activerecord 2.1.2 → 2.2.2

data/lib/active_record/associations/association_collection.rb

@@ -2,6 +2,19 @@ require 'set'
 
 module ActiveRecord
   module Associations
+    # AssociationCollection is an abstract class that provides common stuff to
+    # ease the implementation of association proxies that represent
+    # collections. See the class hierarchy in AssociationProxy.
+    #
+    # You need to be careful with assumptions regarding the target: The proxy
+    # does not fetch records from the database until it needs them, but new
+    # ones created with +build+ are added to the target. So, the target may be
+    # non-empty and still lack children waiting to be read from the database.
+    # If you look directly to the database you cannot assume that's the entire
+    # collection because new records may have beed added to the target, etc.
+    #
+    # If you need to work on all current children, new and existing records,
+    # +load_target+ and the +loaded+ flag are your friends.
     class AssociationCollection < AssociationProxy #:nodoc:
       def initialize(owner, reflection)
         super
@@ -14,7 +27,7 @@ module ActiveRecord
         # If using a custom finder_sql, scan the entire collection.
         if @reflection.options[:finder_sql]
           expects_array = args.first.kind_of?(Array)
-          ids           = args.flatten.compact.uniq.map(&:to_i)
+          ids           = args.flatten.compact.uniq.map { |arg| arg.to_i }
 
           if ids.size == 1
             id = ids.first
@@ -50,7 +63,7 @@ module ActiveRecord
       
       # Fetches the first one using SQL if possible.
       def first(*args)
-        if fetch_first_or_last_using_find? args
+        if fetch_first_or_last_using_find?(args)
           find(:first, *args)
         else
           load_target unless loaded?
@@ -60,7 +73,7 @@ module ActiveRecord
 
       # Fetches the last one using SQL if possible.
       def last(*args)
-        if fetch_first_or_last_using_find? args
+        if fetch_first_or_last_using_find?(args)
           find(:last, *args)
         else
           load_target unless loaded?
@@ -95,7 +108,7 @@ module ActiveRecord
         result = true
         load_target if @owner.new_record?
 
-        @owner.transaction do
+        transaction do
           flatten_deeper(records).each do |record|
             raise_on_type_mismatch(record)
             add_record_to_target_with_callbacks(record) do |r|
@@ -110,6 +123,21 @@ module ActiveRecord
       alias_method :push, :<<
       alias_method :concat, :<<
 
+      # Starts a transaction in the association class's database connection.
+      #
+      #   class Author < ActiveRecord::Base
+      #     has_many :books
+      #   end
+      #
+      #   Author.find(:first).books.transaction do
+      #     # same effect as calling Book.transaction
+      #   end
+      def transaction(*args)
+        @reflection.klass.transaction(*args) do
+          yield
+        end
+      end
+
       # Remove all records from this association
       def delete_all
         load_target
@@ -126,12 +154,47 @@ module ActiveRecord
         end
       end
 
-      # Remove +records+ from this association.  Does not destroy +records+.
+      # Count all records using SQL. If the +:counter_sql+ option is set for the association, it will
+      # be used for the query. If no +:counter_sql+ was supplied, but +:finder_sql+ was set, the
+      # descendant's +construct_sql+ method will have set :counter_sql automatically.
+      # Otherwise, construct options and pass them with scope to the target class's +count+.
+      def count(*args)
+        if @reflection.options[:counter_sql]
+          @reflection.klass.count_by_sql(@counter_sql)
+        else
+          column_name, options = @reflection.klass.send(:construct_count_options_from_args, *args)
+          if @reflection.options[:uniq]
+            # This is needed because 'SELECT count(DISTINCT *)..' is not valid SQL.
+            column_name = "#{@reflection.quoted_table_name}.#{@reflection.klass.primary_key}" if column_name == :all
+            options.merge!(:distinct => true)
+          end
+
+          value = @reflection.klass.send(:with_scope, construct_scope) { @reflection.klass.count(column_name, options) }
+
+          limit  = @reflection.options[:limit]
+          offset = @reflection.options[:offset]
+
+          if limit || offset
+            [ [value - offset.to_i, 0].max, limit.to_i ].min
+          else
+            value
+          end
+        end
+      end
+
+
+      # Removes +records+ from this association calling +before_remove+ and
+      # +after_remove+ callbacks.
+      #
+      # This method is abstract in the sense that +delete_records+ has to be
+      # provided by descendants. Note this method does not imply the records
+      # are actually removed from the database, that depends precisely on
+      # +delete_records+. They are in any case removed from the collection.
       def delete(*records)
         records = flatten_deeper(records)
         records.each { |record| raise_on_type_mismatch(record) }
         
