activerecord 3.0.0

data/lib/active_record/callbacks.rb

@@ -0,0 +1,288 @@
+require 'active_support/core_ext/array/wrap'
+
+module ActiveRecord
+  # = Active Record Callbacks
+  #
+  # Callbacks are hooks into the life cycle of an Active Record object that allow you to trigger logic
+  # before or after an alteration of the object state. This can be used to make sure that associated and
+  # dependent objects are deleted when +destroy+ is called (by overwriting +before_destroy+) or to massage attributes
+  # before they're validated (by overwriting +before_validation+). As an example of the callbacks initiated, consider
+  # the <tt>Base#save</tt> call for a new record:
+  #
+  # * (-) <tt>save</tt>
+  # * (-) <tt>valid</tt>
+  # * (1) <tt>before_validation</tt>
+  # * (-) <tt>validate</tt>
+  # * (2) <tt>after_validation</tt>
+  # * (3) <tt>before_save</tt>
+  # * (4) <tt>before_create</tt>
+  # * (-) <tt>create</tt>
+  # * (5) <tt>after_create</tt>
+  # * (6) <tt>after_save</tt>
+  # * (7) <tt>after_commit</tt>
+  #
+  # Also, an <tt>after_rollback</tt> callback can be configured to be triggered whenever a rollback is issued.
+  # Check out <tt>ActiveRecord::Transactions</tt> for more details about <tt>after_commit</tt> and
+  # <tt>after_rollback</tt>.
+  #
+  # That's a total of ten callbacks, which gives you immense power to react and prepare for each state in the
+  # Active Record life cycle. The sequence for calling <tt>Base#save</tt> for an existing record is similar,
+  # except that each <tt>_on_create</tt> callback is replaced by the corresponding <tt>_on_update</tt> callback.
+  #
+  # Examples:
+  #   class CreditCard < ActiveRecord::Base
+  #     # Strip everything but digits, so the user can specify "555 234 34" or
+  #     # "5552-3434" or both will mean "55523434"
+  #     before_validation(:on => :create) do
+  #       self.number = number.gsub(/[^0-9]/, "") if attribute_present?("number")
+  #     end
+  #   end
+  #
+  #   class Subscription < ActiveRecord::Base
+  #     before_create :record_signup
+  #
+  #     private
+  #       def record_signup
+  #         self.signed_up_on = Date.today
+  #       end
+  #   end
+  #
+  #   class Firm < ActiveRecord::Base
+  #     # Destroys the associated clients and people when the firm is destroyed
+  #     before_destroy { |record| Person.destroy_all "firm_id = #{record.id}"   }
+  #     before_destroy { |record| Client.destroy_all "client_of = #{record.id}" }
+  #   end
+  #
+  # == Inheritable callback queues
+  #
+  # Besides the overwritable callback methods, it's also possible to register callbacks through the
+  # use of the callback macros. Their main advantage is that the macros add behavior into a callback
+  # queue that is kept intact down through an inheritance hierarchy.
+  #
+  #   class Topic < ActiveRecord::Base
+  #     before_destroy :destroy_author
+  #   end
+  #
+  #   class Reply < Topic
+  #     before_destroy :destroy_readers
+  #   end
+  #
+  # Now, when <tt>Topic#destroy</tt> is run only +destroy_author+ is called. When <tt>Reply#destroy</tt> is
+  # run, both +destroy_author+ and +destroy_readers+ are called. Contrast this to the following situation
+  # where the +before_destroy+ methis is overriden:
+  #
+  #   class Topic < ActiveRecord::Base
+  #     def before_destroy() destroy_author end
+  #   end
+  #
+  #   class Reply < Topic
+  #     def before_destroy() destroy_readers end
+  #   end
+  #
+  # In that case, <tt>Reply#destroy</tt> would only run +destroy_readers+ and _not_ +destroy_author+.
+  # So, use the callback macros when you want to ensure that a certain callback is called for the entire
+  # hierarchy, and use the regular overwriteable methods when you want to leave it up to each descendant
+  # to decide whether they want to call +super+ and trigger the inherited callbacks.
+  #
+  # *IMPORTANT:* In order for inheritance to work for the callback queues, you must specify the
+  # callbacks before specifying the associations. Otherwise, you might trigger the loading of a
+  # child before the parent has registered the callbacks and they won't be inherited.
+  #
+  # == Types of callbacks
+  #
+  # There are four types of callbacks accepted by the callback macros: Method references (symbol), callback objects,
+  # inline methods (using a proc), and inline eval methods (using a string). Method references and callback objects
+  # are the recommended approaches, inline methods using a proc are sometimes appropriate (such as for
+  # creating mix-ins), and inline eval methods are deprecated.
+  #
+  # The method reference callbacks work by specifying a protected or private method available in the object, like this:
+  #
+  #   class Topic < ActiveRecord::Base
+  #     before_destroy :delete_parents
+  #
+  #     private
+  #       def delete_parents
+  #         self.class.delete_all "parent_id = #{id}"
+  #       end
+  #   end
+  #
+  # The callback objects have methods named after the callback called with the record as the only parameter, such as:
+  #
+  #   class BankAccount < ActiveRecord::Base
+  #     before_save      EncryptionWrapper.new
+  #     after_save       EncryptionWrapper.new
+  #     after_initialize EncryptionWrapper.new
+  #   end
+  #
+  #   class EncryptionWrapper
+  #     def before_save(record)
+  #       record.credit_card_number = encrypt(record.credit_card_number)
+  #     end
+  #
+  #     def after_save(record)
+  #       record.credit_card_number = decrypt(record.credit_card_number)
+  #     end
+  #
+  #     alias_method :after_find, :after_save
+  #
+  #     private
+  #       def encrypt(value)
+  #         # Secrecy is committed
+  #       end
+  #
+  #       def decrypt(value)
+  #         # Secrecy is unveiled
+  #       end
+  #   end
+  #
+  # So you specify the object you want messaged on a given callback. When that callback is triggered, the object has
+  # a method by the name of the callback messaged. You can make these callbacks more flexible by passing in other
+  # initialization data such as the name of the attribute to work with:
+  #
+  #   class BankAccount < ActiveRecord::Base
+  #     before_save      EncryptionWrapper.new("credit_card_number")
+  #     after_save       EncryptionWrapper.new("credit_card_number")
+  #     after_initialize EncryptionWrapper.new("credit_card_number")
+  #   end
+  #
+  #   class EncryptionWrapper
+  #     def initialize(attribute)
+  #       @attribute = attribute
+  #     end
+  #
+  #     def before_save(record)
+  #       record.send("#{@attribute}=", encrypt(record.send("#{@attribute}")))
+  #     end
+  #
+  #     def after_save(record)
+  #       record.send("#{@attribute}=", decrypt(record.send("#{@attribute}")))
+  #     end
+  #
+  #     alias_method :after_find, :after_save
+  #
+  #     private
+  #       def encrypt(value)
+  #         # Secrecy is committed
+  #       end
+  #
+  #       def decrypt(value)
+  #         # Secrecy is unveiled
+  #       end
+  #   end
+  #
+  # The callback macros usually accept a symbol for the method they're supposed to run, but you can also
+  # pass a "method string", which will then be evaluated within the binding of the callback. Example:
+  #
+  #   class Topic < ActiveRecord::Base
+  #     before_destroy 'self.class.delete_all "parent_id = #{id}"'
+  #   end
+  #
+  # Notice that single quotes (') are used so the <tt>#{id}</tt> part isn't evaluated until the callback
+  # is triggered. Also note that these inline callbacks can be stacked just like the regular ones:
+  #
+  #   class Topic < ActiveRecord::Base
+  #     before_destroy 'self.class.delete_all "parent_id = #{id}"',
+  #                    'puts "Evaluated after parents are destroyed"'
+  #   end
+  #
+  # == The +after_find+ and +after_initialize+ exceptions
+  #
+  # Because +after_find+ and +after_initialize+ are called for each object found and instantiated by a finder,
+  # such as <tt>Base.find(:all)</tt>, we've had to implement a simple performance constraint (50% more speed
+  # on a simple test case). Unlike all the other callbacks, +after_find+ and +after_initialize+ will only be
+  # run if an explicit implementation is defined (<tt>def after_find</tt>). In that case, all of the
+  # callback types will be called.
+  #
+  # == <tt>before_validation*</tt> returning statements
+  #
+  # If the returning value of a +before_validation+ callback can be evaluated to +false+, the process will be
+  # aborted and <tt>Base#save</tt> will return +false+. If Base#save! is called it will raise a
+  # ActiveRecord::RecordInvalid exception. Nothing will be appended to the errors object.
+  #
+  # == Canceling callbacks
+  #
+  # If a <tt>before_*</tt> callback returns +false+, all the later callbacks and the associated action are
+  # cancelled. If an <tt>after_*</tt> callback returns +false+, all the later callbacks are cancelled.
+  # Callbacks are generally run in the order they are defined, with the exception of callbacks defined as
+  # methods on the model, which are called last.
+  #
+  # == Transactions
+  #
+  # The entire callback chain of a +save+, <tt>save!</tt>, or +destroy+ call runs
+  # within a transaction. That includes <tt>after_*</tt> hooks. If everything
+  # goes fine a COMMIT is executed once the chain has been completed.
+  #
+  # If a <tt>before_*</tt> callback cancels the action a ROLLBACK is issued. You
+  # can also trigger a ROLLBACK raising an exception in any of the callbacks,
+  # including <tt>after_*</tt> hooks. Note, however, that in that case the client
+  # needs to be aware of it because an ordinary +save+ will raise such exception
+  # instead of quietly returning +false+.
+  #
+  # == Debugging callbacks
+  #
+  # To list the methods and procs registered with a particular callback, append <tt>_callback_chain</tt> to
+  # the callback name that you wish to list and send that to your class from the Rails console:
+  #
+  #   >> Topic.after_save_callback_chain
+  #   => [#<ActiveSupport::Callbacks::Callback:0x3f6a448
+  #       @method=#<Proc:0x03f9a42c@/Users/foo/bar/app/models/topic.rb:43>, kind:after_save, identifiernil,
+  #       options{}]
+  #
+  module Callbacks
+    extend ActiveSupport::Concern
+
+    CALLBACKS = [
+      :after_initialize, :after_find, :after_touch, :before_validation, :after_validation,
+      :before_save, :around_save, :after_save, :before_create, :around_create,
+      :after_create, :before_update, :around_update, :after_update,
+      :before_destroy, :around_destroy, :after_destroy, :after_commit, :after_rollback
+    ]
+
+    included do
+      extend ActiveModel::Callbacks
+      include ActiveModel::Validations::Callbacks
+
+      define_model_callbacks :initialize, :find, :touch, :only => :after
+      define_model_callbacks :save, :create, :update, :destroy
+    end
+
+    module ClassMethods
+      def method_added(meth)
+        super
+        if CALLBACKS.include?(meth.to_sym)
+          ActiveSupport::Deprecation.warn("Base##{meth} has been deprecated, please use Base.#{meth} :method instead", caller[0,1])
+          send(meth.to_sym, meth.to_sym)
+        end
+      end
+    end
+
+    def destroy #:nodoc:
+      _run_destroy_callbacks { super }
+    end
+
+    def touch(*) #:nodoc:
+      _run_touch_callbacks { super }
+    end
+
+    def deprecated_callback_method(symbol) #:nodoc:
+      if respond_to?(symbol, true)
+        ActiveSupport::Deprecation.warn("Overwriting #{symbol} in your models has been deprecated, please use Base##{symbol} :method_name instead")
+        send(symbol)
+      end
+    end
+
+  private
+
+    def create_or_update #:nodoc:
+      _run_save_callbacks { super }
+    end
+
+    def create #:nodoc:
+      _run_create_callbacks { super }
+    end
+
+    def update(*) #:nodoc:
+      _run_update_callbacks { super }
+    end
+  end
+end

