activerecord 3.0.20 → 3.1.0.beta1

data/lib/active_record.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2004-2010 David Heinemeier Hansson
+# Copyright (c) 2004-2011 David Heinemeier Hansson
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
@@ -43,7 +43,6 @@ module ActiveRecord
     autoload :ConnectionNotEstablished, 'active_record/errors'
 
     autoload :Aggregations
-    autoload :AssociationPreload
     autoload :Associations
     autoload :AttributeMethods
     autoload :AutosaveAssociation
@@ -79,6 +78,11 @@ module ActiveRecord
     autoload :Timestamp
     autoload :Transactions
     autoload :Validations
+    autoload :IdentityMap
+  end
+
+  module Coders
+    autoload :YAMLColumn, 'active_record/coders/yaml_column'
   end
 
   module AttributeMethods

data/lib/active_record/aggregations.rb

@@ -4,9 +4,7 @@ module ActiveRecord
     extend ActiveSupport::Concern
 
     def clear_aggregation_cache #:nodoc:
-      self.class.reflect_on_all_aggregations.to_a.each do |assoc|
-        instance_variable_set "@#{assoc.name}", nil
-      end unless self.new_record?
+      @aggregation_cache.clear if persisted?
     end
 
     # Active Record implements aggregation through a macro-like class method called +composed_of+
@@ -48,7 +46,7 @@ module ActiveRecord
     #
     #    def <=>(other_money)
     #      if currency == other_money.currency
-    #        amount <=> other_money.amount
+    #        amount <=> amount
     #      else
     #        amount <=> other_money.exchange_to(currency).amount
     #      end
@@ -222,53 +220,32 @@ module ActiveRecord
 
       private
         def reader_method(name, class_name, mapping, allow_nil, constructor)
-          module_eval do
-            define_method(name) do |*args|
-              force_reload = args.first || false
-
-              unless instance_variable_defined?("@#{name}")
-                instance_variable_set("@#{name}", nil)
-              end
-
-              if (instance_variable_get("@#{name}").nil? || force_reload) && (!allow_nil || mapping.any? {|pair| !read_attribute(pair.first).nil? })
-                attrs = mapping.collect {|pair| read_attribute(pair.first)}
-                object = case constructor
-                  when Symbol
-                    class_name.constantize.send(constructor, *attrs)
-                  when Proc, Method
-                    constructor.call(*attrs)
-                  else
-                    raise ArgumentError, 'Constructor must be a symbol denoting the constructor method to call or a Proc to be invoked.'
-                  end
-                instance_variable_set("@#{name}", object)
-              end
-              instance_variable_get("@#{name}")
+          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 writer_method(name, class_name, mapping, allow_nil, converter)
-          module_eval do
-            define_method("#{name}=") do |part|
-              if part.nil? && allow_nil
-                mapping.each { |pair| self[pair.first] = nil }
-                instance_variable_set("@#{name}", nil)
-              else
-                unless part.is_a?(class_name.constantize) || converter.nil?
-                  part = case converter
-                    when Symbol
-                     class_name.constantize.send(converter, part)
-                    when Proc, Method
-                      converter.call(part)
-                    else
-                      raise ArgumentError, 'Converter must be a symbol denoting the converter method to call or a Proc to be invoked.'
-                    end
-                end
-
-                mapping.each { |pair| self[pair.first] = part.send(pair.last) }
-                instance_variable_set("@#{name}", part.freeze)
+          define_method("#{name}=") do |part|
+            if part.nil? && allow_nil
+              mapping.each { |pair| self[pair.first] = nil }
+              @aggregation_cache[name] = nil
+            else
+              unless part.is_a?(class_name.constantize) || converter.nil?
+                part = converter.respond_to?(:call) ?
+                  converter.call(part) :
+                  class_name.constantize.send(converter, part)
               end
+
+              mapping.each { |pair| self[pair.first] = part.send(pair.last) }
+              @aggregation_cache[name] = part.freeze
             end
           end
         end

data/lib/active_record/associations.rb

@@ -4,6 +4,7 @@ require 'active_support/core_ext/module/delegation'
 require 'active_support/core_ext/object/blank'
 require 'active_support/core_ext/string/conversions'
 require 'active_support/core_ext/module/remove_method'
+require 'active_support/core_ext/class/attribute'
 
 module ActiveRecord
   class InverseOfAssociationNotFoundError < ActiveRecordError #:nodoc:
@@ -18,18 +19,30 @@ module ActiveRecord
     end
   end
 
-  class HasManyThroughAssociationPolymorphicError < ActiveRecordError #:nodoc:
+  class HasManyThroughAssociationPolymorphicSourceError < ActiveRecordError #:nodoc:
     def initialize(owner_class_name, reflection, source_reflection)
       super("Cannot have a has_many :through association '#{owner_class_name}##{reflection.name}' on the polymorphic object '#{source_reflection.class_name}##{source_reflection.name}'.")
     end
   end
 
+  class HasManyThroughAssociationPolymorphicThroughError < ActiveRecordError #:nodoc:
+    def initialize(owner_class_name, reflection)
+      super("Cannot have a has_many :through association '#{owner_class_name}##{reflection.name}' which goes through the polymorphic association '#{owner_class_name}##{reflection.through_reflection.name}'.")
+    end
+  end
+
   class HasManyThroughAssociationPointlessSourceTypeError < ActiveRecordError #:nodoc:
     def initialize(owner_class_name, reflection, source_reflection)
       super("Cannot have a has_many :through association '#{owner_class_name}##{reflection.name}' with a :source_type option if the '#{reflection.through_reflection.class_name}##{source_reflection.name}' is not polymorphic.  Try removing :source_type on your association.")
     end
   end
 
+  class HasOneThroughCantAssociateThroughCollection < ActiveRecordError #:nodoc:
+    def initialize(owner_class_name, reflection, through_reflection)
+      super("Cannot have a has_one :through association '#{owner_class_name}##{reflection.name}' where the :through association '#{owner_class_name}##{through_reflection.name}' is a collection. Specify a has_one or belongs_to association in the :through option instead.")
+    end
+  end
+
   class HasManyThroughSourceAssociationNotFoundError < ActiveRecordError #:nodoc:
     def initialize(reflection)
       through_reflection      = reflection.through_reflection
@@ -39,14 +52,6 @@ module ActiveRecord
     end
   end
 
-  class HasManyThroughSourceAssociationMacroError < ActiveRecordError #:nodoc:
-    def initialize(reflection)
-      through_reflection = reflection.through_reflection
-      source_reflection  = reflection.source_reflection
-      super("Invalid source reflection macro :#{source_reflection.macro}#{" :through" if source_reflection.options[:through]} for has_many #{reflection.name.inspect}, :through => #{through_reflection.name.inspect}.  Use :source to specify the source reflection.")
-    end
-  end
-
   class HasManyThroughCantAssociateThroughHasOneOrManyReflection < ActiveRecordError #:nodoc:
     def initialize(owner, reflection)
       super("Cannot modify association '#{owner.class.name}##{reflection.name}' because the source reflection class '#{reflection.source_reflection.class_name}' is associated to '#{reflection.through_reflection.class_name}' via :#{reflection.source_reflection.macro}.")
@@ -65,6 +70,12 @@ module ActiveRecord
     end
   end
 
+  class HasManyThroughNestedAssociationsAreReadonly < ActiveRecordError #:nodoc
+    def initialize(owner, reflection)
+      super("Cannot modify association '#{owner.class.name}##{reflection.name}' because it goes through more than one other association.")
+    end
+  end
+
   class HasAndBelongsToManyAssociationWithPrimaryKeyError < ActiveRecordError #:nodoc:
     def initialize(reflection)
       super("Primary key is not allowed in a has_and_belongs_to_many join table (#{reflection.options[:join_table]}).")
@@ -93,8 +104,8 @@ module ActiveRecord
   # (has_many, has_one) when there is at least 1 child associated instance.
   # ex: if @project.tasks.size > 0, DeleteRestrictionError will be raised when trying to destroy @project
   class DeleteRestrictionError < ActiveRecordError #:nodoc:
-    def initialize(reflection)
-      super("Cannot delete record because of dependent #{reflection.name}")
+    def initialize(name)
+      super("Cannot delete record because of dependent #{name}")
     end
   end
 
@@ -104,36 +115,67 @@ module ActiveRecord
 
     # These classes will be loaded when associations are created.
     # So there is no need to eager load them.
