datamapper-dm-core 0.9.11 → 0.10.0

data/lib/dm-core/transaction.rb

@@ -1,141 +1,170 @@
-# TODO: move to dm-more/dm-transactions
+# TODO: move to dm-more/dm-transaction
 
 module DataMapper
   class Transaction
+    extend Chainable
 
-    attr_reader :transaction_primitives, :adapters, :state
-
-    #
-    # Create a new DataMapper::Transaction
+    # Create a new Transaction
     #
-    # @see DataMapper::Transaction#link
+    # @see Transaction#link
     #
     # In fact, it just calls #link with the given arguments at the end of the
     # constructor.
     #
+    # @api public
     def initialize(*things)
       @transaction_primitives = {}
       @state = :none
       @adapters = {}
       link(*things)
-      commit { |*block_args| yield(*block_args) } if block_given?
+      if block_given?
+        warn "Passing block to #{self.class.name}.new is deprecated (#{caller[0]})"
+        commit { |*block_args| yield(*block_args) }
+      end
     end
 
-    #
     # Associate this Transaction with some things.
     #
-    # @param things<any number of Object>  the things you want this Transaction
-    #   associated with
-    # @details [things a Transaction may be associatied with]
-    #   DataMapper::Adapters::AbstractAdapter subclasses will be added as
+    # @param [Object] things
+    #   the things you want this Transaction associated with:
+    #
+    #   Adapters::AbstractAdapter subclasses will be added as
     #     adapters as is.
     #   Arrays will have their elements added.
-    #   DataMapper::Repositories will have their @adapters added.
-    #   DataMapper::Resource subclasses will have all the repositories of all
+    #   Repository will have it's own @adapters added.
+    #   Resource subclasses will have all the repositories of all
     #     their properties added.
-    #   DataMapper::Resource instances will have all repositories of all their
+    #   Resource instances will have all repositories of all their
     #     properties added.
-    # @param block<Block> a block (taking one argument, the Transaction) to execute
-    #   within this transaction. The transaction will begin and commit around
+    #
+    # @param [Proc] block
+    #   a block (taking one argument, the Transaction) to execute within
+    #   this transaction. The transaction will begin and commit around
     #   the block, and rollback if an exception is raised.
     #
+    # @api private
     def link(*things)
-      raise "Illegal state for link: #{@state}" unless @state == :none
+      unless @state == :none
+        raise "Illegal state for link: #{@state}"
+      end
+
       things.each do |thing|
-        if thing.is_a?(Array)
-          link(*thing)
-        elsif thing.is_a?(DataMapper::Adapters::AbstractAdapter)
-          @adapters[thing] = :none
-        elsif thing.is_a?(DataMapper::Repository)
-          link(thing.adapter)
-        elsif thing.is_a?(Class) && thing.ancestors.include?(DataMapper::Resource)
-          link(*thing.repositories)
-        elsif thing.is_a?(DataMapper::Resource)
-          link(thing.model)
-        else
-          raise "Unknown argument to #{self}#link: #{thing.inspect}"
+        case thing
+          when DataMapper::Adapters::AbstractAdapter
+            @adapters[thing] = :none
+          when DataMapper::Repository
+            link(thing.adapter)
+          when DataMapper::Model
+            link(*thing.repositories)
+          when DataMapper::Resource
+            link(thing.model)
+          when Array
+            link(*thing)
+          else
+            raise "Unknown argument to #{self.class}#link: #{thing.inspect} (#{thing.class})"
         end
       end
-      return commit { |*block_args| yield(*block_args) } if block_given?
-      return self
+
+      if block_given?
+        commit { |*block_args| yield(*block_args) }
+      else
+        self
+      end
     end
 
-    #
     # Begin the transaction
     #
     # Before #begin is called, the transaction is not valid and can not be used.
     #
+    # @api private
     def begin
-      raise "Illegal state for begin: #{@state}" unless @state == :none
+      unless @state == :none
+        raise "Illegal state for begin: #{@state}"
+      end
+
       each_adapter(:connect_adapter, [:log_fatal_transaction_breakage])
       each_adapter(:begin_adapter, [:rollback_and_close_adapter_if_begin, :close_adapter_if_none])
       @state = :begin
     end
 
-    #
     # Commit the transaction
     #
+    #   If no block is given, it will simply commit any changes made since the
+    #   Transaction did #begin.
+    #
     # @param block<Block>   a block (taking the one argument, the Transaction) to
     #   execute within this transaction. The transaction will begin and commit
     #   around the block, and roll back if an exception is raised.
     #
-    # @note
-    #   If no block is given, it will simply commit any changes made since the
-    #   Transaction did #begin.
-    #
+    # @api private
     def commit
       if block_given?
