activerecord 1.0.0 → 4.0.0

data/lib/active_record/aggregations.rb

@@ -1,19 +1,23 @@
 module ActiveRecord
+  # = Active Record Aggregations
   module Aggregations # :nodoc:
-    def self.append_features(base)
-      super
-      base.extend(ClassMethods)
+    extend ActiveSupport::Concern
+
+    def clear_aggregation_cache #:nodoc:
+      @aggregation_cache.clear if persisted?
     end
 
-    # Active Record implements aggregation through a macro-like class method called +composed_of+ for representing attributes 
-    # as value objects. It expresses relationships like "Account [is] composed of Money [among other things]" or "Person [is]
-    # composed of [an] address". Each call to the macro adds a description on how the value objects are created from the 
-    # attributes of the entity object (when the entity is initialized either as a new object or from finding an existing) 
-    # and how it can be turned back into attributes (when the entity is saved to the database). Example:
+    # Active Record implements aggregation through a macro-like class method called +composed_of+
+    # for representing attributes  as value objects. It expresses relationships like "Account [is]
+    # composed of Money [among other things]" or "Person [is] composed of [an] address". Each call
+    # to the macro adds a description of how the value objects are created from the attributes of
+    # the entity object (when the entity is initialized either as a new object or from finding an
+    # existing object) and how it can be turned back into attributes (when the entity is saved to
+    # the database).
     #
     #   class Customer < ActiveRecord::Base
-    #     composed_of :balance, :class_name => "Money", :mapping => %w(balance amount)
-    #     composed_of :address, :mapping => [ %w(address_street street), %w(address_city city) ]
+    #     composed_of :balance, class_name: "Money", mapping: %w(balance amount)
+    #     composed_of :address, mapping: [ %w(address_street street), %w(address_city city) ]
     #   end
     #
     # The customer class now has the following methods to manipulate the value objects:
@@ -25,10 +29,10 @@ module ActiveRecord
     #  class Money
     #    include Comparable
     #    attr_reader :amount, :currency
-    #    EXCHANGE_RATES = { "USD_TO_DKK" => 6 }  
-    # 
-    #    def initialize(amount, currency = "USD") 
-    #      @amount, @currency = amount, currency 
+    #    EXCHANGE_RATES = { "USD_TO_DKK" => 6 }
+    #
+    #    def initialize(amount, currency = "USD")
+    #      @amount, @currency = amount, currency
     #    end
     #
     #    def exchange_to(other_currency)
@@ -42,7 +46,7 @@ module ActiveRecord
     #
     #    def <=>(other_money)
     #      if currency == other_money.currency
-    #        among <=> amount
+    #        amount <=> other_money.amount
     #      else
     #        amount <=> other_money.exchange_to(currency).amount
     #      end
@@ -51,114 +55,206 @@ module ActiveRecord
     #
     #  class Address
     #    attr_reader :street, :city
-    #    def initialize(street, city) 
-    #      @street, @city = street, city 
+    #    def initialize(street, city)
+    #      @street, @city = street, city
     #    end
     #
-    #    def close_to?(other_address) 
-    #      city == other_address.city 
+    #    def close_to?(other_address)
+    #      city == other_address.city
     #    end
     #
     #    def ==(other_address)
     #      city == other_address.city && street == other_address.street
     #    end
     #  end
-    #  
-    # Now it's possible to access attributes from the database through the value objects instead. If you choose to name the
-    # composition the same as the attributes name, it will be the only way to access that attribute. That's the case with our
-    # +balance+ attribute. You interact with the value objects just like you would any other attribute, though:
+    #
+    # Now it's possible to access attributes from the database through the value objects instead. If
+    # you choose to name the composition the same as the attribute's name, it will be the only way to
+    # access that attribute. That's the case with our +balance+ attribute. You interact with the value
+    # objects just like you would with any other attribute:
     #
     #   customer.balance = Money.new(20)     # sets the Money value object and the attribute
     #   customer.balance                     # => Money value object
-    #   customer.balance.exchanged_to("DKK") # => Money.new(120, "DKK")
+    #   customer.balance.exchange_to("DKK")  # => Money.new(120, "DKK")
     #   customer.balance > Money.new(10)     # => true
     #   customer.balance == Money.new(20)    # => true
     #   customer.balance < Money.new(5)      # => false
     #