-    autoload :AssociationCollection, 'active_record/associations/association_collection'
-    autoload :AssociationProxy, 'active_record/associations/association_proxy'
-    autoload :BelongsToAssociation, 'active_record/associations/belongs_to_association'
+    autoload :Association,           'active_record/associations/association'
+    autoload :SingularAssociation,   'active_record/associations/singular_association'
+    autoload :CollectionAssociation, 'active_record/associations/collection_association'
+    autoload :CollectionProxy,       'active_record/associations/collection_proxy'
+
+    autoload :BelongsToAssociation,            'active_record/associations/belongs_to_association'
     autoload :BelongsToPolymorphicAssociation, 'active_record/associations/belongs_to_polymorphic_association'
-    autoload :HasAndBelongsToManyAssociation, 'active_record/associations/has_and_belongs_to_many_association'
-    autoload :HasManyAssociation, 'active_record/associations/has_many_association'
-    autoload :HasManyThroughAssociation, 'active_record/associations/has_many_through_association'
-    autoload :HasOneAssociation, 'active_record/associations/has_one_association'
-    autoload :HasOneThroughAssociation, 'active_record/associations/has_one_through_association'
+    autoload :HasAndBelongsToManyAssociation,  'active_record/associations/has_and_belongs_to_many_association'
+    autoload :HasManyAssociation,              'active_record/associations/has_many_association'
+    autoload :HasManyThroughAssociation,       'active_record/associations/has_many_through_association'
+    autoload :HasOneAssociation,               'active_record/associations/has_one_association'
+    autoload :HasOneThroughAssociation,        'active_record/associations/has_one_through_association'
+    autoload :ThroughAssociation,              'active_record/associations/through_association'
+
+    module Builder #:nodoc:
+      autoload :Association,           'active_record/associations/builder/association'
+      autoload :SingularAssociation,   'active_record/associations/builder/singular_association'
+      autoload :CollectionAssociation, 'active_record/associations/builder/collection_association'
+
+      autoload :BelongsTo,           'active_record/associations/builder/belongs_to'
+      autoload :HasOne,              'active_record/associations/builder/has_one'
+      autoload :HasMany,             'active_record/associations/builder/has_many'
+      autoload :HasAndBelongsToMany, 'active_record/associations/builder/has_and_belongs_to_many'
+    end
+
+    autoload :Preloader,        'active_record/associations/preloader'
+    autoload :JoinDependency,   'active_record/associations/join_dependency'
+    autoload :AssociationScope, 'active_record/associations/association_scope'
+    autoload :AliasTracker,     'active_record/associations/alias_tracker'
+    autoload :JoinHelper,       'active_record/associations/join_helper'
 
     # Clears out the association cache.
     def clear_association_cache #:nodoc:
-      self.class.reflect_on_all_associations.to_a.each do |assoc|
-        instance_variable_set "@#{assoc.name}", nil
-      end unless self.new_record?
+      @association_cache.clear if persisted?
+    end
+
+    # :nodoc:
+    attr_reader :association_cache
+
+    # Returns the association instance for the given name, instantiating it if it doesn't already exist
+    def association(name) #:nodoc:
+      association = association_instance_get(name)
+
+      if association.nil?
+        reflection  = self.class.reflect_on_association(name)
+        association = reflection.association_class.new(self, reflection)
+        association_instance_set(name, association)
+      end
+
+      association
     end
 
     private
       # Returns the specified association instance if it responds to :loaded?, nil otherwise.
       def association_instance_get(name)
-        ivar = "@#{name}"
-        if instance_variable_defined?(ivar)
-          association = instance_variable_get(ivar)
-          association if association.respond_to?(:loaded?)
-        end
+        @association_cache[name.to_sym]
       end
 
       # Set the specified association instance.
       def association_instance_set(name, association)
-        instance_variable_set("@#{name}", association)
+        @association_cache[name] = association
       end
 
     # Associations are a set of macro-like class methods for tying objects together through
@@ -177,7 +219,7 @@ module ActiveRecord
     #   other=(other)                     |     X      |      X       |    X
     #   build_other(attributes={})        |     X      |              |    X
     #   create_other(attributes={})       |     X      |              |    X
-    #   other.create!(attributes={})      |            |              |    X
+    #   create_other!(attributes={})      |     X      |              |    X
     #
     # ===Collection associations (one-to-many / many-to-many)
     #                                     |       |          | has_many
@@ -200,10 +242,9 @@ module ActiveRecord
     #   others.empty?                     |   X   |    X     |    X
     #   others.clear                      |   X   |    X     |    X
     #   others.delete(other,other,...)    |   X   |    X     |    X
-    #   others.delete_all                 |   X   |    X     |
+    #   others.delete_all                 |   X   |    X     |    X
     #   others.destroy_all                |   X   |    X     |    X
     #   others.find(*args)                |   X   |    X     |    X
-    #   others.find_first                 |   X   |          |
     #   others.exists?                    |   X   |    X     |    X
     #   others.uniq                       |   X   |    X     |    X
     #   others.reset                      |   X   |    X     |    X
@@ -317,26 +358,31 @@ module ActiveRecord
     # === One-to-one associations
     #
     # * Assigning an object to a +has_one+ association automatically saves that object and
-    # the object being replaced (if there is one), in order to update their primary
-    # keys - except if the parent object is unsaved (<tt>new_record? == true</tt>).
-    # * If either of these saves fail (due to one of the objects being invalid) the assignment
-    # statement returns +false+ and the assignment is cancelled.
+    #   the object being replaced (if there is one), in order to update their foreign
+    #   keys - except if the parent object is unsaved (<tt>new_record? == true</tt>).
+    # * If either of these saves fail (due to one of the objects being invalid), an
+    #   <tt>ActiveRecord::RecordNotSaved</tt> exception is raised and the assignment is
+    #   cancelled.
     # * If you wish to assign an object to a +has_one+ association without saving it,
-    # use the <tt>association.build</tt> method (documented below).
+    #   use the <tt>build_association</tt> method (documented below). The object being
+    #   replaced will still be saved to update its foreign key.
     # * Assigning an object to a +belongs_to+ association does not save the object, since
-    # the foreign key field belongs on the parent. It does not save the parent either.
+    #   the foreign key field belongs on the parent. It does not save the parent either.
     #
     # === Collections
     #
     # * Adding an object to a collection (+has_many+ or +has_and_belongs_to_many+) automatically
-    # saves that object, except if the parent object (the owner of the collection) is not yet
-    # stored in the database.
+    #   saves that object, except if the parent object (the owner of the collection) is not yet
+    #   stored in the database.
     # * If saving any of the objects being added to a collection (via <tt>push</tt> or similar)
-    # fails, then <tt>push</tt> returns +false+.
+    #   fails, then <tt>push</tt> returns +false+.
+    # * If saving fails while replacing the collection (via <tt>association=</tt>), an
+    #   <tt>ActiveRecord::RecordNotSaved</tt> exception is raised and the assignment is
+    #   cancelled.
     # * You can add an object to a collection without automatically saving it by using the
-    # <tt>collection.build</tt> method (documented below).
+    #   <tt>collection.build</tt> method (documented below).
     # * All unsaved (<tt>new_record? == true</tt>) members of the collection are automatically
-    # saved when the parent is saved.
+    #   saved when the parent is saved.
     #
     # === Association callbacks
     #
@@ -487,6 +533,65 @@ module ActiveRecord
     #   @group.avatars << Avatar.new   # this would work if User belonged_to Avatar rather than the other way around
     #   @group.avatars.delete(@group.avatars.last)  # so would this
     #
+    # If you are using a +belongs_to+ on the join model, it is a good idea to set the
+    # <tt>:inverse_of</tt> option on the +belongs_to+, which will mean that the following example
+    # works correctly (where <tt>tags</tt> is a +has_many+ <tt>:through</tt> association):
+    #
+    #   @post = Post.first
+    #   @tag = @post.tags.build :name => "ruby"
+    #   @tag.save
+    #
+    # The last line ought to save the through record (a <tt>Taggable</tt>). This will only work if the
+    # <tt>:inverse_of</tt> is set:
+    #
+    #   class Taggable < ActiveRecord::Base
+    #     belongs_to :post
+    #     belongs_to :tag, :inverse_of => :taggings
+    #   end
+    #
+    # === Nested Associations
+    #
+    # You can actually specify *any* association with the <tt>:through</tt> option, including an
+    # association which has a <tt>:through</tt> option itself. For example:
+    #
+    #   class Author < ActiveRecord::Base
+    #     has_many :posts
+    #     has_many :comments, :through => :posts
+    #     has_many :commenters, :through => :comments
+    #   end
+    #
+    #   class Post < ActiveRecord::Base
+    #     has_many :comments
+    #   end
+    #
+    #   class Comment < ActiveRecord::Base
+    #     belongs_to :commenter
+    #   end
+    #
+    #   @author = Author.first
+    #   @author.commenters # => People who commented on posts written by the author
+    #
+    # An equivalent way of setting up this association this would be:
+    #
+    #   class Author < ActiveRecord::Base
+    #     has_many :posts
+    #     has_many :commenters, :through => :posts
+    #   end
+    #
+    #   class Post < ActiveRecord::Base
+    #     has_many :comments
+    #     has_many :commenters, :through => :comments
+    #   end
+    #
+    #   class Comment < ActiveRecord::Base
+    #     belongs_to :commenter
+    #   end
+    #
+    # When using nested association, you will not be able to modify the association because there
+    # is not enough information to know what modification to make. For example, if you tried to
+    # add a <tt>Commenter</tt> in the example above, there would be no way to tell how to set up the
+    # intermediate <tt>Post</tt> and <tt>Comment</tt> objects.
+    #
     # === Polymorphic Associations
     #
     # Polymorphic associations on models are not restricted on what types of models they