data/lib/active_record/connection_adapters/abstract/connection_pool.rb

@@ -0,0 +1,365 @@
+require 'monitor'
+require 'set'
+require 'active_support/core_ext/module/synchronization'
+
+module ActiveRecord
+  # Raised when a connection could not be obtained within the connection
+  # acquisition timeout period.
+  class ConnectionTimeoutError < ConnectionNotEstablished
+  end
+
+  module ConnectionAdapters
+    # Connection pool base class for managing Active Record database
+    # connections.
+    #
+    # == Introduction
+    #
+    # A connection pool synchronizes thread access to a limited number of
+    # database connections. The basic idea is that each thread checks out a
+    # database connection from the pool, uses that connection, and checks the
+    # connection back in. ConnectionPool is completely thread-safe, and will
+    # ensure that a connection cannot be used by two threads at the same time,
+    # as long as ConnectionPool's contract is correctly followed. It will also
+    # handle cases in which there are more threads than connections: if all
+    # connections have been checked out, and a thread tries to checkout a
+    # connection anyway, then ConnectionPool will wait until some other thread
+    # has checked in a connection.
+    #
+    # == Obtaining (checking out) a connection
+    #
+    # Connections can be obtained and used from a connection pool in several
+    # ways:
+    #
+    # 1. Simply use ActiveRecord::Base.connection as with Active Record 2.1 and
+    #    earlier (pre-connection-pooling). Eventually, when you're done with
+    #    the connection(s) and wish it to be returned to the pool, you call
+    #    ActiveRecord::Base.clear_active_connections!. This will be the
+    #    default behavior for Active Record when used in conjunction with
+    #    Action Pack's request handling cycle.
+    # 2. Manually check out a connection from the pool with
+    #    ActiveRecord::Base.connection_pool.checkout. You are responsible for
+    #    returning this connection to the pool when finished by calling
+    #    ActiveRecord::Base.connection_pool.checkin(connection).
+    # 3. Use ActiveRecord::Base.connection_pool.with_connection(&block), which
+    #    obtains a connection, yields it as the sole argument to the block,
+    #    and returns it to the pool after the block completes.
+    #
+    # Connections in the pool are actually AbstractAdapter objects (or objects
+    # compatible with AbstractAdapter's interface).
+    #
+    # == Options
+    #
+    # There are two connection-pooling-related options that you can add to
+    # your database connection configuration:
+    #
+    # * +pool+: number indicating size of connection pool (default 5)
+    # * +wait_timeout+: number of seconds to block and wait for a connection
+    #   before giving up and raising a timeout error (default 5 seconds).
+    class ConnectionPool
+      attr_reader :spec, :connections
+
+      # Creates a new ConnectionPool object. +spec+ is a ConnectionSpecification
+      # object which describes database connection information (e.g. adapter,
+      # host name, username, password, etc), as well as the maximum size for
+      # this ConnectionPool.
+      #
+      # The default ConnectionPool maximum size is 5.
+      def initialize(spec)
+        @spec = spec
+
+        # The cache of reserved connections mapped to threads
+        @reserved_connections = {}
+
+        # The mutex used to synchronize pool access
+        @connection_mutex = Monitor.new
+        @queue = @connection_mutex.new_cond
+
+        # default 5 second timeout unless on ruby 1.9
+        @timeout =
+          if RUBY_VERSION < '1.9'
+            spec.config[:wait_timeout] || 5
+          end
+
+        # default max pool size to 5
+        @size = (spec.config[:pool] && spec.config[:pool].to_i) || 5
+
+        @connections = []
+        @checked_out = []
+      end
+
+      # Retrieve the connection associated with the current thread, or call
+      # #checkout to obtain one if necessary.
+      #
+      # #connection can be called any number of times; the connection is
+      # held in a hash keyed by the thread id.
+      def connection
+        @reserved_connections[current_connection_id] ||= checkout
+      end
+
+      # Signal that the thread is finished with the current connection.
+      # #release_connection releases the connection-thread association
+      # and returns the connection to the pool.
+      def release_connection(with_id = current_connection_id)
+        conn = @reserved_connections.delete(with_id)
+        checkin conn if conn
+      end
+
+      # If a connection already exists yield it to the block.  If no connection
+      # exists checkout a connection, yield it to the block, and checkin the
+      # connection when finished.
+      def with_connection
+        connection_id = current_connection_id
+        fresh_connection = true unless @reserved_connections[connection_id]
+        yield connection
+      ensure
+        release_connection(connection_id) if fresh_connection
+      end
+
+      # Returns true if a connection has already been opened.
+      def connected?
+        !@connections.empty?
+      end
+
+      # Disconnects all connections in the pool, and clears the pool.
+      def disconnect!
+        @reserved_connections.each do |name,conn|
+          checkin conn
+        end
+        @reserved_connections = {}
+        @connections.each do |conn|
+          conn.disconnect!
+        end
+        @connections = []
+      end
+
+      # Clears the cache which maps classes
+      def clear_reloadable_connections!
+        @reserved_connections.each do |name, conn|
+          checkin conn
+        end
+        @reserved_connections = {}
+        @connections.each do |conn|
+          conn.disconnect! if conn.requires_reloading?
+        end
+        @connections.delete_if do |conn|
+          conn.requires_reloading?
+        end
+      end
+
+      # Verify active connections and remove and disconnect connections
+      # associated with stale threads.
+      def verify_active_connections! #:nodoc:
+        clear_stale_cached_connections!
+        @connections.each do |connection|
+          connection.verify!
+        end
+      end
+
+      # Return any checked-out connections back to the pool by threads that
+      # are no longer alive.
+      def clear_stale_cached_connections!
+        keys = @reserved_connections.keys - Thread.list.find_all { |t|
+          t.alive?
+        }.map { |thread| thread.object_id }
+
+        keys.each do |key|
+          checkin @reserved_connections[key]
+          @reserved_connections.delete(key)
+        end
+      end
+
+      # Check-out a database connection from the pool, indicating that you want
+      # to use it. You should call #checkin when you no longer need this.
+      #
+      # This is done by either returning an existing connection, or by creating
+      # a new connection. If the maximum number of connections for this pool has
+      # already been reached, but the pool is empty (i.e. they're all being used),
+      # then this method will wait until a thread has checked in a connection.
+      # The wait time is bounded however: if no connection can be checked out
+      # within the timeout specified for this pool, then a ConnectionTimeoutError
+      # exception will be raised.
+      #
+      # Returns: an AbstractAdapter object.
+      #
+      # Raises:
+      # - ConnectionTimeoutError: no connection can be obtained from the pool
+      #   within the timeout period.
+      def checkout
+        # Checkout an available connection
+        @connection_mutex.synchronize do
+          loop do
+            conn = if @checked_out.size < @connections.size
+                     checkout_existing_connection
+                   elsif @connections.size < @size
+                     checkout_new_connection
+                   end
+            return conn if conn
+            # No connections available; wait for one
+            if @queue.wait(@timeout)
+              next
+            else
+              # try looting dead threads
+              clear_stale_cached_connections!
+              if @size == @checked_out.size
+                raise ConnectionTimeoutError, "could not obtain a database connection#{" within #{@timeout} seconds" if @timeout}.  The max pool size is currently #{@size}; consider increasing it."
+              end
+            end
+          end
+        end
+      end
+
+      # Check-in a database connection back into the pool, indicating that you
+      # no longer need this connection.
+      #
+      # +conn+: an AbstractAdapter object, which was obtained by earlier by
+      # calling +checkout+ on this pool.
+      def checkin(conn)
+        @connection_mutex.synchronize do
+          conn.send(:_run_checkin_callbacks) do
+            @checked_out.delete conn
+            @queue.signal
+          end
+        end
+      end
+
+      synchronize :clear_reloadable_connections!, :verify_active_connections!,
+        :connected?, :disconnect!, :with => :@connection_mutex
+
+      private
+      def new_connection
+        ActiveRecord::Base.send(spec.adapter_method, spec.config)
+      end
+
+      def current_connection_id #:nodoc:
+        Thread.current.object_id
+      end
+
+      def checkout_new_connection
+        c = new_connection
+        @connections << c
+        checkout_and_verify(c)
+      end
+
+      def checkout_existing_connection
+        c = (@connections - @checked_out).first
+        checkout_and_verify(c)
+      end
+
+      def checkout_and_verify(c)
+        c.run_callbacks :checkout do
+          c.verify!
+          @checked_out << c
+        end
+        c
+      end
+    end
+
+    # ConnectionHandler is a collection of ConnectionPool objects. It is used
+    # for keeping separate connection pools for Active Record models that connect
+    # to different databases.
+    #
+    # For example, suppose that you have 5 models, with the following hierarchy:
+    #
+    #  |
+    #  +-- Book
+    #  |    |
+    #  |    +-- ScaryBook
+    #  |    +-- GoodBook
+    #  +-- Author
+    #  +-- BankAccount
+    #
+    # Suppose that Book is to connect to a separate database (i.e. one other
+    # than the default database). Then Book, ScaryBook and GoodBook will all use
+    # the same connection pool. Likewise, Author and BankAccount will use the
+    # same connection pool. However, the connection pool used by Author/BankAccount
+    # is not the same as the one used by Book/ScaryBook/GoodBook.
+    #
+    # Normally there is only a single ConnectionHandler instance, accessible via
+    # ActiveRecord::Base.connection_handler. Active Record models use this to
+    # determine that connection pool that they should use.
+    class ConnectionHandler
+      attr_reader :connection_pools
+
+      def initialize(pools = {})
+        @connection_pools = pools
+      end
+
+      def establish_connection(name, spec)
+        @connection_pools[name] = ConnectionAdapters::ConnectionPool.new(spec)
+      end
+
+      # Returns any connections in use by the current thread back to the pool,
+      # and also returns connections to the pool cached by threads that are no
+      # longer alive.
+      def clear_active_connections!
+        @connection_pools.each_value {|pool| pool.release_connection }
+      end
+
+      # Clears the cache which maps classes
+      def clear_reloadable_connections!
+        @connection_pools.each_value {|pool| pool.clear_reloadable_connections! }
+      end
+
+      def clear_all_connections!
+        @connection_pools.each_value {|pool| pool.disconnect! }
+      end
+
+      # Verify active connections.
+      def verify_active_connections! #:nodoc:
+        @connection_pools.each_value {|pool| pool.verify_active_connections! }
+      end
+
+      # Locate the connection of the nearest super class. This can be an
+      # active or defined connection: if it is the latter, it will be
+      # opened and set as the active connection for the class it was defined
+      # for (not necessarily the current class).
+      def retrieve_connection(klass) #:nodoc:
+        pool = retrieve_connection_pool(klass)
+        (pool && pool.connection) or raise ConnectionNotEstablished
+      end
+
+      # Returns true if a connection that's accessible to this class has
+      # already been opened.
+      def connected?(klass)
+        conn = retrieve_connection_pool(klass)
+        conn && conn.connected?
+      end
+
+      # Remove the connection for this class. This will close the active
+      # connection and the defined connection (if they exist). The result
+      # can be used as an argument for establish_connection, for easily
+      # re-establishing the connection.
+      def remove_connection(klass)
+        pool = @connection_pools[klass.name]
+        return nil unless pool
+
+        @connection_pools.delete_if { |key, value| value == pool }
+        pool.disconnect!
+        pool.spec.config
+      end
+
+      def retrieve_connection_pool(klass)
+        pool = @connection_pools[klass.name]
+        return pool if pool
+        return nil if ActiveRecord::Base == klass
+        retrieve_connection_pool klass.superclass
+      end
+    end
+
+    class ConnectionManagement
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        @app.call(env)
+      ensure
+        # Don't return connection (and perform implicit rollback) if
+        # this request is a part of integration test
+        unless env.key?("rack.test")
+          ActiveRecord::Base.clear_active_connections!
+        end
+      end
+    end
+  end
+end