-    # Value objects can also be composed of multiple attributes, such as the case of Address. The order of the mappings will
-    # determine the order of the parameters. Example:
+    # Value objects can also be composed of multiple attributes, such as the case of Address. The order
+    # of the mappings will determine the order of the parameters.
     #
     #   customer.address_street = "Hyancintvej"
     #   customer.address_city   = "Copenhagen"
     #   customer.address        # => Address.new("Hyancintvej", "Copenhagen")
+    #
+    #   customer.address_street = "Vesterbrogade"
+    #   customer.address        # => Address.new("Hyancintvej", "Copenhagen")
+    #   customer.clear_aggregation_cache
+    #   customer.address        # => Address.new("Vesterbrogade", "Copenhagen")
+    #
     #   customer.address = Address.new("May Street", "Chicago")
-    #   customer.address_street # => "May Street" 
-    #   customer.address_city   # => "Chicago" 
+    #   customer.address_street # => "May Street"
+    #   customer.address_city   # => "Chicago"
     #
     # == Writing value objects
     #
-    # Value objects are immutable and interchangeable objects that represent a given value, such as a Money object representing
-    # $5. Two Money objects both representing $5 should be equal (through methods such == and <=> from Comparable if ranking makes
-    # sense). This is unlike a entity objects where equality is determined by identity. An entity class such as Customer can
-    # easily have two different objects that both have an address on Hyancintvej. Entity identity is determined by object or
-    # relational unique identifiers (such as primary keys). Normal ActiveRecord::Base classes are entity objects.
-    #
-    # It's also important to treat the value objects as immutable. Don't allow the Money object to have its amount changed after
-    # creation. Create a new money object with the new value instead. This is examplified by the Money#exchanged_to method that
-    # returns a new value object instead of changing its own values. Active Record won't persist value objects that have been
-    # changed through other means than the writer method.
-    #
-    # The immutable requirement is enforced by Active Record by freezing any object assigned as a value object. Attempting to 
-    # change it afterwards will result in a TypeError.
-    # 
-    # Read more about value objects on http://c2.com/cgi/wiki?ValueObject and on the dangers of not keeping value objects
-    # immutable on http://c2.com/cgi/wiki?ValueObjectsShouldBeImmutable
+    # Value objects are immutable and interchangeable objects that represent a given value, such as
+    # a Money object representing $5. Two Money objects both representing $5 should be equal (through
+    # methods such as <tt>==</tt> and <tt><=></tt> from Comparable if ranking makes sense). This is
+    # unlike entity objects where equality is determined by identity. An entity class such as Customer can
+    # easily have two different objects that both have an address on Hyancintvej. Entity identity is
+    # determined by object or relational unique identifiers (such as primary keys). Normal
+    # ActiveRecord::Base classes are entity objects.
+    #
+    # It's also important to treat the value objects as immutable. Don't allow the Money object to have
+    # its amount changed after creation. Create a new Money object with the new value instead. The
+    # Money#exchange_to method is an example of this. It returns a new value object instead of changing
+    # its own values. Active Record won't persist value objects that have been changed through means
+    # other than the writer method.
+    #
+    # The immutable requirement is enforced by Active Record by freezing any object assigned as a value
+    # object. Attempting to change it afterwards will result in a RuntimeError.
+    #
+    # Read more about value objects on http://c2.com/cgi/wiki?ValueObject and on the dangers of not
+    # keeping value objects immutable on http://c2.com/cgi/wiki?ValueObjectsShouldBeImmutable
+    #
+    # == Custom constructors and converters
+    #
+    # By default value objects are initialized by calling the <tt>new</tt> constructor of the value
+    # class passing each of the mapped attributes, in the order specified by the <tt>:mapping</tt>
+    # option, as arguments. If the value class doesn't support this convention then +composed_of+ allows
+    # a custom constructor to be specified.
+    #
+    # When a new value is assigned to the value object, the default assumption is that the new value
+    # is an instance of the value class. Specifying a custom converter allows the new value to be automatically
+    # converted to an instance of value class if necessary.
+    #
+    # For example, the NetworkResource model has +network_address+ and +cidr_range+ attributes that
+    # should be aggregated using the NetAddr::CIDR value class (http://netaddr.rubyforge.org). The constructor
+    # for the value class is called +create+ and it expects a CIDR address string as a parameter. New
+    # values can be assigned to the value object using either another NetAddr::CIDR object, a string
+    # or an array. The <tt>:constructor</tt> and <tt>:converter</tt> options can be used to meet
+    # these requirements:
+    #
+    #   class NetworkResource < ActiveRecord::Base
+    #     composed_of :cidr,
+    #                 class_name: 'NetAddr::CIDR',
+    #                 mapping: [ %w(network_address network), %w(cidr_range bits) ],
+    #                 allow_nil: true,
+    #                 constructor: Proc.new { |network_address, cidr_range| NetAddr::CIDR.create("#{network_address}/#{cidr_range}") },
+    #                 converter: Proc.new { |value| NetAddr::CIDR.create(value.is_a?(Array) ? value.join('/') : value) }
+    #   end
+    #
+    #   # This calls the :constructor
+    #   network_resource = NetworkResource.new(network_address: '192.168.0.1', cidr_range: 24)
+    #
+    #   # These assignments will both use the :converter
+    #   network_resource.cidr = [ '192.168.2.1', 8 ]
+    #   network_resource.cidr = '192.168.0.1/24'
+    #
+    #   # This assignment won't use the :converter as the value is already an instance of the value class
+    #   network_resource.cidr = NetAddr::CIDR.create('192.168.2.1/8')
+    #
+    #   # Saving and then reloading will use the :constructor on reload
+    #   network_resource.save
+    #   network_resource.reload
+    #
+    # == Finding records by a value object
+    #
+    # Once a +composed_of+ relationship is specified for a model, records can be loaded from the database
+    # by specifying an instance of the value object in the conditions hash. The following example
+    # finds all customers with +balance_amount+ equal to 20 and +balance_currency+ equal to "USD":
+    #
+    #   Customer.where(balance: Money.new(20, "USD"))
+    #
     module ClassMethods
