Abstract some common code from AssociationScope and JoinDependency::JoinAssociation into a JoinHelper module

Move the code which builds a scope for through associations into a generic AssociationScope class which is capable of building a scope for any association.

Move JoinDependency and friends from ActiveRecord::Associations::ClassMethods to just ActiveRecord::Associations

Use proper objects to do the work to build the associations (adding methods, callbacks etc) rather than calling a whole bunch of methods with rather long names.

Split AssociationProxy into an Association class (and subclasses) which manages the association, and a CollectionProxy class which is *only* a proxy. Singular associations no longer have a proxy. See CHANGELOG for more.

Allow building and then later saving has_many :through records, such that the join record is automatically saved too. This requires the :inverse_of option to be set on the source association in the join model. See the CHANGELOG for details. [#4329 state:resolved]

Ensure that association_ids uses the correct attribute where the association is a has_many :through with a :primary_key option on the source reflection. [#6376 state:resolved]

Support the :dependent option on has_many :through associations. For historical and practical reasons, :delete_all is the default deletion strategy employed by association.delete(*records), despite the fact that the default strategy is :nullify for regular has_many. Also, this only works at all if the source reflection is a belongs_to. For other situations, you should directly modify the through association.

Signed-off-by: NSantiago Pastorino <santiago@wyeworks.com>

Removed support for accessing attributes on a has_and_belongs_to_many join table. This has been documented as deprecated behaviour since April 2006. Please use has_many :through instead. A deprecation warning will be added to the 3-0-stable branch for the 3.0.4 release.

Refactor the code for singular association constructors. This will allow me to define a create_association! method in a minute.

Get rid of set_association_target and association_loaded? as the parts of the code that need that can now just use association_proxy(:name).loaded?/target=

Return value is irrelevant here as the RHS of the assignment is always returned by methods ending in '='

Remove incorrect documentation about build_assoc on has_one. This is proven, for example, by test_successful_build_association in has_one_associations_test.rb

For a singular association, it should be build_association, rather than association.build (as association may be nil)

Correctly indent the bullet points under 'One-to-one associations', so that the lines are not broken in the generated rdoc html

Remove undocumented feature from has_one where you could pass false as the second parameter to build_assoc or create_assoc, and the existing associated object would be untouched (the foreign key would not be nullified, and it would not be deleted). If you want behaviour similar to this you can do the following things:

* Use :dependent => :nullify (or don't specify :dependent) if you want to prevent the existing associated object from being deleted
* Use has_many if you actually want multiple associated objects
* Explicitly set the foreign key if, for some reason, you really need to have multiple objects associated with the same has_one. E.g.

    previous = obj.assoc
    obj.create_assoc
    previous.update_attributes(:obj_id => obj.id)

When preloading a belongs_to, the target should still be set (to nil) if there is no foreign key present. And the loaded flag should be set on the association proxy. This then allows us to remove the foreign_key_present? check from BelongsToAssociation#find_target. Also added a test for the same thing on polymorphic associations.

This required changing the code to keep the association proxy for a belongs_to around, despite its target being nil. Which in turn required various changes to the way that stale target checking is handled, in order to support various edge cases (loaded target is nil then foreign key added, foreign key is changed and then changed back, etc). A side effect is that the code is nicer and more succinct.

Note that I am removing test_no_unexpected_aliasing since that is basically checking that the proxy for a belongs_to *does* change, which is the exact opposite of the intention of this commit. Also adding various tests for various edge cases and related things.

Phew, long commit message!

Rename AssociationReflection#primary_key_name to foreign_key, since the options key which it relates to is :foreign_key

Get rid of extra_conditions param from configure_dependency_for_has_many. I can't see a particularly plausible argument for this being used by plugins, and if they really want they can just redefine the callback or whatever. Note also that before my recent commit the extra_conditions param was completely ignored for :dependent => :destroy.

Refactor configure_dependency_for_has_many to use AssociationCollection#delete_all. It was necessary to change test_before_destroy in lifecycle_test.rb so that it checks topic.replies.size *before* doing the destroy, as afterwards it will now (correctly) be 0.