activerecord 1.9.1 → 1.10.0

data/CHANGELOG

@@ -1,3 +1,81 @@
+*1.10.0* (19th April, 2005)
+
+* Added eager loading of associations as a way to solve the N+1 problem more gracefully without piggy-back queries. Example:
+
+    for post in Post.find(:all, :limit => 100)
+      puts "Post:            " + post.title
+      puts "Written by:      " + post.author.name
+      puts "Last comment on: " + post.comments.first.created_on
+    end
+  
+  This used to generate 301 database queries if all 100 posts had both author and comments. It can now be written as:
+  
+    for post in Post.find(:all, :limit => 100, :include => [ :author, :comments ])
+ 
+  ...and the number of database queries needed is now 1.
+
+* Added new unified Base.find API and deprecated the use of find_first and find_all. See the documentation for Base.find. Examples:
+
+    Person.find(1, :conditions => "administrator = 1", :order => "created_on DESC")
+    Person.find(1, 5, 6, :conditions => "administrator = 1", :order => "created_on DESC")
+    Person.find(:first, :order => "created_on DESC", :offset => 5)
+    Person.find(:all, :conditions => [ "category IN (?)", categories], :limit => 50)
+    Person.find(:all, :offset => 10, :limit => 10)
+
+* Added acts_as_nested_set #1000 [wschenk]. Introduction:
+
+    This acts provides Nested Set functionality.  Nested Set is similiar to Tree, but with
+    the added feature that you can select the children and all of it's descendants with
+    a single query.  A good use case for this is a threaded post system, where you want
+    to display every reply to a comment without multiple selects.
+
+* Added Base.save! that attempts to save the record just like Base.save but will raise a RecordInvalid exception instead of returning false if the record is not valid [After much pestering from Dave Thomas]
+
+* Fixed PostgreSQL usage of fixtures with regards to public schemas and table names with dots #962 [gnuman1@gmail.com]
+
+* Fixed that fixtures were being deleted in the same order as inserts causing FK errors #890 [andrew.john.peters@gmail.com]
+
+* Fixed loading of fixtures in to be in the right order (or PostgreSQL would bark) #1047 [stephenh@chase3000.com]
+
+* Fixed page caching for non-vhost applications living underneath the root #1004 [Ben Schumacher]
+
+* Fixes a problem with the SQL Adapter which was resulting in IDENTITY_INSERT not being set to ON when it should be #1104 [adelle]
+
+* Added the option to specify the acceptance string in validates_acceptance_of #1106 [caleb@aei-tech.com]
+
+* Added insert_at(position) to acts_as_list #1083 [DeLynnB]
+
+* Removed the default order by id on has_and_belongs_to_many queries as it could kill performance on large sets (you can still specify by hand with :order)
+
+* Fixed that Base.silence should restore the old logger level when done, not just set it to DEBUG #1084 [yon@milliped.com]
+
+* Fixed boolean saving on Oracle #1093 [mparrish@pearware.org]
+
+* Moved build_association and create_association for has_one and belongs_to out of deprecation as they work when the association is nil unlike association.build and association.create, which require the association to be already in place #864
+
+* Added rollbacks of transactions if they're active as the dispatcher is killed gracefully (TERM signal) #1054 [Leon Bredt]
+
+* Added quoting of column names for fixtures #997 [jcfischer@gmail.com]
+
+* Fixed counter_sql when no records exist in database for PostgreSQL (would give error, not 0) #1039 [Caleb Tennis]
+
+* Fixed that benchmarking times for rendering included db runtimes #987 [skaes@web.de]
+
+* Fixed boolean queries for t/f fields in PostgreSQL #995 [dave@cherryville.org]
+
+* Added that model.items.delete(child) will delete the child, not just set the foreign key to nil, if the child is dependent on the model #978 [bitsweat]
+
+* Fixed auto-stamping of dates (created_on/updated_on) for PostgreSQL #985 [dave@cherryville.org]
+
+* Fixed Base.silence/benchmark to only log if a logger has been configured #986 [skaes@web.de]
+
+* Added a join parameter as the third argument to Base.find_first and as the second to Base.count #426, #988 [skaes@web.de]
+
+* Fixed bug in Base#hash method that would treat records with the same string-based id as different [Dave Thomas]
+
+* Renamed DateHelper#distance_of_time_in_words_to_now to DateHelper#time_ago_in_words (old method name is still available as a deprecated alias)
+
+
 *1.9.1* (27th March, 2005)
 
 * Fixed that Active Record objects with float attribute could not be cloned #808

data/README