@@ -756,7 +861,7 @@ module ActiveRecord
     #      belongs_to :dungeon
     #    end
     #
-    # The +traps+ association on +Dungeon+ and the the +dungeon+ association on +Trap+ are
+    # The +traps+ association on +Dungeon+ and the +dungeon+ association on +Trap+ are
     # the inverse of each other and the inverse of the +dungeon+ association on +EvilWizard+
     # is the +evil_wizard+ association on +Dungeon+ (and vice-versa).  By default,
     # Active Record doesn't know anything about these inverse relationships and so no object
@@ -796,6 +901,73 @@ module ActiveRecord
     # * does not work with <tt>:polymorphic</tt> associations.
     # * for +belongs_to+ associations +has_many+ inverse associations are ignored.
     #
+    # == Deleting from associations
+    #
+    # === Dependent associations
+    #
+    # +has_many+, +has_one+ and +belongs_to+ associations support the <tt>:dependent</tt> option.
+    # This allows you to specify that associated records should be deleted when the owner is
+    # deleted.
+    #
+    # For example:
+    #
+    #     class Author
+    #       has_many :posts, :dependent => :destroy
+    #     end
+    #     Author.find(1).destroy # => Will destroy all of the author's posts, too
+    #
+    # The <tt>:dependent</tt> option can have different values which specify how the deletion
+    # is done. For more information, see the documentation for this option on the different
+    # specific association types.
+    #
+    # === Delete or destroy?
+    #
+    # +has_many+ and +has_and_belongs_to_many+ associations have the methods <tt>destroy</tt>,
+    # <tt>delete</tt>, <tt>destroy_all</tt> and <tt>delete_all</tt>.
+    #
+    # For +has_and_belongs_to_many+, <tt>delete</tt> and <tt>destroy</tt> are the same: they
+    # cause the records in the join table to be removed.
+    #
+    # For +has_many+, <tt>destroy</tt> will always call the <tt>destroy</tt> method of the
+    # record(s) being removed so that callbacks are run. However <tt>delete</tt> will either
+    # do the deletion according to the strategy specified by the <tt>:dependent</tt> option, or
+    # if no <tt>:dependent</tt> option is given, then it will follow the default strategy.
+    # The default strategy is <tt>:nullify</tt> (set the foreign keys to <tt>nil</tt>), except for
+    # +has_many+ <tt>:through</tt>, where the default strategy is <tt>delete_all</tt> (delete
+    # the join records, without running their callbacks).
+    #
+    # There is also a <tt>clear</tt> method which is the same as <tt>delete_all</tt>, except that
+    # it returns the association rather than the records which have been deleted.
+    #
+    # === What gets deleted?
+    #
+    # There is a potential pitfall here: +has_and_belongs_to_many+ and +has_many+ <tt>:through</tt>
+    # associations have records in join tables, as well as the associated records. So when we
+    # call one of these deletion methods, what exactly should be deleted?
+    #
+    # The answer is that it is assumed that deletion on an association is about removing the
+    # <i>link</i> between the owner and the associated object(s), rather than necessarily the
+    # associated objects themselves. So with +has_and_belongs_to_many+ and +has_many+
+    # <tt>:through</tt>, the join records will be deleted, but the associated records won't.
+    #
+    # This makes sense if you think about it: if you were to call <tt>post.tags.delete(Tag.find_by_name('food'))</tt>
+    # you would want the 'food' tag to be unlinked from the post, rather than for the tag itself
+    # to be removed from the database.
+    #
+    # However, there are examples where this strategy doesn't make sense. For example, suppose
+    # a person has many projects, and each project has many tasks. If we deleted one of a person's
+    # tasks, we would probably not want the project to be deleted. In this scenario, the delete method
+    # won't actually work: it can only be used if the association on the join model is a
+    # +belongs_to+. In other situations you are expected to perform operations directly on
+    # either the associated records or the <tt>:through</tt> association.
+    #
+    # With a regular +has_many+ there is no distinction between the "associated records"
+    # and the "link", so there is only one choice for what gets deleted.
+    #
+    # With +has_and_belongs_to_many+ and +has_many+ <tt>:through</tt>, if you want to delete the
+    # associated records themselves, you can always do something along the lines of
+    # <tt>person.tasks.each(&:destroy)</tt>.
+    #
     # == Type safety with <tt>ActiveRecord::AssociationTypeMismatch</tt>
     #
     # If you attempt to assign an object to an association that doesn't match the inferred
@@ -820,6 +992,10 @@ module ActiveRecord
       #   Removes one or more objects from the collection by setting their foreign keys to +NULL+.
       #   Objects will be in addition destroyed if they're associated with <tt>:dependent => :destroy</tt>,
       #   and deleted if they're associated with <tt>:dependent => :delete_all</tt>.
+      #
+      #   If the <tt>:through</tt> option is used, then the join records are deleted (rather than
+      #   nullified) by default, but you can specify <tt>:dependent => :destroy</tt> or
+      #   <tt>:dependent => :nullify</tt> to override this.
       # [collection=objects]
       #   Replaces the collections content by deleting and adding objects as appropriate. If the <tt>:through</tt>
       #   option is true callbacks in the join models are triggered except destroy callbacks, since deletion is
@@ -875,7 +1051,7 @@ module ActiveRecord
       # * <tt>Firm#clients.create</tt> (similar to <tt>c = Client.new("firm_id" => id); c.save; c</tt>)
       # The declaration can also include an options hash to specialize the behavior of the association.
       #
-      # === Supported options
+      # === Options
       # [:class_name]
       #   Specify the class name of the association. Use it only if that name can't be inferred
       #   from the association name. So <tt>has_many :products</tt> will by default be linked
@@ -903,7 +1079,9 @@ module ActiveRecord
       #   objects' foreign keys are set to +NULL+ *without* calling their +save+ callbacks. If set to
       #   <tt>:restrict</tt> this object cannot be deleted if it has any associated object.
       #
-      #   *Warning:* This option is ignored when used with <tt>:through</tt> option.
+      #   If using with the <tt>:through</tt> option, the association on the join model must be
+      #   a +belongs_to+, and the records which get deleted are the join records, rather than
+      #   the associated records.
       #
       # [:finder_sql]
       #   Specify a complete SQL statement to fetch the association. This is a good way to go for complex
@@ -934,13 +1112,21 @@ module ActiveRecord
       # [:as]
       #   Specifies a polymorphic interface (See <tt>belongs_to</tt>).
       # [:through]
-      #   Specifies a join model through which to perform the query.  Options for <tt>:class_name</tt>
-      #   and <tt>:foreign_key</tt> are ignored, as the association uses the source reflection. You
-      #   can only use a <tt>:through</tt> query through a <tt>belongs_to</tt>, <tt>has_one</tt>
-      #   or <tt>has_many</tt> association on the join model. The collection of join models
-      #   can be managed via the collection API. For example, new join models are created for
-      #   newly associated objects, and if some are gone their rows are deleted (directly,
-      #   no destroy callbacks are triggered).
+      #   Specifies an association through which to perform the query. This can be any other type
+      #   of association, including other <tt>:through</tt> associations. Options for <tt>:class_name</tt>,
+      #   <tt>:primary_key</tt> and <tt>:foreign_key</tt> are ignored, as the association uses the
+      #   source reflection.
+      #
+      #   If the association on the join model is a +belongs_to+, the collection can be modified
+      #   and the records on the <tt>:through</tt> model will be automatically created and removed
+      #   as appropriate. Otherwise, the collection is read-only, so you should manipulate the
+      #   <tt>:through</tt> association directly.
+      #
+      #   If you are going to modify the association (rather than just read from it), then it is
+      #   a good idea to set the <tt>:inverse_of</tt> option on the source association on the
+      #   join model. This allows associated records to be built which will automatically create
+      #   the appropriate join model records when they are saved. (See the 'Association Join Models'
+      #   section above.)
       # [:source]
       #   Specifies the source association name used by <tt>has_many :through</tt> queries.
       #   Only use it if the name cannot be inferred from the association.