-        raise "Illegal state for commit with block: #{@state}" unless @state == :none
+        unless @state == :none
+          raise "Illegal state for commit with block: #{@state}"
+        end
+
         begin
           self.begin
           rval = within { |*block_args| yield(*block_args) }
-          self.commit if @state == :begin
+          if @state == :begin
+            self.commit
+          end
           return rval
-        rescue Exception => e
-          self.rollback if @state == :begin
-          raise e
+        rescue Exception => exception
+          if @state == :begin
+            self.rollback
+          end
+          raise exception
         end
       else
-        raise "Illegal state for commit without block: #{@state}" unless @state == :begin
-        each_adapter(:prepare_adapter, [:rollback_and_close_adapter_if_begin, :rollback_prepared_and_close_adapter_if_prepare])
+        unless @state == :begin
+          raise "Illegal state for commit without block: #{@state}"
+        end
         each_adapter(:commit_adapter, [:log_fatal_transaction_breakage])
         each_adapter(:close_adapter, [:log_fatal_transaction_breakage])
         @state = :commit
       end
     end
 
-    #
     # Rollback the transaction
     #
     # Will undo all changes made during the transaction.
     #
+    # @api private
     def rollback
-      raise "Illegal state for rollback: #{@state}" unless @state == :begin
+      unless @state == :begin
+        raise "Illegal state for rollback: #{@state}"
+      end
       each_adapter(:rollback_adapter_if_begin, [:rollback_and_close_adapter_if_begin, :close_adapter_if_none])
-      each_adapter(:rollback_prepared_adapter_if_prepare, [:rollback_prepared_and_close_adapter_if_begin, :close_adapter_if_none])
       each_adapter(:close_adapter_if_open, [:log_fatal_transaction_breakage])
       @state = :rollback
     end
 
-    #
     # Execute a block within this Transaction.
     #
-    # @param block<Block> the block of code to execute.
+    # No #begin, #commit or #rollback is performed in #within, but this
+    # Transaction will pushed on the per thread stack of transactions for each
+    # adapter it is associated with, and it will ensures that it will pop the
+    # Transaction away again after the block is finished.
     #
-    # @note
-    #   No #begin, #commit or #rollback is performed in #within, but this
-    #   Transaction will pushed on the per thread stack of transactions for each
-    #   adapter it is associated with, and it will ensures that it will pop the
-    #   Transaction away again after the block is finished.
+    # @param block<Block> the block of code to execute.
     #
+    # @api private
     def within
-      raise "No block provided" unless block_given?
-      raise "Illegal state for within: #{@state}" unless @state == :begin
+      unless block_given?
+        raise 'No block provided'
+      end
+
+      unless @state == :begin
+        raise "Illegal state for within: #{@state}"
+      end
+
       @adapters.each do |adapter, state|
         adapter.push_transaction(self)
       end
+
       begin
-        return yield(self)
+        yield self
       ensure
         @adapters.each do |adapter, state|
           adapter.pop_transaction
@@ -143,17 +172,23 @@ module DataMapper
       end
     end
 
+    # TODO: document
+    # @api private
     def method_missing(meth, *args, &block)
-      if args.size == 1 && args.first.is_a?(DataMapper::Adapters::AbstractAdapter)
-        if (match = meth.to_s.match(/^(.*)_if_(none|begin|prepare|rollback|commit)$/))
+      if args.size == 1 && args.first.kind_of?(Adapters::AbstractAdapter)
+        if (match = meth.to_s.match(/^(.*)_if_(none|begin|rollback|commit)$/))
           if self.respond_to?(match[1], true)
-            self.send(match[1], args.first) if state_for(args.first).to_s == match[2]
+            if state_for(args.first).to_s == match[2]
+              self.send(match[1], args.first)
+            end
           else
             super
           end
-        elsif (match = meth.to_s.match(/^(.*)_unless_(none|begin|prepare|rollback|commit)$/))
+        elsif (match = meth.to_s.match(/^(.*)_unless_(none|begin|rollback|commit)$/))
           if self.respond_to?(match[1], true)
-            self.send(match[1], args.first) unless state_for(args.first).to_s == match[2]
+            unless state_for(args.first).to_s == match[2]
+              self.send(match[1], args.first)
+            end
           else
             super
           end
@@ -165,103 +200,309 @@ module DataMapper
       end
     end
 
+    # TODO: document
+    # @api private
     def primitive_for(adapter)
-      raise "Unknown adapter #{adapter}" unless @adapters.include?(adapter)
-      raise "No primitive for #{adapter}" unless @transaction_primitives.include?(adapter)
+      unless @adapters.include?(adapter)
+        raise "Unknown adapter #{adapter}"
+      end
+
+      unless @transaction_primitives.include?(adapter)
+        raise "No primitive for #{adapter}"
+      end
+
       @transaction_primitives[adapter]
     end
 
     private
 