-      # Adds the a reader and writer method for manipulating a value object, so
-      # <tt>composed_of :address</tt> would add <tt>address</tt> and <tt>address=(new_address)</tt>.
+      # Adds reader and writer methods for manipulating a value object:
+      # <tt>composed_of :address</tt> adds <tt>address</tt> and <tt>address=(new_address)</tt> methods.
       #
       # Options are:
-      # * <tt>:class_name</tt>  - specify the class name of the association. Use it only if that name can't be infered
-      #   from the part id. So <tt>composed_of :address</tt> will by default be linked to the +Address+ class, but
-      #   if the real class name is +CompanyAddress+, you'll have to specify it with this option.
-      # * <tt>:mapping</tt> - specifies a number of mapping arrays (attribute, parameter) that bind an attribute name
-      #   to a constructor parameter on the value class.
+      # * <tt>:class_name</tt> - Specifies the class name of the association. Use it only if that name
+      #   can't be inferred from the part id. So <tt>composed_of :address</tt> will by default be linked
+      #   to the Address class, but if the real class name is CompanyAddress, you'll have to specify it
+      #   with this option.
+      # * <tt>:mapping</tt> - Specifies the mapping of entity attributes to attributes of the value
+      #   object. Each mapping is represented as an array where the first item is the name of the
+      #   entity attribute and the second item is the name of the attribute in the value object. The
+      #   order in which mappings are defined determines the order in which attributes are sent to the
+      #   value class constructor.
+      # * <tt>:allow_nil</tt> - Specifies that the value object will not be instantiated when all mapped
+      #   attributes are +nil+. Setting the value object to +nil+ has the effect of writing +nil+ to all
+      #   mapped attributes.
+      #   This defaults to +false+.
+      # * <tt>:constructor</tt> - A symbol specifying the name of the constructor method or a Proc that
+      #   is called to initialize the value object. The constructor is passed all of the mapped attributes,
+      #   in the order that they are defined in the <tt>:mapping option</tt>, as arguments and uses them
+      #   to instantiate a <tt>:class_name</tt> object.
+      #   The default is <tt>:new</tt>.
+      # * <tt>:converter</tt> - A symbol specifying the name of a class method of <tt>:class_name</tt>
+      #   or a Proc that is called when a new value is assigned to the value object. The converter is
+      #   passed the single value that is used in the assignment and is only called if the new value is
+      #   not an instance of <tt>:class_name</tt>. If <tt>:allow_nil</tt> is set to true, the converter
+      #   can return nil to skip the assignment.
       #
       # Option examples:
