activerecord 3.0.0 → 4.0.0

data/lib/active_record/associations/preloader.rb

@@ -0,0 +1,178 @@
+module ActiveRecord
+  module Associations
+    # Implements the details of eager loading of Active Record associations.
+    #
+    # Note that 'eager loading' and 'preloading' are actually the same thing.
+    # However, there are two different eager loading strategies.
+    #
+    # The first one is by using table joins. This was only strategy available
+    # prior to Rails 2.1. Suppose that you have an Author model with columns
+    # 'name' and 'age', and a Book model with columns 'name' and 'sales'. Using
+    # this strategy, Active Record would try to retrieve all data for an author
+    # and all of its books via a single query:
+    #
+    #   SELECT * FROM authors
+    #   LEFT OUTER JOIN books ON authors.id = books.author_id
+    #   WHERE authors.name = 'Ken Akamatsu'
+    #
+    # However, this could result in many rows that contain redundant data. After
+    # having received the first row, we already have enough data to instantiate
+    # the Author object. In all subsequent rows, only the data for the joined
+    # 'books' table is useful; the joined 'authors' data is just redundant, and
+    # processing this redundant data takes memory and CPU time. The problem
+    # quickly becomes worse and worse as the level of eager loading increases
+    # (i.e. if Active Record is to eager load the associations' associations as
+    # well).
+    #
+    # The second strategy is to use multiple database queries, one for each
+    # level of association. Since Rails 2.1, this is the default strategy. In
+    # situations where a table join is necessary (e.g. when the +:conditions+
+    # option references an association's column), it will fallback to the table
+    # join strategy.
+    class Preloader #:nodoc:
+      extend ActiveSupport::Autoload
+
+      eager_autoload do
+        autoload :Association,           'active_record/associations/preloader/association'
+        autoload :SingularAssociation,   'active_record/associations/preloader/singular_association'
+        autoload :CollectionAssociation, 'active_record/associations/preloader/collection_association'
+        autoload :ThroughAssociation,    'active_record/associations/preloader/through_association'
+
+        autoload :HasMany,             'active_record/associations/preloader/has_many'
+        autoload :HasManyThrough,      'active_record/associations/preloader/has_many_through'
+        autoload :HasOne,              'active_record/associations/preloader/has_one'
+        autoload :HasOneThrough,       'active_record/associations/preloader/has_one_through'
+        autoload :HasAndBelongsToMany, 'active_record/associations/preloader/has_and_belongs_to_many'
+        autoload :BelongsTo,           'active_record/associations/preloader/belongs_to'
+      end
+
+      attr_reader :records, :associations, :preload_scope, :model
+
+      # Eager loads the named associations for the given Active Record record(s).
+      #
+      # In this description, 'association name' shall refer to the name passed
+      # to an association creation method. For example, a model that specifies
+      # <tt>belongs_to :author</tt>, <tt>has_many :buyers</tt> has association
+      # names +:author+ and +:buyers+.
+      #
+      # == Parameters
+      # +records+ is an array of ActiveRecord::Base. This array needs not be flat,
+      # i.e. +records+ itself may also contain arrays of records. In any case,
+      # +preload_associations+ will preload the all associations records by
+      # flattening +records+.
+      #
+      # +associations+ specifies one or more associations that you want to
+      # preload. It may be:
+      # - a Symbol or a String which specifies a single association name. For
+      #   example, specifying +:books+ allows this method to preload all books
+      #   for an Author.
+      # - an Array which specifies multiple association names. This array
+      #   is processed recursively. For example, specifying <tt>[:avatar, :books]</tt>
+      #   allows this method to preload an author's avatar as well as all of his
+      #   books.
+      # - a Hash which specifies multiple association names, as well as
+      #   association names for the to-be-preloaded association objects. For
+      #   example, specifying <tt>{ author: :avatar }</tt> will preload a
+      #   book's author, as well as that author's avatar.
+      #
+      # +:associations+ has the same format as the +:include+ option for
+      # <tt>ActiveRecord::Base.find</tt>. So +associations+ could look like this:
+      #
+      #   :books
+      #   [ :books, :author ]
+      #   { author: :avatar }
+      #   [ :books, { author: :avatar } ]
+      def initialize(records, associations, preload_scope = nil)
+        @records       = Array.wrap(records).compact.uniq
+        @associations  = Array.wrap(associations)
+        @preload_scope = preload_scope || Relation.new(nil, nil)
+      end
+
+      def run
+        unless records.empty?
+          associations.each { |association| preload(association) }
+        end
+      end
+
+      private
+
+      def preload(association)
+        case association
+        when Hash
+          preload_hash(association)
+        when Symbol
+          preload_one(association)
+        when String
+          preload_one(association.to_sym)
+        else
+          raise ArgumentError, "#{association.inspect} was not recognised for preload"
+        end
+      end
+
+      def preload_hash(association)
+        association.each do |parent, child|
+          Preloader.new(records, parent, preload_scope).run
+          Preloader.new(records.map { |record| record.send(parent) }.flatten, child).run
+        end
+      end
+
+      # Not all records have the same class, so group then preload group on the reflection
+      # itself so that if various subclass share the same association then we do not split
+      # them unnecessarily
+      #
+      # Additionally, polymorphic belongs_to associations can have multiple associated
+      # classes, depending on the polymorphic_type field. So we group by the classes as
+      # well.
+      def preload_one(association)
+        grouped_records(association).each do |reflection, klasses|
+          klasses.each do |klass, records|
+            preloader_for(reflection).new(klass, records, reflection, preload_scope).run
+          end
+        end
+      end
+
+      def grouped_records(association)
+        Hash[
+          records_by_reflection(association).map do |reflection, records|
+            [reflection, records.group_by { |record| association_klass(reflection, record) }]
+          end
+        ]
+      end
+
+      def records_by_reflection(association)
+        records.group_by do |record|
+          reflection = record.class.reflections[association]
+
+          unless reflection
+            raise ActiveRecord::ConfigurationError, "Association named '#{association}' was not found; " \
+                                                    "perhaps you misspelled it?"
+          end
+
+          reflection
+        end
+      end
+
+      def association_klass(reflection, record)
+        if reflection.macro == :belongs_to && reflection.options[:polymorphic]
+          klass = record.send(reflection.foreign_type)
+          klass && klass.constantize
+        else
+          reflection.klass
+        end
+      end
+
+      def preloader_for(reflection)
+        case reflection.macro
+        when :has_many
+          reflection.options[:through] ? HasManyThrough : HasMany
+        when :has_one
+          reflection.options[:through] ? HasOneThrough : HasOne
+        when :has_and_belongs_to_many
+          HasAndBelongsToMany
+        when :belongs_to
+          BelongsTo
+        end
+      end
+    end
+  end
+end