@@ -333,7 +333,7 @@ The prefered method of installing Active Record is through its GEM file. You'll
 RubyGems[http://rubygems.rubyforge.org/wiki/wiki.pl] installed for that, though. If you have,
 then use:
 
-  % [sudo] gem install activerecord-1.7.0.gem
+  % [sudo] gem install activerecord-1.10.0.gem
 
 You can also install Active Record the old-fashion way with the following command:
 

data/install.rb

@@ -18,48 +18,13 @@ unless $sitedir
   end
 end
 
-makedirs = %w{ active_record/associations active_record/connection_adapters active_record/support active_record/vendor active_record/acts }
-makedirs.each {|f| File::makedirs(File.join($sitedir, *f.split(/\//)))}
-
-# deprecated files that should be removed
-# deprecated = %w{ }
-
-# files to install in library path
-files = %w-
- active_record.rb
- active_record/aggregations.rb
- active_record/associations.rb
- active_record/associations/association_collection.rb
- active_record/associations/has_and_belongs_to_many_association.rb
- active_record/associations/has_many_association.rb
- active_record/base.rb
- active_record/callbacks.rb
- active_record/connection_adapters/abstract_adapter.rb
- active_record/connection_adapters/db2_adapter.rb
- active_record/connection_adapters/mysql_adapter.rb
- active_record/connection_adapters/oracle_adapter.rb
- active_record/connection_adapters/postgresql_adapter.rb
- active_record/connection_adapters/sqlite_adapter.rb
- active_record/connection_adapters/sqlserver_adapter.rb
- active_record/deprecated_associations.rb
- active_record/fixtures.rb
- active_record/locking.rb
- active_record/observer.rb
- active_record/reflection.rb
- active_record/acts/list.rb
- active_record/acts/tree.rb
- active_record/timestamp.rb
- active_record/transactions.rb
- active_record/validations.rb
- active_record/vendor/db2.rb
- active_record/vendor/mysql.rb
- active_record/vendor/mysql411.rb
- active_record/vendor/simple.rb
--
-
 # the acual gruntwork
 Dir.chdir("lib")
-# File::safe_unlink *deprecated.collect{|f| File.join($sitedir, f.split(/\//))}
-files.each {|f| 
-  File::install(f, File.join($sitedir, *f.split(/\//)), 0644, true)
+
+Find.find("active_record", "active_record.rb") { |f|
+  if f[-3..-1] == ".rb"
+    File::install(f, File.join($sitedir, *f.split(/\//)), 0644, true)
+  else
+    File::makedirs(File.join($sitedir, *f.split(/\//)))
+  end
 }

data/lib/active_record.rb

@@ -43,6 +43,7 @@ require 'active_record/reflection'
 require 'active_record/timestamp'
 require 'active_record/acts/list'
 require 'active_record/acts/tree'
+require 'active_record/acts/nested_set'
 require 'active_record/locking'
 require 'active_record/migration'
 
@@ -57,6 +58,7 @@ ActiveRecord::Base.class_eval do
   include ActiveRecord::Reflection
   include ActiveRecord::Acts::Tree
   include ActiveRecord::Acts::List
+  include ActiveRecord::Acts::NestedSet
 end
 
 require 'active_record/connection_adapters/mysql_adapter'

data/lib/active_record/acts/list.rb

@@ -71,6 +71,10 @@ module ActiveRecord
       # lower in the list of all chapters. Likewise, <tt>chapter.first?</tt> would return true if that chapter is
       # the first in the list of all chapters.
       module InstanceMethods
+        def insert_at(position = 1)
+          position == 1 ? add_to_list_top : insert_at_position(position)
+        end
+
         def move_lower
           return unless lower_item
 
@@ -107,7 +111,6 @@ module ActiveRecord
           decrement_positions_on_lower_items
         end
 
-
         def increment_position
           update_attribute position_column, self.send(position_column).to_i + 1
         end
@@ -168,24 +171,45 @@ module ActiveRecord
             update_attribute(position_column, 1)
           end
 
+          # This has the effect of moving all the higher items up one.
+          def decrement_positions_on_higher_items(position)
+            self.class.update_all(
+              "#{position_column} = (#{position_column} - 1)", "#{scope_condition} AND #{position_column} <= #{position}"
+            )
+	       end
+
           # This has the effect of moving all the lower items up one.
           def decrement_positions_on_lower_items
             self.class.update_all(
-              "#{position_column} = (#{position_column} - 1)",  "#{scope_condition} AND #{position_column} > #{send(position_column).to_i}"
+              "#{position_column} = (#{position_column} - 1)", "#{scope_condition} AND #{position_column} > #{send(position_column).to_i}"
             )
           end
-  
+
+          # This has the effect of moving all the higher items down one.
           def increment_positions_on_higher_items
             self.class.update_all(
-              "#{position_column} = (#{position_column} + 1)",  "#{scope_condition} AND #{position_column} < #{send(position_column).to_i}"
+              "#{position_column} = (#{position_column} + 1)", "#{scope_condition} AND #{position_column} < #{send(position_column).to_i}"
             )
           end
 
+          # This has the effect of moving all the lower items down one.
+          def increment_positions_on_lower_items(position)
+	         self.class.update_all(
+	           "#{position_column} = (#{position_column} + 1)", "#{scope_condition} AND #{position_column} >= #{position}"
+	         )
+	       end
+
           def increment_positions_on_all_items
             self.class.update_all(
               "#{position_column} = (#{position_column} + 1)",  "#{scope_condition}"
             )
           end
+
+          def insert_at_position(position)
+            remove_from_list
+	         increment_positions_on_lower_items(position)
+            self.update_attribute(position_column, position)
+          end
       end     
     end
   end

data/lib/active_record/acts/nested_set.rb

@@ -0,0 +1,212 @@
+module ActiveRecord
+  module Acts #:nodoc:
+    module NestedSet #:nodoc:
+      def self.append_features(base)
+        super        
+        base.extend(ClassMethods)              
+      end  
+
+      # This acts provides Nested Set functionality.  Nested Set is similiar to Tree, but with
+      # the added feature that you can select the children and all of it's descendants with
+      # a single query.  A good use case for this is a threaded post system, where you want
+      # to display every reply to a comment without multiple selects.
+      #
+      # A google search for "Nested Set" should point you in the direction to explain the
+      # data base theory.  I figured a bunch of this from
+      # http://threebit.net/tutorials/nestedset/tutorial1.html
+      #
+      # Instead of picturing a leaf node structure with child pointing back to their parent,
+      # the best way to imagine how this works is to think of the parent entity surrounding all
+      # of it's children, and it's parent surrounding it, etc.  Assuming that they are lined up
+      # horizontally, we store the left and right boundries in the database.
+      #
+      # Imagine:
+      #   root
+      #     |_ Child 1
+      #       |_ Child 1.1
+      #       |_ Child 1.2
+      #     |_ Child 2
+      #       |_ Child 2.1
+      #       |_ Child 2.2
+      #
+      # If my cirlces in circles description didn't make sense, check out this sweet
+      # ASCII art:
+      #
+      #     ___________________________________________________________________
+      #    |  Root                                                             |
+      #    |    ____________________________    ____________________________   |
+      #    |   |  Child 1                  |   |  Child 2                  |   |
+      #    |   |   __________   _________  |   |   __________   _________  |   |
+      #    |   |  |  C 1.1  |  |  C 1.2 |  |   |  |  C 2.1  |  |  C 2.2 |  |   |
+      #    1   2  3_________4  5________6  7   8  9_________10 11_______12 13  14
+      #    |   |___________________________|   |___________________________|   |
+      #    |___________________________________________________________________| 
+      #
+      # The numbers represent the left and right boundries.  The table them might
+      # look like this:
+      #    ID | PARENT | LEFT | RIGHT | DATA
+      #     1 |      0 |    1 |    14 | root
+      #     2 |      1 |    2 |     7 | Child 1
+      #     3 |      2 |    3 |     4 | Child 1.1
+      #     4 |      2 |    5 |     6 | Child 1.2
+      #     5 |      1 |    8 |    13 | Child 2
+      #     6 |      5 |    9 |    10 | Child 2.1
+      #     7 |      5 |   11 |    12 | Child 2.2
+      #
+      # So, to get all children of an entry, you
+      #     SELECT * WHERE CHILD.LEFT IS BETWEEN PARENT.LEFT AND PARENT.RIGHT
+      #
+      # To get the count, it's (LEFT - RIGHT + 1)/2, etc.
+      #
+      # To get the direct parent, it falls back to using the PARENT_ID field.   
+      #
+      # There are instance methods for all of these.
+      #
+      # The structure is good if you need to group things together; the downside is that
+      # keeping data integrity is a pain, and both adding and removing and entry
+      # require a full table write.        
+      #
+      # This sets up a before_destroy trigger to prune the tree correctly if one of it's
+      # elements gets deleted.
+      #
+      module ClassMethods                      
+        # Configuration options are:
+        #
+        # * +parent_column+ - specifies the column name to use for keeping the position integer (default: parent_id)
+        # * +left_column+ - column name for left boundry data, default "lft"
+        # * +right_column+ - column name for right boundry data, default "rgt"
+        # * +scope+ - restricts what is to be considered a list. Given a symbol, it'll attach "_id" 
+        #   (if that hasn't been already) and use that as the foreign key restriction. It's also possible 
+        #   to give it an entire string that is interpolated if you need a tighter scope than just a foreign key.
+        #   Example: <tt>acts_as_list :scope => 'todo_list_id = #{todo_list_id} AND completed = 0'</tt>
+        def acts_as_nested_set(options = {})
+          configuration = { :parent_column => "parent_id", :left_column => "lft", :right_column => "rgt", :scope => "1 = 1" }
+          
+          configuration.update(options) if options.is_a?(Hash)
+          
+          configuration[:scope] = "#{configuration[:scope]}_id".intern if configuration[:scope].is_a?(Symbol) && configuration[:scope].to_s !~ /_id$/
+          
+          if configuration[:scope].is_a?(Symbol)
+            scope_condition_method = %(
+              def scope_condition
+                if #{configuration[:scope].to_s}.nil?
+                  "#{configuration[:scope].to_s} IS NULL"
+                else
+                  "#{configuration[:scope].to_s} = \#{#{configuration[:scope].to_s}}"
+                end
+              end
+            )
+          else
+            scope_condition_method = "def scope_condition() \"#{configuration[:scope]}\" end"
+          end
+        
+          class_eval <<-EOV
+            include ActiveRecord::Acts::NestedSet::InstanceMethods
+
+            #{scope_condition_method}
+            
+            def left_col_name() "#{configuration[:left_column]}" end
+
+            def right_col_name() "#{configuration[:right_column]}" end
+              
+            def parent_column() "#{configuration[:parent_column]}" end
+
+          EOV
+        end
+      end
+      
+      module InstanceMethods
+        # Returns true is this is a root node.  
+        def root?
+          parent_id = self[parent_column]
+          (parent_id == 0 || parent_id.nil?) && (self[left_col_name] == 1) && (self[right_col_name] > self[left_col_name])
+        end                                                                                             
+                                    
+        # Returns true is this is a child node
+        def child?                          
+          parent_id = self[parent_column]
+          !(parent_id == 0 || parent_id.nil?) && (self[left_col_name] > 1) && (self[right_col_name] > self[left_col_name])
+        end     
+        
+        # Returns true if we have no idea what this is
+        def unknown?
+          !root? && !child?
+        end
+
+                     
+        # Added a child to this object in the tree.  If this object hasn't been initialized,
+        # it gets set up as a root node.  Otherwise, this method will update all of the
+        # other elements in the tree and shift them to the right. Keeping everything
+        # balanaced. 
+        def add_child( child )     
+          self.reload
+          child.reload
+
+          if child.root?
+            raise "Adding sub-tree isn\'t currently supported"
+          else
+            if ( (self[left_col_name] == nil) || (self[right_col_name] == nil) )
+              # Looks like we're now the root node!  Woo
+              self[left_col_name] = 1
+              self[right_col_name] = 4
+              
+              # What do to do about validation?
+              return nil unless self.save
+              
+              child[parent_column] = self.id
+              child[left_col_name] = 2
+              child[right_col_name]= 3
+              return child.save
+            else
+              # OK, we need to add and shift everything else to the right
+              child[parent_column] = self.id
+              right_bound = self[right_col_name]
+              child[left_col_name] = right_bound
+              child[right_col_name] = right_bound + 1
+              self[right_col_name] += 2
+              self.class.transaction {
+                self.class.update_all( "#{left_col_name} = (#{left_col_name} + 2)",  "#{scope_condition} AND #{left_col_name} >= #{right_bound}" )
+                self.class.update_all( "#{right_col_name} = (#{right_col_name} + 2)",  "#{scope_condition} AND #{right_col_name} >= #{right_bound}" )
+                self.save
+                child.save
+              }
+            end
+          end                                   
+        end
+                                   
+        # Returns the number of nested children of this object.
+        def children_count
+          return (self[right_col_name] - self[left_col_name] - 1)/2
+        end
+                                                               
+        # Returns a set of itself and all of it's nested children
+        def full_set
+          self.class.find_all( "#{scope_condition} AND (#{left_col_name} BETWEEN #{self[left_col_name]} and #{self[right_col_name]})" )
+        end
+                  
+        # Returns a set of all of it's children and nested children
+        def all_children
+          self.class.find_all( "#{scope_condition} AND (#{left_col_name} > #{self[left_col_name]}) and (#{right_col_name} < #{self[right_col_name]})" )
+        end
+                                  
+        # Returns a set of only this entries immediate children
+        def direct_children
+          self.class.find_all( "#{scope_condition} and #{parent_column} = #{self.id}")
+        end
+                                      
+        # Prunes a branch off of the tree, shifting all of the elements on the right
+        # back to the left so the counts still work.
+        def before_destroy
+          return if self[right_col_name].nil? || self[left_col_name].nil?
+          dif = self[right_col_name] - self[left_col_name] + 1
+
+          self.class.transaction {
+            self.class.delete_all( "#{scope_condition} and #{left_col_name} > #{self[left_col_name]} and #{right_col_name} < #{self[right_col_name]}" )
+            self.class.update_all( "#{left_col_name} = (#{left_col_name} - #{dif})",  "#{scope_condition} AND #{left_col_name} >= #{self[right_col_name]}" )
+            self.class.update_all( "#{right_col_name} = (#{right_col_name} - #{dif} )",  "#{scope_condition} AND #{right_col_name} >= #{self[right_col_name]}" )
+          }
+        end
+      end
+    end
+  end
+end

data/lib/active_record/associations.rb

@@ -19,7 +19,7 @@ module ActiveRecord
         instance_variable_set "@#{assoc.name}", nil
       end
     end
-
+    
     # Associations are a set of macro-like class methods for tying objects together through foreign keys. They express relationships like 
     # "Project has one Project Manager" or "Project belongs to a Portfolio". Each macro adds a number of methods to the class which are 
     # specialized according to the collection or association symbol and the options hash. It works much the same was as Ruby's own attr* 
@@ -108,6 +108,41 @@ module ActiveRecord
     #   project.milestones(true).size  # fetches milestones from the database
     #   project.milestones             # uses the milestone cache
     #
+    # == Eager loading of associations
+    #
+    # Eager loading is a way to find objects of a certain class and a number of named associations along with it in a single SQL call. This is
+    # one of the easiest ways of to prevent the dreaded 1+N problem in which fetching 100 posts that each needs to display their author
+    # triggers 101 database queries. Through the use of eager loading, the 101 queries can be reduced to 1. Example:
+    #
+    #   class Post < ActiveRecord::Base
+    #     belongs_to :author
+    #     has_many   :comments
+    #   end
+    #
+    # Consider the following loop using the class above:
+    #
+    #   for post in Post.find(:all, :limit => 100)
+    #     puts "Post:            " + post.title
+    #     puts "Written by:      " + post.author.name
+    #     puts "Last comment on: " + post.comments.first.created_on
+    #   end 
+    #
+    # To iterate over these one hundred posts, we'll generate 201 database queries. Let's first just optimize it for retrieving the author:
+    #
+    #   for post in Post.find(:all, :limit => 100, :include => :author)
+    #
+    # This references the name of the belongs_to association that also used the :author symbol, so the find will now weave in a join something
+    # like this: LEFT OUTER JOIN authors ON authors.id = posts.author_id. Doing so will cut down the number of queries from 201 to 101.
+    #
+    # We can improve upon the situation further by referencing both associations in the finder with:
+    #
+    #   for post in Post.find(:all, :limit => 100, :include => [ :author, :comments ])
+    #
+    # That'll add another join along the lines of: LEFT OUTER JOIN comments ON comments.post_id = posts.id. And we'll be down to 1 query.
+    # But that shouldn't fool you to think that you can pull out huge amounts of data with no performance penalty just because you've reduced
+    # the number of queries. The database still needs to send all the data to Active Record and it still needs to be processed. So its no
+    # catch-all for performance problems, but its a great way to cut down on the number of queries in a situation as the one described above.
+    #
     # == Modules
     #
     # By default, associations will look for objects within the current module scope. Consider:
@@ -153,28 +188,27 @@ module ActiveRecord
       # * <tt>collection(force_reload = false)</tt> - returns an array of all the associated objects.
       #   An empty array is returned if none are found.
       # * <tt>collection<<(object, ...)</tt> - adds one or more objects to the collection by setting their foreign keys to the collection's primary key.
-      # * <tt>collection.delete(object, ...)</tt> - removes one or more objects from the collection by setting their foreign keys to NULL.  This does not destroy the objects.
+      # * <tt>collection.delete(object, ...)</tt> - removes one or more objects from the collection by setting their foreign keys to NULL.  
+      #   This will also destroy the objects if they're declared as belongs_to and dependent on this model.
       # * <tt>collection.clear</tt> - removes every object from the collection. This does not destroy the objects.
       # * <tt>collection.empty?</tt> - returns true if there are no associated objects.
       # * <tt>collection.size</tt> - returns the number of associated objects.
-      # * <tt>collection.find(id)</tt> - finds an associated object responding to the +id+ and that
-      #   meets the condition that it has to be associated with this object.
-      # * <tt>collection.find_all(conditions = nil, orderings = nil, limit = nil, joins = nil)</tt> - finds all associated objects responding 
-      #   criteria mentioned (like in the standard find_all) and that meets the condition that it has to be associated with this object.
+      # * <tt>collection.find</tt> - finds an associated object according to the same rules as Base.find.
       # * <tt>collection.build(attributes = {})</tt> - returns a new object of the collection type that has been instantiated
-      #   with +attributes+ and linked to this object through a foreign key but has not yet been saved.
+      #   with +attributes+ and linked to this object through a foreign key but has not yet been saved. *Note:* This only works if an 
+      #   associated object already exists, not if its nil!
       # * <tt>collection.create(attributes = {})</tt> - returns a new object of the collection type that has been instantiated
       #   with +attributes+ and linked to this object through a foreign key and that has already been saved (if it passed the validation).
+      #   *Note:* This only works if an associated object already exists, not if its nil!
       #
       # Example: A Firm class declares <tt>has_many :clients</tt>, which will add:
-      # * <tt>Firm#clients</tt> (similar to <tt>Clients.find_all "firm_id = #{id}"</tt>)
+      # * <tt>Firm#clients</tt> (similar to <tt>Clients.find :all, :conditions => "firm_id = #{id}"</tt>)
       # * <tt>Firm#clients<<</tt>
       # * <tt>Firm#clients.delete</tt>
       # * <tt>Firm#clients.clear</tt>
       # * <tt>Firm#clients.empty?</tt> (similar to <tt>firm.clients.size == 0</tt>)
       # * <tt>Firm#clients.size</tt> (similar to <tt>Client.count "firm_id = #{id}"</tt>)
-      # * <tt>Firm#clients.find</tt> (similar to <tt>Client.find_on_conditions(id, "firm_id = #{id}")</tt>)
-      # * <tt>Firm#clients.find_all</tt> (similar to <tt>Client.find_all "firm_id = #{id}"</tt>)
+      # * <tt>Firm#clients.find</tt> (similar to <tt>Client.find(id, :conditions => "firm_id = #{id}")</tt>)
       # * <tt>Firm#clients.build</tt> (similar to <tt>Client.new("firm_id" => id)</tt>)
       # * <tt>Firm#clients.create</tt> (similar to <tt>c = Client.new("client_id" => id); c.save; c</tt>)
       # The declaration can also include an options hash to specialize the behavior of the association.
@@ -219,6 +253,8 @@ module ActiveRecord
 
         if options[:dependent] and options[:exclusively_dependent]
           raise ArgumentError, ':dependent and :exclusively_dependent are mutually exclusive options.  You may specify one or the other.' # ' ruby-mode
+        # See HasManyAssociation#delete_records.  Dependent associations
+        # delete children, otherwise foreign key is set to NULL.
         elsif options[:dependent]
           module_eval "before_destroy '#{association_name}.each { |o| o.destroy }'"
         elsif options[:exclusively_dependent]
@@ -247,19 +283,19 @@ module ActiveRecord
       # * <tt>association=(associate)</tt> - assigns the associate object, extracts the primary key, sets it as the foreign key, 
       #   and saves the associate object.
       # * <tt>association.nil?</tt> - returns true if there is no associated object.
-      # * <tt>association.build(attributes = {})</tt> - returns a new object of the associated type that has been instantiated
+      # * <tt>build_association(attributes = {})</tt> - 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. Note: This ONLY works if
       #   an association already exists. It will NOT work if the association is nil.
-      # * <tt>association.create(attributes = {})</tt> - returns a new object of the associated type that has been instantiated
+      # * <tt>create_association(attributes = {})</tt> - returns a new object of the associated type that has been instantiated
       #   with +attributes+ and linked to this object through a foreign key and that has already been saved (if it passed the validation).
-      #   Note: This ONLY works if an association already exists. It will NOT work if the association is nil.
       #
       # Example: An Account class declares <tt>has_one :beneficiary</tt>, which will add:
       # * <tt>Account#beneficiary</tt> (similar to <tt>Beneficiary.find_first "account_id = #{id}"</tt>)
       # * <tt>Account#beneficiary=(beneficiary)</tt> (similar to <tt>beneficiary.account_id = account.id; beneficiary.save</tt>)
       # * <tt>Account#beneficiary.nil?</tt>
-      # * <tt>Account#beneficiary.build</tt> (similar to <tt>Beneficiary.new("account_id" => id)</tt>)
-      # * <tt>Account#beneficiary.create</tt> (similar to <tt>b = Beneficiary.new("account_id" => id); b.save; b</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>)
+      #
       # The declaration can also include an options hash to specialize the behavior of the association.
       # 
       # Options are:
@@ -300,13 +336,13 @@ module ActiveRecord
         end
       
         association_accessor_methods(association_name, association_class_name, association_class_primary_key_name, options, HasOneAssociation)
+        association_constructor_method(:build, association_name, association_class_name, association_class_primary_key_name, options, HasOneAssociation)
+        association_constructor_method(:create, association_name, association_class_name, association_class_primary_key_name, options, HasOneAssociation)
         
         module_eval "before_destroy '#{association_name}.destroy unless #{association_name}.nil?'" if options[:dependent]
 
         # deprecated api
         deprecated_has_association_method(association_name)
-        deprecated_build_method("build_", association_name, association_class_name, association_class_primary_key_name)
-        deprecated_create_method("create_", association_name, association_class_name, association_class_primary_key_name)
         deprecated_association_comparison_method(association_name, association_class_name)
       end
 
@@ -316,9 +352,9 @@ module ActiveRecord
       # * <tt>association(force_reload = false)</tt> - returns the associated object. Nil is returned if none is found.
       # * <tt>association=(associate)</tt> - assigns the associate object, extracts the primary key, and sets it as the foreign key.
       # * <tt>association.nil?</tt> - returns true if there is no associated object.
-      # * <tt>association.build(attributes = {})</tt> - returns a new object of the associated type that has been instantiated
+      # * <tt>build_association(attributes = {})</tt> - 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.
-      # * <tt>association.create(attributes = {})</tt> - returns a new object of the associated type that has been instantiated
+      # * <tt>create_association(attributes = {})</tt> - returns a new object of the associated type that has been instantiated
       #   with +attributes+ and linked to this object through a foreign key and that has already been saved (if it passed the validation).
       #
       # Example: A Post class declares <tt>belongs_to :author</tt>, which will add:
@@ -326,8 +362,8 @@ module ActiveRecord
       # * <tt>Post#author=(author)</tt> (similar to <tt>post.author_id = author.id</tt>)
       # * <tt>Post#author?</tt> (similar to <tt>post.author == some_author</tt>)
       # * <tt>Post#author.nil?</tt>
-      # * <tt>Post#author.build</tt> (similar to <tt>Author.new("post_id" => id)</tt>)
-      # * <tt>Post#author.create</tt> (similar to <tt>b = Author.new("post_id" => id); b.save; b</tt>)
+      # * <tt>Post#build_author</tt> (similar to <tt>Author.new("post_id" => id)</tt>)
+      # * <tt>Post#create_author</tt> (similar to <tt>b = Author.new("post_id" => id); b.save; b</tt>)
       # The declaration can also include an options hash to specialize the behavior of the association.
       # 
       # Options are:
@@ -362,6 +398,8 @@ module ActiveRecord
         association_class_primary_key_name = options[:foreign_key] || Inflector.underscore(Inflector.demodulize(association_class_name)) + "_id"
 
         association_accessor_methods(association_name, association_class_name, association_class_primary_key_name, options, BelongsToAssociation)
+        association_constructor_method(:build, association_name, association_class_name, association_class_primary_key_name, options, BelongsToAssociation)
+        association_constructor_method(:create, association_name, association_class_name, association_class_primary_key_name, options, BelongsToAssociation)
 
         module_eval do
           before_save <<-EOF
@@ -548,6 +586,15 @@ module ActiveRecord
             end
             association
           end
+
+          define_method("set_#{association_name}_target") do |target|
+            return if target.nil?
+            association = association_proxy_class.new(self,
+              association_name, association_class_name,
+              association_class_primary_key_name, options)
+            association.target = target
+            instance_variable_set("@#{association_name}", association)
+          end
         end
 
         def collection_accessor_methods(association_name, association_class_name, association_class_primary_key_name, options, association_proxy_class)
@@ -614,6 +661,141 @@ module ActiveRecord
             end_eval
           end
         end
+
+        def association_constructor_method(constructor, association_name, association_class_name, association_class_primary_key_name, options, association_proxy_class)
+          define_method("#{constructor}_#{association_name}") do |*params|
+            attributees = params.first unless params.empty?
+            association = instance_variable_get("@#{association_name}")
+
+            if association.nil?
+              association = association_proxy_class.new(self,
+                association_name, association_class_name,
+                association_class_primary_key_name, options)
+              instance_variable_set("@#{association_name}", association)
+            end
+
+            association.send(constructor, attributees)
+          end
+        end
+
+        def find_with_associations(options = {})
+          reflections          = reflect_on_included_associations(options[:include])
+          schema_abbreviations = generate_schema_abbreviations(reflections)
+          primary_key_table    = generate_primary_key_table(reflections, schema_abbreviations)
+
+          rows        = select_all_rows(options, schema_abbreviations, reflections)
+          records     = { }        
+          primary_key = primary_key_table[table_name]
+          
+          for row in rows
+            id = row[primary_key]
+            records[id] ||= instantiate(extract_record(schema_abbreviations, table_name, row))
+          
+            reflections.each do |reflection|
+              next unless row[primary_key_table[reflection.table_name]]
+              
+              case reflection.macro
+                when :has_many, :has_and_belongs_to_many
+                  records[id].send(reflection.name)
+                  records[id].instance_variable_get("@#{reflection.name}").target.push(
+                    reflection.klass.send(:instantiate, extract_record(schema_abbreviations, reflection.table_name, row))
+                  )
+                when :has_one, :belongs_to
+                  records[id].send(
+                    "#{reflection.name}=", 
+                    reflection.klass.send(:instantiate, extract_record(schema_abbreviations, reflection.table_name, row))
+                  )
+              end
+            end
+          end
+          
+          return records.values
+        end
+
+        def reflect_on_included_associations(associations)
+          [ associations ].flatten.collect { |association| reflect_on_association(association) }
+        end
+
+        def generate_schema_abbreviations(reflections)
+          schema = [ [ table_name, column_names ] ]
+          schema += reflections.collect { |r| [ r.table_name, r.klass.column_names ] }
+
+          schema_abbreviations = {}
+          schema.each_with_index do |table_and_columns, i|
+            table, columns = table_and_columns
+            columns.each_with_index { |column, j| schema_abbreviations["t#{i}_r#{j}"] = [ table, column ] }
+          end
+          
+          return schema_abbreviations
+        end
+
+        def generate_primary_key_table(reflections, schema_abbreviations)
+          primary_key_lookup_table = {}
+          primary_key_lookup_table[table_name] = 
+            schema_abbreviations.find { |cn, tc| tc == [ table_name, primary_key ] }.first
+
+          reflections.collect do |reflection| 
+            primary_key_lookup_table[reflection.klass.table_name] = schema_abbreviations.find { |cn, tc| 
+              tc == [ reflection.klass.table_name, reflection.klass.primary_key ]
+            }.first
+          end
+          
+          return primary_key_lookup_table
+        end
+
+
+        def select_all_rows(options, schema_abbreviations, reflections)
+          connection.select_all(
+            construct_finder_sql_with_included_associations(options, schema_abbreviations, reflections), 
+            "#{name} Load Including Associations"
+          )
+        end
+
+        def construct_finder_sql_with_included_associations(options, schema_abbreviations, reflections)
+          sql = "SELECT #{column_aliases(schema_abbreviations)} FROM #{table_name} "
+          sql << reflections.collect { |reflection| association_join(reflection) }.to_s
+          sql << "#{options[:joins]} " if options[:joins]
+          add_conditions!(sql, options[:conditions])
+          sql << "ORDER BY #{options[:order]} " if options[:order]
+          
+          return sanitize_sql(sql)
+        end
+
+        def column_aliases(schema_abbreviations)
+          schema_abbreviations.collect { |cn, tc| "#{tc.join(".")} AS #{cn}" }.join(", ")
+        end
+
+        def association_join(reflection)
+          case reflection.macro
+            when :has_and_belongs_to_many
+              " LEFT OUTER JOIN #{reflection.options[:join_table]} ON " +
+              "#{reflection.options[:join_table]}.#{reflection.options[:foreign_key] || table_name.classify.foreign_key} = " +
+              "#{table_name}.#{primary_key} " +
+              " LEFT OUTER JOIN #{reflection.klass.table_name} ON " +
+              "#{reflection.options[:join_table]}.#{reflection.options[:associated_foreign_key] || reflection.klass.table_name.classify.foreign_key} = " +
+              "#{reflection.klass.table_name}.#{reflection.klass.primary_key} "
+            when :has_many, :has_one
+              " LEFT OUTER JOIN #{reflection.klass.table_name} ON " +
+              "#{reflection.klass.table_name}.#{reflection.options[:foreign_key] || table_name.classify.foreign_key} = " +
+              "#{table_name}.#{primary_key} "
+            when :belongs_to
+              " LEFT OUTER JOIN #{reflection.klass.table_name} ON " +
+              "#{reflection.klass.table_name}.#{reflection.klass.primary_key} = " +
+              "#{table_name}.#{reflection.options[:foreign_key] || reflection.klass.table_name.classify.foreign_key} "
+            else
+              ""
+          end          
+        end
+
+
+        def extract_record(schema_abbreviations, table_name, row)
+          record = {}
+          row.each do |column, value|
+            prefix, column_name = schema_abbreviations[column]
+            record[column_name] = value if prefix == table_name
+          end
+          return record
+        end        
     end
   end
 end