@@ -979,16 +1165,8 @@ module ActiveRecord
       #       'FROM people p, post_subscriptions ps ' +
       #       'WHERE ps.post_id = #{id} AND ps.person_id = p.id ' +
       #       'ORDER BY p.first_name'
-      def has_many(association_id, options = {}, &extension)
-        reflection = create_has_many_reflection(association_id, options, &extension)
-        configure_dependency_for_has_many(reflection)
-        add_association_callbacks(reflection.name, reflection.options)
-
-        if options[:through]
-          collection_accessor_methods(reflection, HasManyThroughAssociation)
-        else
-          collection_accessor_methods(reflection, HasManyAssociation)
-        end
+      def has_many(name, options = {}, &extension)
+        Builder::HasMany.build(self, name, options, &extension)
       end
 
       # Specifies a one-to-one association with another class. This method should only be used
@@ -1006,12 +1184,14 @@ module ActiveRecord
       # [build_association(attributes = {})]
       #   Returns a new object of the associated type that has been instantiated
       #   with +attributes+ and linked to this object through a foreign key, but has not
-      #   yet been saved. <b>Note:</b> This ONLY works if an association already exists.
-      #   It will NOT work if the association is +nil+.
+      #   yet been saved.
       # [create_association(attributes = {})]
       #   Returns a new object of the associated type that has been instantiated
       #   with +attributes+, linked to this object through a foreign key, and that
       #   has already been saved (if it passed the validation).
+      # [create_association!(attributes = {})]
+      #   Does the same as <tt>create_association</tt>, but raises <tt>ActiveRecord::RecordInvalid</tt>
+      #   if the record is invalid.
       #
       # (+association+ is replaced with the symbol passed as the first argument, so
       # <tt>has_one :manager</tt> would add among others <tt>manager.nil?</tt>.)
@@ -1023,6 +1203,7 @@ module ActiveRecord
       # * <tt>Account#beneficiary=(beneficiary)</tt> (similar to <tt>beneficiary.account_id = account.id; beneficiary.save</tt>)
       # * <tt>Account#build_beneficiary</tt> (similar to <tt>Beneficiary.new("account_id" => id)</tt>)
       # * <tt>Account#create_beneficiary</tt> (similar to <tt>b = Beneficiary.new("account_id" => id); b.save; b</tt>)
+      # * <tt>Account#create_beneficiary!</tt> (similar to <tt>b = Beneficiary.new("account_id" => id); b.save!; b</tt>)
       #
       # === Options
       #
@@ -1061,10 +1242,10 @@ module ActiveRecord
       #   you want to do a join but not include the joined columns. Do not forget to include the
       #   primary and foreign keys, otherwise it will raise an error.
       # [:through]
-      #   Specifies a Join Model through which to perform the query.  Options for <tt>:class_name</tt>
-      #   and <tt>:foreign_key</tt> are ignored, as the association uses the source reflection. You
-      #   can only use a <tt>:through</tt> query through a <tt>has_one</tt> or <tt>belongs_to</tt>
-      #   association on the join model.
+      #   Specifies a Join Model through which to perform the query.  Options for <tt>:class_name</tt>,
+      #   <tt>:primary_key</tt>, and <tt>:foreign_key</tt> are ignored, as the association uses the
+      #   source reflection. You can only use a <tt>:through</tt> query through a <tt>has_one</tt>
+      #   or <tt>belongs_to</tt> association on the join model.
       # [:source]
       #   Specifies the source association name used by <tt>has_one :through</tt> queries.
       #   Only use it if the name cannot be inferred from the association.
@@ -1097,17 +1278,8 @@ module ActiveRecord
       #   has_one :boss, :readonly => :true
       #   has_one :club, :through => :membership
       #   has_one :primary_address, :through => :addressables, :conditions => ["addressable.primary = ?", true], :source => :addressable
-      def has_one(association_id, options = {})
-        if options[:through]
-          reflection = create_has_one_through_reflection(association_id, options)
-          association_accessor_methods(reflection, ActiveRecord::Associations::HasOneThroughAssociation)
-        else
-          reflection = create_has_one_reflection(association_id, options)
-          association_accessor_methods(reflection, HasOneAssociation)
-          association_constructor_method(:build,  reflection, HasOneAssociation)
-          association_constructor_method(:create, reflection, HasOneAssociation)
-          configure_dependency_for_has_one(reflection)
-        end
+      def has_one(name, options = {})
+        Builder::HasOne.build(self, name, options)
       end
 
       # Specifies a one-to-one association with another class. This method should only be used
@@ -1129,6 +1301,9 @@ module ActiveRecord
       #   Returns a new object of the associated type that has been instantiated
       #   with +attributes+, linked to this object through a foreign key, and that
       #   has already been saved (if it passed the validation).
+      # [create_association!(attributes = {})]
+      #   Does the same as <tt>create_association</tt>, but raises <tt>ActiveRecord::RecordInvalid</tt>
+      #   if the record is invalid.
       #
       # (+association+ is replaced with the symbol passed as the first argument, so
       # <tt>belongs_to :author</tt> would add among others <tt>author.nil?</tt>.)
@@ -1140,6 +1315,7 @@ module ActiveRecord
       # * <tt>Post#author=(author)</tt> (similar to <tt>post.author_id = author.id</tt>)
       # * <tt>Post#build_author</tt> (similar to <tt>post.author = Author.new</tt>)
       # * <tt>Post#create_author</tt> (similar to <tt>post.author = Author.new; post.author.save; post.author</tt>)
+      # * <tt>Post#create_author!</tt> (similar to <tt>post.author = Author.new; post.author.save!; post.author</tt>)
       # The declaration can also include an options hash to specialize the behavior of the association.
       #
       # === Options
@@ -1161,6 +1337,11 @@ module ActiveRecord
       #   association will use "person_id" as the default <tt>:foreign_key</tt>. Similarly,
       #   <tt>belongs_to :favorite_person, :class_name => "Person"</tt> will use a foreign key
       #   of "favorite_person_id".
+      # [:foreign_type]
+      #   Specify the column used to store the associated object's type, if this is a polymorphic
+      #   association. By default this is guessed to be the name of the association with a "_type"
+      #   suffix. So a class that defines a <tt>belongs_to :taggable, :polymorphic => true</tt>
+      #   association will use "taggable_type" as the default <tt>:foreign_type</tt>.
       # [:primary_key]
       #   Specify the method that returns the primary key of associated object used for the association.
       #   By default this is id.
@@ -1216,21 +1397,8 @@ module ActiveRecord
       #   belongs_to :post, :counter_cache => true
       #   belongs_to :company, :touch => true
       #   belongs_to :company, :touch => :employees_last_updated_at
-      def belongs_to(association_id, options = {})
-        reflection = create_belongs_to_reflection(association_id, options)
-
-        if reflection.options[:polymorphic]
-          association_accessor_methods(reflection, BelongsToPolymorphicAssociation)
-        else
-          association_accessor_methods(reflection, BelongsToAssociation)
-          association_constructor_method(:build,  reflection, BelongsToAssociation)
-          association_constructor_method(:create, reflection, BelongsToAssociation)
-        end
-
-        add_counter_cache_callbacks(reflection)          if options[:counter_cache]
-        add_touch_callbacks(reflection, options[:touch]) if options[:touch]
-
-        configure_dependency_for_belongs_to(reflection)
+      def belongs_to(name, options = {})
+        Builder::BelongsTo.build(self, name, options)
       end
 
       # Specifies a many-to-many relationship with another class. This associates two classes via an
@@ -1261,12 +1429,6 @@ module ActiveRecord
       #     end
       #   end
       #
-      # Deprecated: Any additional fields added to the join table will be placed as attributes when
-      # pulling records out through +has_and_belongs_to_many+ associations. Records returned from join
-      # tables with additional attributes will be marked as readonly (because we can't save changes
-      # to the additional attributes). It's strongly recommended that you upgrade any
-      # associations with attributes to a real join model (see introduction).
-      #
       # Adds the following methods for retrieval and query:
       #
       # [collection(force_reload = false)]
@@ -1407,898 +1569,9 @@ module ActiveRecord
       #   has_and_belongs_to_many :categories, :readonly => true
       #   has_and_belongs_to_many :active_projects, :join_table => 'developers_projects', :delete_sql =>
       #   'DELETE FROM developers_projects WHERE active=1 AND developer_id = #{id} AND project_id = #{record.id}'