data/lib/active_record/associations/singular_association.rb

@@ -0,0 +1,64 @@
+module ActiveRecord
+  module Associations
+    class SingularAssociation < Association #:nodoc:
+      # Implements the reader method, e.g. foo.bar for Foo.has_one :bar
+      def reader(force_reload = false)
+        if force_reload
+          klass.uncached { reload }
+        elsif !loaded? || stale_target?
+          reload
+        end
+
+        target
+      end
+
+      # Implements the writer method, e.g. foo.bar= for Foo.belongs_to :bar
+      def writer(record)
+        replace(record)
+      end
+
+      def create(attributes = {}, &block)
+        create_record(attributes, &block)
+      end
+
+      def create!(attributes = {}, &block)
+        create_record(attributes, true, &block)
+      end
+
+      def build(attributes = {})
+        record = build_record(attributes)
+        yield(record) if block_given?
+        set_new_record(record)
+        record
+      end
+
+      private
+
+        def create_scope
+          scope.scope_for_create.stringify_keys.except(klass.primary_key)
+        end
+
+        def find_target
+          scope.first.tap { |record| set_inverse_instance(record) }
+        end
+
+        # Implemented by subclasses
+        def replace(record)
+          raise NotImplementedError, "Subclasses must implement a replace(record) method"
+        end
+
+        def set_new_record(record)
+          replace(record)
+        end
+
+        def create_record(attributes, raise_error = false)
+          record = build_record(attributes)
+          yield(record) if block_given?
+          saved = record.save
+          set_new_record(record)
+          raise RecordInvalid.new(record) if !saved && raise_error
+          record
+        end
+    end
+  end
+end

data/lib/active_record/associations/through_association.rb

@@ -0,0 +1,87 @@
+module ActiveRecord
+  # = Active Record Through Association
+  module Associations
+    module ThroughAssociation #:nodoc:
+
+      delegate :source_reflection, :through_reflection, :chain, :to => :reflection
+
+      protected
+
+        # We merge in these scopes for two reasons:
+        #
+        #   1. To get the default_scope conditions for any of the other reflections in the chain
+        #   2. To get the type conditions for any STI models in the chain
+        def target_scope
+          scope = super
+          chain[1..-1].each do |reflection|
+            scope.merge!(
+              reflection.klass.all.with_default_scope.
+                except(:select, :create_with, :includes, :preload, :joins, :eager_load)
+            )
+          end
+          scope
+        end
+
+      private
+
+        # Construct attributes for :through pointing to owner and associate. This is used by the
+        # methods which create and delete records on the association.
+        #
+        # We only support indirectly modifying through associations which has a belongs_to source.
+        # This is the "has_many :tags, through: :taggings" situation, where the join model
+        # typically has a belongs_to on both side. In other words, associations which could also
+        # be represented as has_and_belongs_to_many associations.
+        #
+        # We do not support creating/deleting records on the association where the source has
+        # some other type, because this opens up a whole can of worms, and in basically any
+        # situation it is more natural for the user to just create or modify their join records
+        # directly as required.
+        def construct_join_attributes(*records)
+          ensure_mutable
+
+          join_attributes = {
+            source_reflection.foreign_key =>
+              records.map { |record|
+                record.send(source_reflection.association_primary_key(reflection.klass))
+              }
+          }
+
+          if options[:source_type]
+            join_attributes[source_reflection.foreign_type] =
+              records.map { |record| record.class.base_class.name }
+          end
+
+          if records.count == 1
+            Hash[join_attributes.map { |k, v| [k, v.first] }]
+          else
+            join_attributes
+          end
+        end
+
+        # Note: this does not capture all cases, for example it would be crazy to try to
+        # properly support stale-checking for nested associations.
+        def stale_state
+          if through_reflection.macro == :belongs_to
+            owner[through_reflection.foreign_key] && owner[through_reflection.foreign_key].to_s
+          end
+        end
+
+        def foreign_key_present?
+          through_reflection.macro == :belongs_to &&
+          !owner[through_reflection.foreign_key].nil?
+        end
+
+        def ensure_mutable
+          if source_reflection.macro != :belongs_to
+            raise HasManyThroughCantAssociateThroughHasOneOrManyReflection.new(owner, reflection)
+          end
+        end
+
+        def ensure_not_nested
+          if reflection.nested?
+            raise HasManyThroughNestedAssociationsAreReadonly.new(owner, reflection)
+          end
+        end
+    end
+  end
+end