-        @owner.transaction do
+        transaction do
           records.each { |record| callback(:before_remove, record) }
           
           old_records = records.reject {|r| r.new_record? }
@@ -158,7 +221,7 @@ module ActiveRecord
       end
       
       def destroy_all
-        @owner.transaction do
+        transaction do
           each { |record| record.destroy }
         end
 
@@ -183,12 +246,21 @@ module ActiveRecord
         end
       end
 
-      # Returns the size of the collection by executing a SELECT COUNT(*) query if the collection hasn't been loaded and
-      # calling collection.size if it has. If it's more likely than not that the collection does have a size larger than zero
-      # and you need to fetch that collection afterwards, it'll take one less SELECT query if you use length.
+      # Returns the size of the collection by executing a SELECT COUNT(*)
+      # query if the collection hasn't been loaded, and calling
+      # <tt>collection.size</tt> if it has.
+      #
+      # If the collection has been already loaded +size+ and +length+ are
+      # equivalent. If not and you are going to need the records anyway
+      # +length+ will take one less query. Otherwise +size+ is more efficient.
+      #
+      # This method is abstract in the sense that it relies on
+      # +count_records+, which is a method descendants have to provide.
       def size
         if @owner.new_record? || (loaded? && !@reflection.options[:uniq])
           @target.size
+        elsif !loaded? && @reflection.options[:group]
+          load_target.size
         elsif !loaded? && !@reflection.options[:uniq] && @target.is_a?(Array)
           unsaved_records = @target.select { |r| r.new_record? }
           unsaved_records.size + count_records
@@ -197,12 +269,18 @@ module ActiveRecord
         end
       end
 
-      # Returns the size of the collection by loading it and calling size on the array. If you want to use this method to check
-      # whether the collection is empty, use collection.length.zero? instead of collection.empty?
+      # Returns the size of the collection calling +size+ on the target.
+      #
+      # If the collection has been already loaded +length+ and +size+ are
+      # equivalent. If not and you are going to need the records anyway this
+      # method will take one less query. Otherwise +size+ is more efficient.
       def length
         load_target.size
       end
 
+      # Equivalent to <tt>collection.size.zero?</tt>. If the collection has
+      # not been already loaded and you are going to fetch the records anyway
+      # it is better to check <tt>collection.length.zero?</tt>.
       def empty?
         size.zero?
       end
@@ -235,7 +313,7 @@ module ActiveRecord
         other   = other_array.size < 100 ? other_array : other_array.to_set
         current = @target.size < 100 ? @target : @target.to_set
 
-        @owner.transaction do
+        transaction do
           delete(@target.select { |v| !other.include?(v) })
           concat(other_array.select { |v| !current.include?(v) })
         end
@@ -248,6 +326,10 @@ module ActiveRecord
         exists?(record)
       end
 
+      def proxy_respond_to?(method, include_private = false)
+        super || @reflection.klass.respond_to?(method, include_private)
+      end
+
       protected
         def construct_find_options!(options)
         end
@@ -316,7 +398,9 @@ module ActiveRecord
         def create_record(attrs)
           attrs.update(@reflection.options[:conditions]) if @reflection.options[:conditions].is_a?(Hash)
           ensure_owner_is_not_new
-          record = @reflection.klass.send(:with_scope, :create => construct_scope[:create]) { @reflection.klass.new(attrs) }
+          record = @reflection.klass.send(:with_scope, :create => construct_scope[:create]) do
+            @reflection.build_association(attrs)
+          end
           if block_given?
             add_record_to_target_with_callbacks(record) { |*block_args| yield(*block_args) }
           else
@@ -326,7 +410,7 @@ module ActiveRecord
 
         def build_record(attrs)
           attrs.update(@reflection.options[:conditions]) if @reflection.options[:conditions].is_a?(Hash)