+    # TODO: document
+    # @api private
     def validate_primitive(primitive)
-      [:close, :begin, :prepare, :rollback, :rollback_prepared, :commit].each do |meth|
-        raise "Invalid primitive #{primitive}: doesnt respond_to?(#{meth.inspect})" unless primitive.respond_to?(meth)
+      [:close, :begin, :rollback, :commit].each do |meth|
+        unless primitive.respond_to?(meth)
+          raise "Invalid primitive #{primitive}: doesnt respond_to?(#{meth.inspect})"
+        end
       end
-      return primitive
+
+      primitive
     end
 
+    # TODO: document
+    # @api private
     def each_adapter(method, on_fail)
       begin
         @adapters.each do |adapter, state|
           self.send(method, adapter)
         end
-      rescue Exception => e
+      rescue Exception => exception
         @adapters.each do |adapter, state|
           on_fail.each do |fail_handler|
             begin
               self.send(fail_handler, adapter)
-            rescue Exception => e2
-              DataMapper.logger.fatal("#{self}#each_adapter(#{method.inspect}, #{on_fail.inspect}) failed with #{e.inspect}: #{e.backtrace.join("\n")} - and when sending #{fail_handler} to #{adapter} we failed again with #{e2.inspect}: #{e2.backtrace.join("\n")}")
+            rescue Exception => inner_exception
+              DataMapper.logger.fatal("#{self}#each_adapter(#{method.inspect}, #{on_fail.inspect}) failed with #{exception.inspect}: #{exception.backtrace.join("\n")} - and when sending #{fail_handler} to #{adapter} we failed again with #{inner_exception.inspect}: #{inner_exception.backtrace.join("\n")}")
             end
           end
         end
-        raise e
+        raise exception
       end
     end
 
+    # TODO: document
+    # @api private
     def state_for(adapter)
-      raise "Unknown adapter #{adapter}" unless @adapters.include?(adapter)
+      unless @adapters.include?(adapter)
+        raise "Unknown adapter #{adapter}"
+      end
+
       @adapters[adapter]
     end
 
+    # TODO: document
+    # @api private
     def do_adapter(adapter, what, prerequisite)
-      raise "No primitive for #{adapter}" unless @transaction_primitives.include?(adapter)
-      raise "Illegal state for #{what}: #{state_for(adapter)}" unless state_for(adapter) == prerequisite
+      unless @transaction_primitives.include?(adapter)
+        raise "No primitive for #{adapter}"
+      end
+
+      unless state_for(adapter) == prerequisite
+        raise "Illegal state for #{what}: #{state_for(adapter)}"
+      end
+
       DataMapper.logger.debug("#{adapter.name}: #{what}")
       @transaction_primitives[adapter].send(what)
       @adapters[adapter] = what
     end
 
+    # TODO: document
+    # @api private
     def log_fatal_transaction_breakage(adapter)
       DataMapper.logger.fatal("#{self} experienced a totally broken transaction execution. Presenting member #{adapter.inspect}.")
     end
 
+    # TODO: document
+    # @api private
     def connect_adapter(adapter)
-      raise "Already a primitive for adapter #{adapter}" unless @transaction_primitives[adapter].nil?
+      if @transaction_primitives.key?(adapter)
+        raise "Already a primitive for adapter #{adapter}"
+      end
+
       @transaction_primitives[adapter] = validate_primitive(adapter.transaction_primitive)
     end
 
+    # TODO: document
+    # @api private
     def close_adapter_if_open(adapter)
       if @transaction_primitives.include?(adapter)
         close_adapter(adapter)
       end
     end
 
+    # TODO: document
+    # @api private
     def close_adapter(adapter)
-      raise "No primitive for adapter" unless @transaction_primitives.include?(adapter)
+      unless @transaction_primitives.include?(adapter)
+        raise 'No primitive for adapter'
+      end
+
       @transaction_primitives[adapter].close
       @transaction_primitives.delete(adapter)
     end
 
+    # TODO: document
+    # @api private
     def begin_adapter(adapter)
       do_adapter(adapter, :begin, :none)
     end
 
-    def prepare_adapter(adapter)
-      do_adapter(adapter, :prepare, :begin);
-    end
-
+    # TODO: document
+    # @api private
     def commit_adapter(adapter)
-      do_adapter(adapter, :commit, :prepare)
+      do_adapter(adapter, :commit, :begin)
     end
 
+    # TODO: document
+    # @api private
     def rollback_adapter(adapter)
       do_adapter(adapter, :rollback, :begin)
     end
 