-      #   composed_of :temperature, :mapping => %w(reading celsius)
-      #   composed_of :balance, :class_name => "Money", :mapping => %w(balance amount)
-      #   composed_of :address, :mapping => [ %w(address_street street), %w(address_city city) ]
+      #   composed_of :temperature, mapping: %w(reading celsius)
+      #   composed_of :balance, class_name: "Money", mapping: %w(balance amount),
+      #                         converter: Proc.new { |balance| balance.to_money }
+      #   composed_of :address, mapping: [ %w(address_street street), %w(address_city city) ]
+      #   composed_of :gps_location
+      #   composed_of :gps_location, allow_nil: true
+      #   composed_of :ip_address,
+      #               class_name: 'IPAddr',
+      #               mapping: %w(ip to_i),
+      #               constructor: Proc.new { |ip| IPAddr.new(ip, Socket::AF_INET) },
+      #               converter: Proc.new { |ip| ip.is_a?(Integer) ? IPAddr.new(ip, Socket::AF_INET) : IPAddr.new(ip.to_s) }
+      #
       def composed_of(part_id, options = {})
-        validate_options([ :class_name, :mapping ], options.keys)
+        options.assert_valid_keys(:class_name, :mapping, :allow_nil, :constructor, :converter)
 
         name        = part_id.id2name
-        class_name  = options[:class_name] || name_to_class_name(name)
-        mapping     = options[:mapping]
+        class_name  = options[:class_name]  || name.camelize
+        mapping     = options[:mapping]     || [ name, name ]
+        mapping     = [ mapping ] unless mapping.first.is_a?(Array)
+        allow_nil   = options[:allow_nil]   || false
+        constructor = options[:constructor] || :new
+        converter   = options[:converter]
+
+        reader_method(name, class_name, mapping, allow_nil, constructor)
+        writer_method(name, class_name, mapping, allow_nil, converter)
 
-        reader_method(name, class_name, mapping)
-        writer_method(name, class_name, mapping)
+        create_reflection(:composed_of, part_id, nil, options, self)
       end
 
       private
-        # Raises an exception if an invalid option has been specified to prevent misspellings from slipping through 
-        def validate_options(valid_option_keys, supplied_option_keys)
-          unknown_option_keys = supplied_option_keys - valid_option_keys
-          raise(ActiveRecordError, "Unknown options: #{unknown_option_keys}") unless unknown_option_keys.empty?
+        def reader_method(name, class_name, mapping, allow_nil, constructor)
+          define_method(name) do
+            if @aggregation_cache[name].nil? && (!allow_nil || mapping.any? {|pair| !read_attribute(pair.first).nil? })
+              attrs = mapping.collect {|pair| read_attribute(pair.first)}
+              object = constructor.respond_to?(:call) ?
+                constructor.call(*attrs) :
+                class_name.constantize.send(constructor, *attrs)
+              @aggregation_cache[name] = object
+            end
+            @aggregation_cache[name]
+          end
         end
 
-        def name_to_class_name(name)
-          name.capitalize.gsub(/_(.)/) { |s| $1.capitalize }
-        end
-        
-        def reader_method(name, class_name, mapping)
-          module_eval <<-end_eval
-            def #{name}(force_reload = false)
-              if @#{name}.nil? || force_reload
-                @#{name} = #{class_name}.new(#{(Array === mapping.first ? mapping : [ mapping ]).collect{ |pair| "read_attribute(\"#{pair.first}\")"}.join(", ")})
-              end
-              
-              return @#{name}
+        def writer_method(name, class_name, mapping, allow_nil, converter)
+          define_method("#{name}=") do |part|
+            klass = class_name.constantize
+            unless part.is_a?(klass) || converter.nil? || part.nil?
+              part = converter.respond_to?(:call) ? converter.call(part) : klass.send(converter, part)
             end
-          end_eval
-        end        
-        
-        def writer_method(name, class_name, mapping)
-          module_eval <<-end_eval
-            def #{name}=(part)
-              @#{name} = part.freeze
-              #{(Array === mapping.first ? mapping : [ mapping ]).collect{ |pair| "@attributes[\"#{pair.first}\"] = part.#{pair.last}" }.join("\n")}
+
+            if part.nil? && allow_nil
+              mapping.each { |pair| self[pair.first] = nil }
+              @aggregation_cache[name] = nil
+            else
+              mapping.each { |pair| self[pair.first] = part.send(pair.last) }
+              @aggregation_cache[name] = part.freeze
             end
-          end_eval
+          end
         end
     end
   end

data/lib/active_record/associations/alias_tracker.rb