-          record = @reflection.klass.new(attrs)
+          record = @reflection.build_association(attrs)
           if block_given?
             add_record_to_target_with_callbacks(record) { |*block_args| yield(*block_args) }
           else
@@ -361,7 +445,8 @@ module ActiveRecord
         end
 
         def fetch_first_or_last_using_find?(args)
-          args.first.kind_of?(Hash) || !(loaded? || @owner.new_record? || @reflection.options[:finder_sql] || !@target.blank? || args.first.kind_of?(Integer))
+          args.first.kind_of?(Hash) || !(loaded? || @owner.new_record? || @reflection.options[:finder_sql] ||
+                                         @target.any? { |record| record.new_record? } || args.first.kind_of?(Integer))
         end
     end
   end

data/lib/active_record/associations/association_proxy.rb

@@ -39,7 +39,7 @@ module ActiveRecord
     # though the object behind <tt>blog.posts</tt> is not an Array, but an
     # ActiveRecord::Associations::HasManyAssociation.
     #
-    # The <tt>@target</tt> object is not loaded until needed. For example,
+    # The <tt>@target</tt> object is not \loaded until needed. For example,
     #
     #   blog.posts.count
     #
@@ -57,76 +57,109 @@ module ActiveRecord
         reset
       end
 
+      # Returns the owner of the proxy.
       def proxy_owner
         @owner
       end
 
+      # Returns the reflection object that represents the association handled
+      # by the proxy.
       def proxy_reflection
         @reflection
       end
 
+      # Returns the \target of the proxy, same as +target+.
       def proxy_target
         @target
       end
 
+      # Does the proxy or its \target respond to +symbol+?
       def respond_to?(*args)
         proxy_respond_to?(*args) || (load_target && @target.respond_to?(*args))
       end
 
-      # Explicitly proxy === because the instance method removal above
-      # doesn't catch it.
+      # Forwards <tt>===</tt> explicitly to the \target because the instance method
+      # removal above doesn't catch it. Loads the \target if needed.
       def ===(other)
         load_target
         other === @target
       end
 
+      # Returns the name of the table of the related class:
+      #
+      #   post.comments.aliased_table_name # => "comments"
+      #
       def aliased_table_name
         @reflection.klass.table_name
       end
 
+      # Returns the SQL string that corresponds to the <tt>:conditions</tt>
+      # option of the macro, if given, or +nil+ otherwise.
       def conditions
-        @conditions ||= interpolate_sql(sanitize_sql(@reflection.options[:conditions])) if @reflection.options[:conditions]
+        @conditions ||= interpolate_sql(@reflection.sanitized_conditions) if @reflection.sanitized_conditions
       end
       alias :sql_conditions :conditions
 
+      # Resets the \loaded flag to +false+ and sets the \target to +nil+.
       def reset
         @loaded = false
         @target = nil
       end
 
+      # Reloads the \target and returns +self+ on success.
       def reload
         reset
         load_target
         self unless @target.nil?
       end
 
+      # Has the \target been already \loaded?
       def loaded?
         @loaded
       end
 
+      # Asserts the \target has been loaded setting the \loaded flag to +true+.
       def loaded
         @loaded = true
       end
 
+      # Returns the target of this proxy, same as +proxy_target+.
       def target
         @target
       end
 
+      # Sets the target of this proxy to <tt>\target</tt>, and the \loaded flag to +true+.
       def target=(target)
         @target = target
         loaded
       end
 
+      # Forwards the call to the target. Loads the \target if needed.
       def inspect
         load_target
         @target.inspect
       end
 
+      def send(method, *args)
+        if proxy_respond_to?(method)
+          super
+        else
+          load_target
+          @target.send(method, *args)
+        end
+      end
+
       protected
+        # Does the association have a <tt>:dependent</tt> option?
         def dependent?
           @reflection.options[:dependent]
         end
 
+        # Returns a string with the IDs of +records+ joined with a comma, quoted
+        # if needed. The result is ready to be inserted into a SQL IN clause.
+        #
+        #   quoted_record_ids(records) # => "23,56,58,67"
+        #
         def quoted_record_ids(records)
           records.map { |record| record.quoted_id }.join(',')
         end
@@ -135,10 +168,13 @@ module ActiveRecord
           @owner.send(:interpolate_sql, sql, record)
         end
 