-    def rollback_prepared_adapter(adapter)
-      do_adapter(adapter, :rollback_prepared, :prepare)
-    end
-
-    def rollback_prepared_and_close_adapter(adapter)
-      rollback_prepared_adapter(adapter)
-      close_adapter(adapter)
-    end
-
+    # TODO: document
+    # @api private
     def rollback_and_close_adapter(adapter)
       rollback_adapter(adapter)
       close_adapter(adapter)
     end
 
+    module Adapter
+      extend Chainable
+
+      # TODO: document
+      # @api private
+      def self.included(base)
+        [ :Repository, :Model, :Resource ].each do |name|
+          DataMapper.const_get(name).send(:include, Transaction.const_get(name))
+        end
+      end
+
+      # Produces a fresh transaction primitive for this Adapter
+      #
+      # Used by Transaction to perform its various tasks.
+      #
+      # @return [Object]
+      #   a new Object that responds to :close, :begin, :commit,
+      #   and :rollback,
+      #
+      # @api private
+      def transaction_primitive
+        DataObjects::Transaction.create_for_uri(normalized_uri)
+      end
+
+      # Pushes the given Transaction onto the per thread Transaction stack so
+      # that everything done by this Adapter is done within the context of said
+      # Transaction.
+      #
+      # @param [Transaction] transaction
+      #   a Transaction to be the 'current' transaction until popped.
+      #
+      # @return [Array(Transaction)]
+      #   the stack of active transactions for the current thread
+      #
+      # @api private
+      def push_transaction(transaction)
+        transactions << transaction
+      end
+
+      # Pop the 'current' Transaction from the per thread Transaction stack so
+      # that everything done by this Adapter is no longer necessarily within the
+      # context of said Transaction.
+      #
+      # @return [Transaction]
+      #   the former 'current' transaction.
+      #
+      # @api private
+      def pop_transaction
+        transactions.pop
+      end
+
+      # Retrieve the current transaction for this Adapter.
+      #
+      # Everything done by this Adapter is done within the context of this
+      # Transaction.
+      #
+      # @return [Transaction]
+      #   the 'current' transaction for this Adapter.
+      #
+      # @api private
+      def current_transaction
+        transactions.last
+      end
+
+      chainable do
+        protected
+
+        # TODO: document
+        # @api semipublic
+        def open_connection
+          current_connection || super
+        end
+
+        # TODO: document
+        # @api semipublic
+        def close_connection(connection)
+          unless current_connection == connection
+            super
+          end
+        end
+      end
+
+      private
+
+      # TODO: document
+      # @api private
+      def transactions
+        Thread.current[:dm_transactions] ||= []
+      end
+
+      # Retrieve the current connection for this Adapter.
+      #
+      # @return [Transaction]
+      #   the 'current' connection for this Adapter.
+      #
+      # @api private
+      def current_connection
+        if transaction = current_transaction
+          transaction.primitive_for(self).connection
+        end
+      end
+    end # module Adapter
+
+    # alias the MySQL, PostgreSQL, Sqlite3 and Oracle adapters to use transactions
+    MysqlAdapter = PostgresAdapter = Sqlite3Adapter = OracleAdapter = Adapter
+
+    module Repository
+
+      # Produce a new Transaction for this Repository
+      #
+      # @return [Adapters::Transaction]
+      #   a new Transaction (in state :none) that can be used
+      #   to execute code #with_transaction
+      #
+      # @api public
+      def transaction
+        Transaction.new(self)
+      end
+    end # module Repository
+
+    module Model
+      # TODO: document
+      # @api private
+      def self.included(mod)
+        mod.descendants.each { |model| model.extend self }
+      end
+
+      # Produce a new Transaction for this Resource class
+      #
+      # @return <Adapters::Transaction
+      #   a new Adapters::Transaction with all Repositories
+      #   of the class of this Resource added.
+      #
+      # @api public
+      def transaction
+        transaction = Transaction.new(self)
+        transaction.commit { |block_args| yield(*block_args) }
+      end
+    end # module Model
+
+    module Resource
+
+      # Produce a new Transaction for the class of this Resource
+      #
+      # @return [Adapters::Transaction]
+      #   a new Adapters::Transaction for the Repository
+      #   of the class of this Resource added.
+      #
+      # @api public
+      def transaction
+        model.transaction { |*block_args| yield(*block_args) }
+      end
+    end # module Resource
   end # class Transaction
+
+  module Adapters
+    extendable do
+
+      # TODO: document
+      # @api private
+      def const_added(const_name)
+        if Transaction.const_defined?(const_name)
+          adapter = const_get(const_name)
+          adapter.send(:include, Transaction.const_get(const_name))
+        end
+
+        super
+      end
+    end
+  end # module Adapters
 end # module DataMapper