-      def has_and_belongs_to_many(association_id, options = {}, &extension)
-        reflection = create_has_and_belongs_to_many_reflection(association_id, options, &extension)
-        collection_accessor_methods(reflection, HasAndBelongsToManyAssociation)
-
-        configure_destroy_hook_for_has_and_belongs_to_many(reflection)
-
-        add_association_callbacks(reflection.name, options)
+      def has_and_belongs_to_many(name, options = {}, &extension)
+        Builder::HasAndBelongsToMany.build(self, name, options, &extension)
       end
-
-      private
-        # Generates a join table name from two provided table names.
-        # The names in the join table names end up in lexicographic order.
-        #
-        #   join_table_name("members", "clubs")         # => "clubs_members"
-        #   join_table_name("members", "special_clubs") # => "members_special_clubs"
-        def join_table_name(first_table_name, second_table_name)
-          if first_table_name < second_table_name
-            join_table = "#{first_table_name}_#{second_table_name}"
-          else
-            join_table = "#{second_table_name}_#{first_table_name}"
-          end
-
-          table_name_prefix + join_table + table_name_suffix
-        end
-
-        def association_accessor_methods(reflection, association_proxy_class)
-          redefine_method(reflection.name) do |*params|
-            force_reload = params.first unless params.empty?
-            association = association_instance_get(reflection.name)
-
-            if association.nil? || force_reload
-              association = association_proxy_class.new(self, reflection)
-              retval = force_reload ? reflection.klass.uncached { association.reload } : association._load
-              if retval.nil? and association_proxy_class == BelongsToAssociation
-                association_instance_set(reflection.name, nil)
-                return nil
-              end
-              association_instance_set(reflection.name, association)
-            end
-
-            association.target.nil? ? nil : association
-          end
-
-          redefine_method("loaded_#{reflection.name}?") do
-            association = association_instance_get(reflection.name)
-            association && association.loaded?
-          end
-
-          redefine_method("#{reflection.name}=") do |new_value|
-            association = association_instance_get(reflection.name)
-
-            if association.nil? || association.target != new_value
-              association = association_proxy_class.new(self, reflection)
-            end
-
-            association.replace(new_value)
-            association_instance_set(reflection.name, new_value.nil? ? nil : association)
-          end
-
-          redefine_method("set_#{reflection.name}_target") do |target|
-            return if target.nil? and association_proxy_class == BelongsToAssociation
-            association = association_proxy_class.new(self, reflection)
-            association.target = target
-            association_instance_set(reflection.name, association)
-          end
-        end
-
-        def collection_reader_method(reflection, association_proxy_class)
-          redefine_method(reflection.name) do |*params|
-            force_reload = params.first unless params.empty?
-            association = association_instance_get(reflection.name)
-
-            unless association
-              association = association_proxy_class.new(self, reflection)
-              association_instance_set(reflection.name, association)
-            end
-
-            reflection.klass.uncached { association.reload } if force_reload
-
-            association
-          end
-
-          redefine_method("#{reflection.name.to_s.singularize}_ids") do
-            if send(reflection.name).loaded? || reflection.options[:finder_sql]
-              send(reflection.name).map { |r| r.id }
-            else
-              if reflection.through_reflection && reflection.source_reflection.belongs_to?
-                through = reflection.through_reflection
-                primary_key = reflection.source_reflection.primary_key_name
-                send(through.name).select("DISTINCT #{through.quoted_table_name}.#{primary_key}").map! { |r| r.send(primary_key) }
-              else
-                send(reflection.name).select("#{reflection.quoted_table_name}.#{reflection.klass.primary_key}").except(:includes).map! { |r| r.id }
-              end
-            end
-          end
-
-        end
-
-        def collection_accessor_methods(reflection, association_proxy_class, writer = true)
-          collection_reader_method(reflection, association_proxy_class)
-
-          if writer
-            redefine_method("#{reflection.name}=") do |new_value|
-              # Loads proxy class instance (defined in collection_reader_method) if not already loaded
-              association = send(reflection.name)
-              association.replace(new_value)
-              association
-            end
-
-            redefine_method("#{reflection.name.to_s.singularize}_ids=") do |new_value|
-              pk_column = reflection.primary_key_column
-              ids = (new_value || []).reject { |nid| nid.blank? }
-              ids.map!{ |i| pk_column.type_cast(i) }
-              send("#{reflection.name}=", reflection.klass.find(ids).index_by{ |r| r.id }.values_at(*ids))
-            end
-          end
-        end
-
-        def association_constructor_method(constructor, reflection, association_proxy_class)
-          redefine_method("#{constructor}_#{reflection.name}") do |*params|
-            attributees      = params.first unless params.empty?
-            replace_existing = params[1].nil? ? true : params[1]
-            association      = association_instance_get(reflection.name)
-
-            unless association
-              association = association_proxy_class.new(self, reflection)
-              association_instance_set(reflection.name, association)
-            end
-
-            if association_proxy_class == HasOneAssociation
-              association.send(constructor, attributees, replace_existing)
-            else
-              association.send(constructor, attributees)
-            end
-          end
-        end
-
-        def add_counter_cache_callbacks(reflection)
-          cache_column = reflection.counter_cache_column
-
-          method_name = "belongs_to_counter_cache_after_create_for_#{reflection.name}".to_sym
-          define_method(method_name) do
-            association = send(reflection.name)
-            association.class.increment_counter(cache_column, association.id) unless association.nil?
-          end
-          after_create(method_name)
-
-          method_name = "belongs_to_counter_cache_before_destroy_for_#{reflection.name}".to_sym
-          define_method(method_name) do
-            association = send(reflection.name)
-            association.class.decrement_counter(cache_column, association.id) unless association.nil?
-          end
-          before_destroy(method_name)
-
-          module_eval(
-            "#{reflection.class_name}.send(:attr_readonly,\"#{cache_column}\".intern) if defined?(#{reflection.class_name}) && #{reflection.class_name}.respond_to?(:attr_readonly)", __FILE__, __LINE__
-          )
-        end
-
-        def add_touch_callbacks(reflection, touch_attribute)
-          method_name = :"belongs_to_touch_after_save_or_destroy_for_#{reflection.name}"
-          redefine_method(method_name) do
-            association = send(reflection.name)
-
-            if touch_attribute == true
-              association.touch unless association.nil?
-            else
-              association.touch(touch_attribute) unless association.nil?
-            end
-          end
-          after_save(method_name)
-          after_touch(method_name)
-          after_destroy(method_name)
-        end
-
-        # Creates before_destroy callback methods that nullify, delete or destroy
-        # has_many associated objects, according to the defined :dependent rule.
-        # If the association is marked as :dependent => :restrict, create a callback
-        # that prevents deleting entirely.
-        #
-        # See HasManyAssociation#delete_records.  Dependent associations
-        # delete children, otherwise foreign key is set to NULL.
-        # See HasManyAssociation#delete_records. Dependent associations
-        # delete children if the option is set to :destroy or :delete_all, set the
-        # foreign key to NULL if the option is set to :nullify, and do not touch the
-        # child records if the option is set to :restrict.
-        #
-        # The +extra_conditions+ parameter, which is not used within the main
-        # Active Record codebase, is meant to allow plugins to define extra
-        # finder conditions.
-        def configure_dependency_for_has_many(reflection, extra_conditions = nil)
-          if reflection.options.include?(:dependent)
-            case reflection.options[:dependent]
-              when :destroy
-                method_name = "has_many_dependent_destroy_for_#{reflection.name}".to_sym
-                define_method(method_name) do
-                  send(reflection.name).each do |o|
-                    # No point in executing the counter update since we're going to destroy the parent anyway
-                    counter_method = ('belongs_to_counter_cache_before_destroy_for_' + self.class.name.downcase).to_sym
-                    if(o.respond_to? counter_method) then
-                      class << o
-                        self
-                      end.send(:define_method, counter_method, Proc.new {})
-                    end
-                    o.destroy
-                  end
-                end
-                before_destroy method_name
-              when :delete_all
-                before_destroy do |record|
-                  self.class.send(:delete_all_has_many_dependencies,
-                  record,
-                  reflection.name,
-                  reflection.klass,
-                  reflection.dependent_conditions(record, self.class, extra_conditions))
-                end
-              when :nullify
-                before_destroy do |record|
-                  self.class.send(:nullify_has_many_dependencies,
-                  record,
-                  reflection.name,
-                  reflection.klass,
-                  reflection.primary_key_name,
-                  reflection.dependent_conditions(record, self.class, extra_conditions))
-                end
-              when :restrict
-                method_name = "has_many_dependent_restrict_for_#{reflection.name}".to_sym
-                define_method(method_name) do
-                  unless send(reflection.name).empty?
-                    raise DeleteRestrictionError.new(reflection)
-                  end
-                end
-                before_destroy method_name
-              else
-                raise ArgumentError, "The :dependent option expects either :destroy, :delete_all, :nullify or :restrict (#{reflection.options[:dependent].inspect})"
-            end
-          end
-        end
-
-        # Creates before_destroy callback methods that nullify, delete or destroy
-        # has_one associated objects, according to the defined :dependent rule.
-        # If the association is marked as :dependent => :restrict, create a callback
-        # that prevents deleting entirely.
-        def configure_dependency_for_has_one(reflection)
-          if reflection.options.include?(:dependent)
-            name = reflection.options[:dependent]
-            method_name = :"has_one_dependent_#{name}_for_#{reflection.name}"
-
-            case name
-              when :destroy, :delete
-                class_eval <<-eoruby, __FILE__, __LINE__ + 1
-                  def #{method_name}
-                    association = #{reflection.name}
-                    association.#{name} if association
-                  end
-                eoruby
-              when :nullify
-                class_eval <<-eoruby, __FILE__, __LINE__ + 1
-                  def #{method_name}
-                    association = #{reflection.name}
-                    association.update_attribute(#{reflection.primary_key_name.inspect}, nil) if association
-                  end
-                eoruby
-              when :restrict
-                method_name = "has_one_dependent_restrict_for_#{reflection.name}".to_sym
-                define_method(method_name) do
-                  unless send(reflection.name).nil?
-                    raise DeleteRestrictionError.new(reflection)
-                  end
-                end
-                before_destroy method_name
-              else
-                raise ArgumentError, "The :dependent option expects either :destroy, :delete, :nullify or :restrict (#{reflection.options[:dependent].inspect})"
-            end
-
-            before_destroy method_name
-          end
-        end
-
-        def configure_dependency_for_belongs_to(reflection)
-          if reflection.options.include?(:dependent)
-            name = reflection.options[:dependent]
-
-            unless [:destroy, :delete].include?(name)
-              raise ArgumentError, "The :dependent option expects either :destroy or :delete (#{reflection.options[:dependent].inspect})"
-            end
-
-            method_name = :"belongs_to_dependent_#{name}_for_#{reflection.name}"
-            class_eval <<-eoruby, __FILE__, __LINE__ + 1
-              def #{method_name}
-                association = #{reflection.name}
-                association.#{name} if association
-              end
-            eoruby
-            after_destroy method_name
-          end
-        end
-
-        def configure_destroy_hook_for_has_and_belongs_to_many(reflection)
-          include(Module.new {
-            class_eval <<-RUBY, __FILE__, __LINE__ + 1
-              def destroy_associations
-                association = #{reflection.name}
-                association.delete_all if association
-                super
-              end
-            RUBY
-          })
-        end
-
-        def delete_all_has_many_dependencies(record, reflection_name, association_class, dependent_conditions)
-          association_class.delete_all(dependent_conditions)
-        end
-
-        def nullify_has_many_dependencies(record, reflection_name, association_class, primary_key_name, dependent_conditions)
-          association_class.update_all("#{primary_key_name} = NULL", dependent_conditions)
-        end
-
-        mattr_accessor :valid_keys_for_has_many_association
-        @@valid_keys_for_has_many_association = [
-          :class_name, :table_name, :foreign_key, :primary_key,
-          :dependent,
-          :select, :conditions, :include, :order, :group, :having, :limit, :offset,
-          :as, :through, :source, :source_type,
-          :uniq,
-          :finder_sql, :counter_sql,
-          :before_add, :after_add, :before_remove, :after_remove,
-          :extend, :readonly,
-          :validate, :inverse_of
-        ]
-
-        def create_has_many_reflection(association_id, options, &extension)
-          options.assert_valid_keys(valid_keys_for_has_many_association)
-          options[:extend] = create_extension_modules(association_id, extension, options[:extend])
-
-          create_reflection(:has_many, association_id, options, self)
-        end
-
-        mattr_accessor :valid_keys_for_has_one_association
-        @@valid_keys_for_has_one_association = [
-          :class_name, :foreign_key, :remote, :select, :conditions, :order,
-          :include, :dependent, :counter_cache, :extend, :as, :readonly,
-          :validate, :primary_key, :inverse_of
-        ]
-
-        def create_has_one_reflection(association_id, options)
-          options.assert_valid_keys(valid_keys_for_has_one_association)
-          create_reflection(:has_one, association_id, options, self)
-        end
-
-        def create_has_one_through_reflection(association_id, options)
-          options.assert_valid_keys(
-            :class_name, :foreign_key, :remote, :select, :conditions, :order, :include, :dependent, :counter_cache, :extend, :as, :through, :source, :source_type, :validate
-          )
-          create_reflection(:has_one, association_id, options, self)
-        end
-
-        mattr_accessor :valid_keys_for_belongs_to_association
-        @@valid_keys_for_belongs_to_association = [
-          :class_name, :primary_key, :foreign_key, :foreign_type, :remote, :select, :conditions,
-          :include, :dependent, :counter_cache, :extend, :polymorphic, :readonly,
-          :validate, :touch, :inverse_of
-        ]
-
-        def create_belongs_to_reflection(association_id, options)
-          options.assert_valid_keys(valid_keys_for_belongs_to_association)
-          reflection = create_reflection(:belongs_to, association_id, options, self)
-
-          if options[:polymorphic]
-            reflection.options[:foreign_type] ||= reflection.class_name.underscore + "_type"
-          end
-
-          reflection
-        end
-
-        mattr_accessor :valid_keys_for_has_and_belongs_to_many_association
-        @@valid_keys_for_has_and_belongs_to_many_association = [
-          :class_name, :table_name, :join_table, :foreign_key, :association_foreign_key,
-          :select, :conditions, :include, :order, :group, :having, :limit, :offset,
-          :uniq,
-          :finder_sql, :counter_sql, :delete_sql, :insert_sql,
-          :before_add, :after_add, :before_remove, :after_remove,
-          :extend, :readonly,
-          :validate
-        ]
-
-        def create_has_and_belongs_to_many_reflection(association_id, options, &extension)
-          options.assert_valid_keys(valid_keys_for_has_and_belongs_to_many_association)
-          options[:extend] = create_extension_modules(association_id, extension, options[:extend])
-
-          reflection = create_reflection(:has_and_belongs_to_many, association_id, options, self)
-
-          if reflection.association_foreign_key == reflection.primary_key_name
-            raise HasAndBelongsToManyAssociationForeignKeyNeeded.new(reflection)
-          end
-
-          reflection.options[:join_table] ||= join_table_name(undecorated_table_name(self.to_s), undecorated_table_name(reflection.class_name))
-          if connection.supports_primary_key? && (connection.primary_key(reflection.options[:join_table]) rescue false)
-             raise HasAndBelongsToManyAssociationWithPrimaryKeyError.new(reflection)
-          end
-
-          reflection
-        end
-
-        def add_association_callbacks(association_name, options)
-          callbacks = %w(before_add after_add before_remove after_remove)
-          callbacks.each do |callback_name|
-            full_callback_name = "#{callback_name}_for_#{association_name}"
-            defined_callbacks = options[callback_name.to_sym]
-            if options.has_key?(callback_name.to_sym)
-              class_inheritable_reader full_callback_name.to_sym
-              write_inheritable_attribute(full_callback_name.to_sym, [defined_callbacks].flatten)
-            else
-              write_inheritable_attribute(full_callback_name.to_sym, [])
-            end
-          end
-        end
-
-        def create_extension_modules(association_id, block_extension, extensions)
-          if block_extension
-            extension_module_name = "#{self.to_s.demodulize}#{association_id.to_s.camelize}AssociationExtension"
-
-            silence_warnings do
-              self.parent.const_set(extension_module_name, Module.new(&block_extension))
-            end
-            Array.wrap(extensions).push("#{self.parent}::#{extension_module_name}".constantize)
-          else
-            Array.wrap(extensions)
-          end
-        end
-
-        class JoinDependency # :nodoc:
-          attr_reader :joins, :reflections, :table_aliases
-
-          def initialize(base, associations, joins)
-            @joins                 = [JoinBase.new(base, joins)]
-            @associations          = {}
-            @reflections           = []
-            @base_records_hash     = {}
-            @base_records_in_order = []
-            @table_aliases         = Hash.new { |aliases, table| aliases[table] = 0 }
-            @table_aliases[base.table_name] = 1
-            build(associations)
-          end
-
-          def graft(*associations)
-            associations.each do |association|
-              join_associations.detect {|a| association == a} ||
-              build(association.reflection.name, association.find_parent_in(self) || join_base, association.join_type)
-            end
-            self
-          end
-
-          def join_associations
-            @joins[1..-1].to_a
-          end
-
-          def join_base
-            @joins[0]
-          end
-
-          def count_aliases_from_table_joins(name)
-            # quoted_name should be downcased as some database adapters (Oracle) return quoted name in uppercase
-            quoted_name = join_base.active_record.connection.quote_table_name(name.downcase).downcase
-            join_sql = join_base.table_joins.to_s.downcase
-            join_sql.blank? ? 0 :
-              # Table names
-              join_sql.scan(/join(?:\s+\w+)?\s+#{quoted_name}\son/).size +
-              # Table aliases
-              join_sql.scan(/join(?:\s+\w+)?\s+\S+\s+#{quoted_name}\son/).size
-          end
-
-          def instantiate(rows)
-            rows.each_with_index do |row, i|
-              primary_id = join_base.record_id(row)
-              unless @base_records_hash[primary_id]
-                @base_records_in_order << (@base_records_hash[primary_id] = join_base.instantiate(row))
-              end
-              construct(@base_records_hash[primary_id], @associations, join_associations.dup, row)
-            end
-            remove_duplicate_results!(join_base.active_record, @base_records_in_order, @associations)
-            return @base_records_in_order
-          end
-
-          def remove_duplicate_results!(base, records, associations)
-            case associations
-              when Symbol, String
-                reflection = base.reflections[associations]
-                remove_uniq_by_reflection(reflection, records)
-              when Array
-                associations.each do |association|
-                  remove_duplicate_results!(base, records, association)
-                end
-              when Hash
-                associations.keys.each do |name|
-                  reflection = base.reflections[name]
-                  remove_uniq_by_reflection(reflection, records)
-
-                  parent_records = []
-                  records.each do |record|
-                    if descendant = record.send(reflection.name)
-                      if reflection.collection?
-                        parent_records.concat descendant.target.uniq
-                      else
-                        parent_records << descendant
-                      end
-                    end
-                  end
-
-                  remove_duplicate_results!(reflection.klass, parent_records, associations[name]) unless parent_records.empty?
-                end
-            end
-          end
-
-          protected
-
-            def cache_joined_association(association)
-              associations = []
-              parent = association.parent
-              while parent != join_base
-                associations.unshift(parent.reflection.name)
-                parent = parent.parent
-              end
-              ref = @associations
-              associations.each do |key|
-                ref = ref[key]
-              end
-              ref[association.reflection.name] ||= {}
-            end
-
-            def build(associations, parent = nil, join_type = Arel::InnerJoin)
-              parent ||= @joins.last
-              case associations
-                when Symbol, String
-                  reflection = parent.reflections[associations.to_s.intern] or
-                  raise ConfigurationError, "Association named '#{ associations }' was not found; perhaps you misspelled it?"
-                  unless join_association = find_join_association(reflection, parent)
-                    @reflections << reflection
-                    join_association = build_join_association(reflection, parent)
-                    join_association.join_type = join_type
-                    @joins << join_association
-                    cache_joined_association(join_association)
-                  end
-                  join_association
-                when Array
-                  associations.each do |association|
-                    build(association, parent, join_type)
-                  end
-                when Hash
-                  associations.keys.sort{|a,b|a.to_s<=>b.to_s}.each do |name|
-                    join_association = build(name, parent, join_type)
-                    build(associations[name], join_association, join_type)
-                  end
-                else
-                  raise ConfigurationError, associations.inspect
-              end
-            end
-
-            def find_join_association(name_or_reflection, parent)
-              case name_or_reflection
-              when Symbol, String
-                join_associations.detect {|j| (j.reflection.name == name_or_reflection.to_s.intern) && (j.parent == parent)}
-              else
-                join_associations.detect {|j| (j.reflection == name_or_reflection) && (j.parent == parent)}
-              end
-            end
-
-            def remove_uniq_by_reflection(reflection, records)
-              if reflection && reflection.collection?
-                records.each { |record| record.send(reflection.name).target.uniq! }
-              end
-            end
-
-            def build_join_association(reflection, parent)
-              JoinAssociation.new(reflection, self, parent)
-            end
-
-            def construct(parent, associations, joins, row)
-              case associations
-                when Symbol, String
-                  join = joins.detect{|j| j.reflection.name.to_s == associations.to_s && j.parent_table_name == parent.class.table_name }
-                  raise(ConfigurationError, "No such association") if join.nil?
-
-                  joins.delete(join)
-                  construct_association(parent, join, row)
-                when Array
-                  associations.each do |association|
-                    construct(parent, association, joins, row)
-                  end
-                when Hash
-                  associations.keys.sort{|a,b|a.to_s<=>b.to_s}.each do |name|
-                    join = joins.detect{|j| j.reflection.name.to_s == name.to_s && j.parent_table_name == parent.class.table_name }
-                    raise(ConfigurationError, "No such association") if join.nil?
-
-                    association = construct_association(parent, join, row)
-                    joins.delete(join)
-                    construct(association, associations[name], joins, row) if association
-                  end
-                else
-                  raise ConfigurationError, associations.inspect
-              end
-            end
-
-            def construct_association(record, join, row)
-              case join.reflection.macro
-                when :has_many, :has_and_belongs_to_many
-                  collection = record.send(join.reflection.name)
-                  collection.loaded
-
-                  return nil if record.id.to_s != join.parent.record_id(row).to_s or row[join.aliased_primary_key].nil?
-                  association = join.instantiate(row)
-                  collection.target.push(association)
-                  collection.__send__(:set_inverse_instance, association, record)
-                when :has_one
-                  return if record.id.to_s != join.parent.record_id(row).to_s
-                  return if record.instance_variable_defined?("@#{join.reflection.name}")
-                  association = join.instantiate(row) unless row[join.aliased_primary_key].nil?
-                  set_target_and_inverse(join, association, record)
-                when :belongs_to
-                  return if record.id.to_s != join.parent.record_id(row).to_s or row[join.aliased_primary_key].nil?
-                  association = join.instantiate(row)
-                  set_target_and_inverse(join, association, record)
-                else
-                  raise ConfigurationError, "unknown macro: #{join.reflection.macro}"
-              end
-              return association
-            end
-
-            def set_target_and_inverse(join, association, record)
-              association_proxy = record.send("set_#{join.reflection.name}_target", association)
-              association_proxy.__send__(:set_inverse_instance, association, record)
-            end
-
-          class JoinBase # :nodoc:
-            attr_reader :active_record, :table_joins
-            delegate    :table_name, :column_names, :primary_key, :reflections, :sanitize_sql, :arel_engine, :to => :active_record
-
-            def initialize(active_record, joins = nil)
-              @active_record = active_record
-              @cached_record = {}
-              @table_joins   = joins
-            end
-
-            def ==(other)
-              other.class == self.class &&
-              other.active_record == active_record
-            end
-
-            def aliased_prefix
-              "t0"
-            end
-
-            def aliased_primary_key
-              "#{aliased_prefix}_r0"
-            end
-
-            def aliased_table_name
-              active_record.table_name
-            end
-
-            def column_names_with_alias
-              unless defined?(@column_names_with_alias)
-                @column_names_with_alias = []
-
-                ([primary_key] + (column_names - [primary_key])).each_with_index do |column_name, i|
-                  @column_names_with_alias << [column_name, "#{aliased_prefix}_r#{i}"]
-                end
-              end
-
-              @column_names_with_alias
-            end
-
-            def extract_record(row)
-              Hash[column_names_with_alias.map{|cn, an| [cn, row[an]]}]
-            end
-
-            def record_id(row)
-              row[aliased_primary_key]
-            end
-
-            def instantiate(row)
-              @cached_record[record_id(row)] ||= active_record.send(:instantiate, extract_record(row))
-            end
-          end
-
-          class JoinAssociation < JoinBase # :nodoc:
-            attr_reader :reflection, :parent, :aliased_table_name, :aliased_prefix, :aliased_join_table_name, :parent_table_name
-            # What type of join will be generated, either Arel::InnerJoin (default) or Arel::OuterJoin
-            attr_accessor :join_type
-            delegate    :options, :klass, :through_reflection, :source_reflection, :to => :reflection
-
-            def initialize(reflection, join_dependency, parent = nil)
-              reflection.check_validity!
-              if reflection.options[:polymorphic]
-                raise EagerLoadPolymorphicError.new(reflection)
-              end
-
-              super(reflection.klass)
-              @join_dependency    = join_dependency
-              @parent             = parent
-              @reflection         = reflection
-              @aliased_prefix     = "t#{ join_dependency.joins.size }"
-              @parent_table_name  = parent.active_record.table_name
-              @aliased_table_name = aliased_table_name_for(table_name)
-              @join               = nil
-              @join_type          = Arel::InnerJoin
-
-              if reflection.macro == :has_and_belongs_to_many
-                @aliased_join_table_name = aliased_table_name_for(reflection.options[:join_table], "_join")
-              end
-
-              if [:has_many, :has_one].include?(reflection.macro) && reflection.options[:through]
-                @aliased_join_table_name = aliased_table_name_for(reflection.through_reflection.klass.table_name, "_join")
-              end
-            end
-
-            def ==(other)
-              other.class == self.class &&
-              other.reflection == reflection &&
-              other.parent == parent
-            end
-
-            def find_parent_in(other_join_dependency)
-              other_join_dependency.joins.detect do |join|
-                self.parent == join
-              end
-            end
-
-            def association_join
-              return @join if @join
-
-              aliased_table = Arel::Table.new(table_name, :as      => @aliased_table_name,
-                                                          :engine  => arel_engine,
-                                                          :columns => klass.columns)
-
-              parent_table = Arel::Table.new(parent.table_name, :as      => parent.aliased_table_name,
-                                                                :engine  => arel_engine,
-                                                                :columns => parent.active_record.columns)
-              as_conditions = reflection.options[:conditions] && process_conditions(reflection.options[:conditions], aliased_table_name)
-
-              @join = case reflection.macro
-              when :has_and_belongs_to_many
-                join_table = Arel::Table.new(options[:join_table], :as => aliased_join_table_name, :engine => arel_engine)
-                fk = options[:foreign_key] || reflection.active_record.to_s.foreign_key
-                klass_fk = options[:association_foreign_key] || klass.to_s.foreign_key
-
-                [
-                  join_table[fk].eq(parent_table[reflection.active_record.primary_key]),
-                  [aliased_table[klass.primary_key].eq(join_table[klass_fk]), as_conditions].reject{ |x| x.blank? }
-                ]
-              when :has_many, :has_one
-                if reflection.options[:through]
-                  join_table = Arel::Table.new(through_reflection.klass.table_name, :as => aliased_join_table_name, :engine => arel_engine)
-                  jt_as_conditions = through_reflection.options[:conditions] && process_conditions(through_reflection.options[:conditions], aliased_table_name)
-                  jt_as_extra = jt_source_extra = jt_sti_extra = nil
-                  first_key = second_key = as_extra = nil
-
-                  if through_reflection.macro == :belongs_to
-                    jt_primary_key = through_reflection.primary_key_name
-                    jt_foreign_key = through_reflection.association_primary_key
-                  else
-                    jt_primary_key = through_reflection.active_record_primary_key
-                    jt_foreign_key = through_reflection.primary_key_name
-
-                    if through_reflection.options[:as] # has_many :through against a polymorphic join
-                      jt_as_extra = join_table[through_reflection.options[:as].to_s + '_type'].eq(parent.active_record.base_class.name)
-                    end
-                  end
-
-                  case source_reflection.macro
-                  when :has_many, :has_one
-                    if source_reflection.options[:as]
-                      first_key   = "#{source_reflection.options[:as]}_id"
-                      second_key  = options[:foreign_key] || primary_key
-                      as_extra    = aliased_table["#{source_reflection.options[:as]}_type"].eq(source_reflection.active_record.base_class.name)
-                    else
-                      first_key   = through_reflection.klass.base_class.to_s.foreign_key
-                      second_key  = options[:foreign_key] || primary_key
-                    end
-
-                    unless through_reflection.klass.descends_from_active_record?
-                      jt_sti_extra = join_table[through_reflection.active_record.inheritance_column].eq(through_reflection.klass.sti_name)
-                    end
-                  when :belongs_to
-                    first_key = primary_key
-                    if reflection.options[:source_type]
-                      second_key = source_reflection.association_foreign_key
-                      jt_source_extra = join_table[reflection.source_reflection.options[:foreign_type]].eq(reflection.options[:source_type])
-                    else
-                      second_key = source_reflection.primary_key_name
-                    end
-                  end
-
-                  [
-                    [parent_table[jt_primary_key].eq(join_table[jt_foreign_key]), jt_as_extra, jt_source_extra, jt_sti_extra, jt_as_conditions].reject{|x| x.blank? },
-                    [aliased_table[first_key].eq(join_table[second_key]), as_extra, as_conditions].reject{ |x| x.blank? }
-                  ]
-                elsif reflection.options[:as]
-                  id_rel = aliased_table["#{reflection.options[:as]}_id"].eq(parent_table[parent.primary_key])
-                  type_rel = aliased_table["#{reflection.options[:as]}_type"].eq(parent.active_record.base_class.name)
-                  [id_rel, type_rel, as_conditions].reject{ |x| x.blank?}
-                else
-                  foreign_key = options[:foreign_key] || reflection.active_record.name.foreign_key
-                  [aliased_table[foreign_key].eq(parent_table[reflection.options[:primary_key] || parent.primary_key]), as_conditions].reject{ |x| x.blank? }
-                end
-              when :belongs_to
-                [aliased_table[options[:primary_key] || reflection.klass.primary_key].eq(parent_table[options[:foreign_key] || reflection.primary_key_name]), as_conditions].reject{ |x| x.blank? }
-              end
-
-              unless klass.descends_from_active_record?
-                sti_column = aliased_table[klass.inheritance_column]
-                sti_condition = sti_column.eq(klass.sti_name)
-                klass.descendants.each {|subclass| sti_condition = sti_condition.or(sti_column.eq(subclass.sti_name)) }
-
-                @join << sti_condition
-              end
-
-              @join
-            end
-
-            def relation
-              aliased = Arel::Table.new(table_name, :as => @aliased_table_name,
-                                                    :engine => arel_engine,
-                                                    :columns => klass.columns)
-
-              if reflection.macro == :has_and_belongs_to_many
-                [Arel::Table.new(options[:join_table], :as => aliased_join_table_name, :engine => arel_engine), aliased]
-              elsif reflection.options[:through]
-                [Arel::Table.new(through_reflection.klass.table_name, :as => aliased_join_table_name, :engine => arel_engine), aliased]
-              else
-                aliased
-              end
-            end
-
-            def join_relation(joining_relation)
-              self.join_type = Arel::OuterJoin
-              joining_relation.joins(self)
-            end
-
-            protected
-
-              def aliased_table_name_for(name, suffix = nil)
-                if @join_dependency.table_aliases[name].zero?
-                  @join_dependency.table_aliases[name] = @join_dependency.count_aliases_from_table_joins(name)
-                end
-
-                if !@join_dependency.table_aliases[name].zero? # We need an alias
-                  name = active_record.connection.table_alias_for "#{pluralize(reflection.name)}_#{parent_table_name}#{suffix}"
-                  @join_dependency.table_aliases[name] += 1
-                  if @join_dependency.table_aliases[name] == 1 # First time we've seen this name
-                    # Also need to count the aliases from the table_aliases to avoid incorrect count
-                    @join_dependency.table_aliases[name] += @join_dependency.count_aliases_from_table_joins(name)
-                  end
-                  table_index = @join_dependency.table_aliases[name]
-                  name = name[0..active_record.connection.table_alias_length-3] + "_#{table_index}" if table_index > 1
-                else
-                  @join_dependency.table_aliases[name] += 1
-                end
-
-                name
-              end
-
-              def pluralize(table_name)
-                ActiveRecord::Base.pluralize_table_names ? table_name.to_s.pluralize : table_name
-              end
-
-              def table_alias_for(table_name, table_alias)
-                 "#{table_name} #{table_alias if table_name != table_alias}".strip
-              end
-
-              def table_name_and_alias
-                table_alias_for table_name, @aliased_table_name
-              end
-
-              def process_conditions(conditions, table_name)
-                sanitized = sanitize_sql(conditions, table_name)
-
-                if sanitized =~ /\#\{.*\}/
-                  ActiveSupport::Deprecation.warn(
-                    'String-based interpolation of association conditions is deprecated. Please use a ' \
-                    'proc instead. So, for example, has_many :older_friends, :conditions => \'age > #{age}\' ' \
-                    'should be changed to has_many :older_friends, :conditions => proc { "age > #{age}" }.'
-                  )
-                  instance_eval("%@#{sanitized.gsub('@', '\@')}@", __FILE__, __LINE__)
-                elsif conditions.respond_to?(:to_proc)
-                  conditions = sanitize_sql(instance_eval(&conditions), table_name)
-                else
-                  sanitized
-                end
-              end
-          end
-        end
     end
   end
 end