@@ -0,0 +1,76 @@
+require 'active_support/core_ext/string/conversions'
+
+module ActiveRecord
+  module Associations
+    # Keeps track of table aliases for ActiveRecord::Associations::ClassMethods::JoinDependency and
+    # ActiveRecord::Associations::ThroughAssociationScope
+    class AliasTracker # :nodoc:
+      attr_reader :aliases, :table_joins, :connection
+
+      # table_joins is an array of arel joins which might conflict with the aliases we assign here
+      def initialize(connection = Base.connection, table_joins = [])
+        @aliases     = Hash.new { |h,k| h[k] = initial_count_for(k) }
+        @table_joins = table_joins
+        @connection  = connection
+      end
+
+      def aliased_table_for(table_name, aliased_name = nil)
+        table_alias = aliased_name_for(table_name, aliased_name)
+
+        if table_alias == table_name
+          Arel::Table.new(table_name)
+        else
+          Arel::Table.new(table_name).alias(table_alias)
+        end
+      end
+
+      def aliased_name_for(table_name, aliased_name = nil)
+        aliased_name ||= table_name
+
+        if aliases[table_name].zero?
+          # If it's zero, we can have our table_name
+          aliases[table_name] = 1
+          table_name
+        else
+          # Otherwise, we need to use an alias
+          aliased_name = connection.table_alias_for(aliased_name)
+
+          # Update the count
+          aliases[aliased_name] += 1
+
+          if aliases[aliased_name] > 1
+            "#{truncate(aliased_name)}_#{aliases[aliased_name]}"
+          else
+            aliased_name
+          end
+        end
+      end
+
+      private
+
+        def initial_count_for(name)
+          return 0 if Arel::Table === table_joins
+
+          # quoted_name should be downcased as some database adapters (Oracle) return quoted name in uppercase
+          quoted_name = connection.quote_table_name(name).downcase
+
+          counts = table_joins.map do |join|
+            if join.is_a?(Arel::Nodes::StringJoin)
+              # Table names + table aliases
+              join.left.downcase.scan(
+                /join(?:\s+\w+)?\s+(\S+\s+)?#{quoted_name}\son/
+              ).size
+            else
+              join.left.table_name == name ? 1 : 0
+            end
+          end
+
+          counts.sum
+        end
+
+        def truncate(name)
+          name.slice(0, connection.table_alias_length - 2)
+        end
+    end
+  end
+end

data/lib/active_record/associations/association.rb