+        # Forwards the call to the reflection class.
         def sanitize_sql(sql)
           @reflection.klass.send(:sanitize_sql, sql)
         end
 
+        # Assigns the ID of the owner to the corresponding foreign key in +record+.
+        # If the association is polymorphic the type of the owner is also set.
         def set_belongs_to_association_for(record)
           if @reflection.options[:as]
             record["#{@reflection.options[:as]}_id"]   = @owner.id unless @owner.new_record?
@@ -148,6 +184,7 @@ module ActiveRecord
           end
         end
 
+        # Merges into +options+ the ones coming from the reflection.
         def merge_options_from_reflection!(options)
           options.reverse_merge!(
             :group   => @reflection.options[:group],
@@ -160,13 +197,17 @@ module ActiveRecord
           )
         end
 
+        # Forwards +with_scope+ to the reflection.
         def with_scope(*args, &block)
           @reflection.klass.send :with_scope, *args, &block
         end
 
       private
+        # Forwards any missing method call to the \target.
         def method_missing(method, *args)
           if load_target
+            raise NoMethodError unless @target.respond_to?(method)
+
             if block_given?
               @target.send(method, *args)  { |*block_args| yield(*block_args) }
             else
@@ -175,16 +216,16 @@ module ActiveRecord
           end
         end
 
-        # Loads the target if needed and returns it.
+        # Loads the \target if needed and returns it.
         #
         # This method is abstract in the sense that it relies on +find_target+,
         # which is expected to be provided by descendants.
         #
-        # If the target is already loaded it is just returned. Thus, you can call
-        # +load_target+ unconditionally to get the target.
+        # If the \target is already \loaded it is just returned. Thus, you can call
+        # +load_target+ unconditionally to get the \target.
         #
         # ActiveRecord::RecordNotFound is rescued within the method, and it is
-        # not reraised. The proxy is reset and +nil+ is the return value.
+        # not reraised. The proxy is \reset and +nil+ is the return value.
         def load_target
           return nil unless defined?(@loaded)
 
@@ -198,22 +239,33 @@ module ActiveRecord
           reset
         end
 
-        # Can be overwritten by associations that might have the foreign key available for an association without
-        # having the object itself (and still being a new record). Currently, only belongs_to presents this scenario.
+        # Can be overwritten by associations that might have the foreign key
+        # available for an association without having the object itself (and
+        # still being a new record). Currently, only +belongs_to+ presents
+        # this scenario (both vanilla and polymorphic).
         def foreign_key_present
           false
         end
 
+        # Raises ActiveRecord::AssociationTypeMismatch unless +record+ is of
+        # the kind of the class of the associated objects. Meant to be used as
+        # a sanity check when you are about to assign an associated record.
         def raise_on_type_mismatch(record)
-          unless record.is_a?(@reflection.klass)
+          unless record.is_a?(@reflection.klass) || record.is_a?(@reflection.class_name.constantize)
             message = "#{@reflection.class_name}(##{@reflection.klass.object_id}) expected, got #{record.class}(##{record.class.object_id})"
             raise ActiveRecord::AssociationTypeMismatch, message
           end
         end
 
-        # Array#flatten has problems with recursive arrays. Going one level deeper solves the majority of the problems.
+        # Array#flatten has problems with recursive arrays. Going one level
+        # deeper solves the majority of the problems.
         def flatten_deeper(array)
-          array.collect { |element| element.respond_to?(:flatten) ? element.flatten : element }.flatten
+          array.collect { |element| (element.respond_to?(:flatten) && !element.is_a?(Hash)) ? element.flatten : element }.flatten
+        end
+
+        # Returns the ID of the owner, quoted if needed.
+        def owner_quoted_id
+          @owner.quoted_id
         end
     end
   end

data/lib/active_record/associations/belongs_to_association.rb

@@ -2,11 +2,11 @@ module ActiveRecord
   module Associations
     class BelongsToAssociation < AssociationProxy #:nodoc:
       def create(attributes = {})
-        replace(@reflection.klass.create(attributes))
+        replace(@reflection.create_association(attributes))
       end
 
       def build(attributes = {})
-        replace(@reflection.klass.new(attributes))
+        replace(@reflection.build_association(attributes))
       end
 
       def replace(record)