@@ -0,0 +1,248 @@
+require 'active_support/core_ext/array/wrap'
+
+module ActiveRecord
+  module Associations
+    # = Active Record Associations
+    #
+    # This is the root class of all associations ('+ Foo' signifies an included module Foo):
+    #
+    #   Association
+    #     SingularAssociation
+    #       HasOneAssociation
+    #         HasOneThroughAssociation + ThroughAssociation
+    #       BelongsToAssociation
+    #         BelongsToPolymorphicAssociation
+    #     CollectionAssociation
+    #       HasAndBelongsToManyAssociation
+    #       HasManyAssociation
+    #         HasManyThroughAssociation + ThroughAssociation
+    class Association #:nodoc:
+      attr_reader :owner, :target, :reflection
+
+      delegate :options, :to => :reflection
+
+      def initialize(owner, reflection)
+        reflection.check_validity!
+
+        @owner, @reflection = owner, reflection
+
+        reset
+        reset_scope
+      end
+
+      # Returns the name of the table of the associated class:
+      #
+      #   post.comments.aliased_table_name # => "comments"
+      #
+      def aliased_table_name
+        klass.table_name
+      end
+
+      # Resets the \loaded flag to +false+ and sets the \target to +nil+.
+      def reset
+        @loaded = false
+        @target = nil
+        @stale_state = nil
+      end
+
+      # Reloads the \target and returns +self+ on success.
+      def reload
+        reset
+        reset_scope
+        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
+        @stale_state = stale_state
+      end
+
+      # The target is stale if the target no longer points to the record(s) that the
+      # relevant foreign_key(s) refers to. If stale, the association accessor method
+      # on the owner will reload the target. It's up to subclasses to implement the
+      # state_state method if relevant.
+      #
+      # Note that if the target has not been loaded, it is not considered stale.
+      def stale_target?
+        loaded? && @stale_state != stale_state
+      end
+
+      # Sets the target of this association to <tt>\target</tt>, and the \loaded flag to +true+.
+      def target=(target)
+        @target = target
+        loaded!
+      end
+
+      def scope
+        target_scope.merge(association_scope)
+      end
+
+      def scoped
+        ActiveSupport::Deprecation.warn "#scoped is deprecated. use #scope instead."
+        scope
+      end
+
+      # The scope for this association.
+      #
+      # Note that the association_scope is merged into the target_scope only when the
+      # scope method is called. This is because at that point the call may be surrounded
+      # by scope.scoping { ... } or with_scope { ... } etc, which affects the scope which
+      # actually gets built.
+      def association_scope
+        if klass
+          @association_scope ||= AssociationScope.new(self).scope
+        end
+      end
+
+      def reset_scope
+        @association_scope = nil
+      end
+
+      # Set the inverse association, if possible
+      def set_inverse_instance(record)
+        if record && invertible_for?(record)
+          inverse = record.association(inverse_reflection_for(record).name)
+          inverse.target = owner
+        end
+      end
+
+      # Returns the class of the target. belongs_to polymorphic overrides this to look at the
+      # polymorphic_type field on the owner.
+      def klass
+        reflection.klass
+      end
+
+      # Can be overridden (i.e. in ThroughAssociation) to merge in other scopes (i.e. the
+      # through association's scope)
+      def target_scope
+        klass.all
+      end
+
+      # 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.
+      #
+      # ActiveRecord::RecordNotFound is rescued within the method, and it is
+      # not reraised. The proxy is \reset and +nil+ is the return value.
+      def load_target
+        @target = find_target if (@stale_state && stale_target?) || find_target?
+
+        loaded! unless loaded?
+        target
+      rescue ActiveRecord::RecordNotFound
+        reset
+      end
+
+      def interpolate(sql, record = nil)
+        if sql.respond_to?(:to_proc)
+          owner.instance_exec(record, &sql)
+        else
+          sql
+        end
+      end
+
+      # We can't dump @reflection since it contains the scope proc
+      def marshal_dump
+        ivars = (instance_variables - [:@reflection]).map { |name| [name, instance_variable_get(name)] }
+        [@reflection.name, ivars]
+      end
+
+      def marshal_load(data)
+        reflection_name, ivars = data
+        ivars.each { |name, val| instance_variable_set(name, val) }
+        @reflection = @owner.class.reflect_on_association(reflection_name)
+      end
+
+      def initialize_attributes(record) #:nodoc:
+        skip_assign = [reflection.foreign_key, reflection.type].compact
+        attributes = create_scope.except(*(record.changed - skip_assign))
+        record.assign_attributes(attributes)
+        set_inverse_instance(record)
+      end
+
+      private
+
+        def find_target?
+          !loaded? && (!owner.new_record? || foreign_key_present?) && klass
+        end
+
+        def creation_attributes
+          attributes = {}
+
+          if (reflection.macro == :has_one || reflection.macro == :has_many) && !options[:through]
+            attributes[reflection.foreign_key] = owner[reflection.active_record_primary_key]
+
+            if reflection.options[:as]
+              attributes[reflection.type] = owner.class.base_class.name
+            end
+          end
+
+          attributes
+        end
+
+        # Sets the owner attributes on the given record
+        def set_owner_attributes(record)
+          creation_attributes.each { |key, value| record[key] = value }
+        end
+
+        # Should be true if there is a foreign key present on the owner which
+        # references the target. This is used to determine whether we can load
+        # the target if the owner is currently a new record (and therefore
+        # without a key).
+        #
+        # Currently implemented by belongs_to (vanilla and polymorphic) and
+        # has_one/has_many :through associations which go through a belongs_to
+        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) || 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
+
+        # Can be redefined by subclasses, notably polymorphic belongs_to
+        # The record parameter is necessary to support polymorphic inverses as we must check for
+        # the association in the specific class of the record.
+        def inverse_reflection_for(record)
+          reflection.inverse_of
+        end
+
+        # Returns true if inverse association on the given record needs to be set.
+        # This method is redefined by subclasses.
+        def invertible_for?(record)
+          inverse_reflection_for(record)
+        end
+
+        # This should be implemented to return the values of the relevant key(s) on the owner,
+        # so that when stale_state is different from the value stored on the last find_target,
+        # the target is stale.
+        #
+        # This is only relevant to certain associations, which is why it returns nil by default.
+        def stale_state
+        end
+
+        def build_record(attributes)
+          reflection.build_association(attributes) do |record|
+            initialize_attributes(record)
+          end
+        end
+    end
+  end
+end