activerecord 1.3.0 → 1.4.0

data/lib/active_record/associations/has_and_belongs_to_many_association.rb

@@ -38,15 +38,42 @@ module ActiveRecord
         self
       end
 
-      def find(association_id = nil, &block)
-        if block_given? || @options[:finder_sql]
-          load_collection
-          @collection.find(&block)
+      def find_first
+        load_collection.first
+      end
+
+      def find(*args)
+        # Return an Array if multiple ids are given.
+        expects_array = args.first.kind_of?(Array)
+
+        ids = args.flatten.compact.uniq
+
+        # If no block is given, raise RecordNotFound.
+        if ids.empty?
+          raise RecordNotFound, "Couldn't find #{@association_class.name} without an ID#{conditions}"
+
+        # If using a custom finder_sql, scan the entire collection.
+        elsif @options[:finder_sql]
+          if ids.size == 1
+            id = ids.first
+            record = load_collection.detect { |record| id == record.id }
+            expects_array? ? [record] : record
+          else
+            load_collection.select { |record| ids.include?(record.id) }
+          end
+
+        # Otherwise, construct a query.
         else
-          if loaded?
-            find_all { |record| record.id == association_id.to_i }.first
+          ids_list = ids.map { |id| @owner.send(:quote, id) }.join(',')
+          records = find_all_records(@finder_sql.sub(/ORDER BY/, "AND j.#{@association_foreign_key} IN (#{ids_list}) ORDER BY"))
+          if records.size == ids.size
+            if ids.size == 1 and !expects_array
+              records.first
+            else
+              records
+            end
           else
-            find_all_records(@finder_sql.sub(/ORDER BY/, "AND j.#{@association_foreign_key} = #{@owner.send(:quote, association_id)} ORDER BY")).first
+            raise RecordNotFound, "Couldn't find #{@association_class.name} with ID in (#{ids_list})"
           end
         end
       end
@@ -70,10 +97,9 @@ module ActiveRecord
           records = @association_class.find_by_sql(sql)
           @options[:uniq] ? uniq(records) : records
         end
-            
+
         def count_records
-          load_collection
-          @collection.size
+          load_collection.size
         end
 
         def insert_record(record)

data/lib/active_record/associations/has_many_association.rb

@@ -3,12 +3,13 @@ module ActiveRecord
     class HasManyAssociation < AssociationCollection #:nodoc:
       def initialize(owner, association_name, association_class_name, association_class_primary_key_name, options)
         super(owner, association_name, association_class_name, association_class_primary_key_name, options)
-        @conditions = @association_class.send(:sanitize_conditions, options[:conditions])
+        @conditions = sanitize_sql(options[:conditions])
 
         if options[:finder_sql]
           @finder_sql = interpolate_sql(options[:finder_sql])
         else
-          @finder_sql = "#{@association_class_primary_key_name} = #{@owner.quoted_id} #{@conditions ? " AND " + interpolate_sql(@conditions) : ""}"
+          @finder_sql = "#{@association_class_primary_key_name} = #{@owner.quoted_id}"
+          @finder_sql << " AND #{@conditions}" if @conditions
         end
 
         if options[:counter_sql]
@@ -35,29 +36,57 @@ module ActiveRecord
         record
       end
 
-      def find_all(runtime_conditions = nil, orderings = nil, limit = nil, joins = nil, &block)
-        if block_given? || @options[:finder_sql]
-          load_collection
-          @collection.find_all(&block)
+      def find_all(runtime_conditions = nil, orderings = nil, limit = nil, joins = nil)
+        if @options[:finder_sql]
+          records = @association_class.find_by_sql(@finder_sql)
         else
-          @association_class.find_all(
-            "#{@association_class_primary_key_name} = #{@owner.quoted_id}" +
-            "#{@conditions ? " AND " + @conditions : ""}#{runtime_conditions ? " AND " + @association_class.send(:sanitize_conditions, runtime_conditions) : ""}",
-            orderings, 
-            limit, 
-            joins
-          )
+          sql = @finder_sql
+          sql << " AND #{sanitize_sql(runtime_conditions)}" if runtime_conditions
+          orderings ||= @options[:order]
+          records = @association_class.find_all(sql, orderings, limit, joins)
         end
       end
 
-      def find(association_id = nil, &block)
-        if block_given? || @options[:finder_sql]
-          load_collection
-          @collection.find(&block)
+      # Count the number of associated records. All arguments are optional.
+      def count(runtime_conditions = nil)
+        if @options[:finder_sql]
+          @association_class.count_by_sql(@finder_sql)
         else
-          @association_class.find_on_conditions(association_id,
-            "#{@association_class_primary_key_name} = #{@owner.quoted_id}#{@conditions ? " AND " + @conditions : ""}"
-          )
+          sql = @finder_sql
+          sql << " AND #{sanitize_sql(runtime_conditions)}" if runtime_conditions
+          @association_class.count(sql)
+        end
+      end
+      
+      # Find the first associated record.  All arguments are optional.
+      def find_first(conditions = nil, orderings = nil)
+        find_all(conditions, orderings, 1).first
+      end
+
+      def find(*args)
+        # Return an Array if multiple ids are given.
+        expects_array = args.first.kind_of?(Array)
+
+        ids = args.flatten.compact.uniq
+
+        # If no ids given, raise RecordNotFound.
+        if ids.empty?
+          raise RecordNotFound, "Couldn't find #{@association_class.name} without an ID"
+
+        # If using a custom finder_sql, scan the entire collection.
+        elsif @options[:finder_sql]
+          if ids.size == 1
+            id = ids.first
+            record = load_collection.detect { |record| id == record.id }
+            expects_array? ? [record] : record
+          else
+            load_collection.select { |record| ids.include?(record.id) }
+          end
+
+        # Otherwise, delegate to association class with conditions.
+        else
+          args << { :conditions => "#{@association_class_primary_key_name} = #{@owner.quoted_id} #{@conditions ? " AND " + @conditions : ""}" }
+          @association_class.find(*args)
         end
       end
 
@@ -71,11 +100,7 @@ module ActiveRecord
 
       protected
         def find_all_records
-          if @options[:finder_sql]
-            @association_class.find_by_sql(@finder_sql)
-          else
-            @association_class.find_all(@finder_sql, @options[:order] ? @options[:order] : nil)
-          end
+          find_all
         end
 
         def count_records

data/lib/active_record/base.rb

@@ -26,6 +26,8 @@ module ActiveRecord #:nodoc:
   end
   class PreparedStatementInvalid < ActiveRecordError #:nodoc:
   end
+  class StaleObjectError < ActiveRecordError #:nodoc:
+  end
 
   # Active Record objects doesn't specify their attributes directly, but rather infer them from the table definition with
   # which they're linked. Adding, removing, and changing attributes and their type is done directly in the database. Any change
@@ -95,6 +97,21 @@ module ActiveRecord #:nodoc:
   #     end
   #   end
   # 
+  # == Dynamic attribute-based finders
+  #
+  # Dynamic attribute-based finders are a cleaner way of getting objects by simple queries without turning to SQL. They work by
+  # appending the name of an attribute to <tt>find_by_</tt>, so you get finders like <tt>Person.find_by_user_name, Payment.find_by_transaction_id</tt>.
+  # So instead of writing <tt>Person.find_first(["user_name = ?", user_name])</tt>, you just do <tt>Person.find_by_user_name(user_name)</tt>.
+  # 
+  # It's also possible to use multiple attributes in the same find by separating them with "_and_", so you get finders like
+  # <tt>Person.find_by_user_name_and_password</tt> or even <tt>Payment.find_by_purchaser_and_state_and_country</tt>. So instead of writing
+  # <tt>Person.find_first(["user_name = ? AND password = ?", user_name, password])</tt>, you just do 
+  # <tt>Person.find_by_user_name_and_password(user_name, password)</tt>.
+  # 
+  # It's even possible to use all the additional parameters to find_first and find_all. For example, the full interface for Payment.find_all_by_amount
+  # is actually Payment.find_all_by_amount(amount, orderings = nil, limit = nil, joins = nil). And the full interface to Person.find_by_user_name is
+  # actually Person.find_by_user_name(user_name, orderings = nil)
+  #
   # == Saving arrays, hashes, and other non-mappeable objects in text columns
   # 
   # Active Record can serialize any object in text columns using YAML. To do so, you must specify this with a call to the class method +serialize+. 
@@ -221,14 +238,10 @@ module ActiveRecord #:nodoc:
     cattr_accessor :pluralize_table_names
     @@pluralize_table_names = true
 
-    # When turned on (which is default), all associations are included using "load". This mean that any change is instant in cached
-    # environments like mod_ruby or FastCGI. When set to false, "require" is used, which is faster but requires server restart to
-    # reflect changes.
-    @@reload_associations = true
-    cattr_accessor :reload_associations
-
-    @@associations_loaded = []
-    cattr_accessor :associations_loaded
+    # Determines whether to use Time.local (using :local) or Time.utc (using :utc) when pulling dates and times from the database.
+    # This is set to :local by default.
+    cattr_accessor :default_timezone
+    @@default_timezone = :local
 
     class << self # Class methods
       # Returns objects for the records responding to either a specific id (1), a list of ids (1, 5, 6) or an array of ids. 
@@ -238,44 +251,58 @@ module ActiveRecord #:nodoc:
       #   Person.find(1, 2, 6) # returns an array for objects with IDs in (1, 2, 6)
       #   Person.find([7, 17]) # returns an array for objects with IDs in (7, 17)
       #   Person.find([1])     # returns an array for objects the object with ID = 1
+      #
+      # The last argument may be a Hash of find options.  Currently, +conditions+ is the only option, behaving the same as with +find_all+.
+      #   Person.find(1, :conditions => "associate_id = 5"
+      #   Person.find(1, 2, 6, :conditions => "status = 'active'"
+      #   Person.find([7, 17], :conditions => ["sanitize_me = ?", "bare'quote"]
+      #
       # +RecordNotFound+ is raised if no record can be found.
-      def find(*ids)
-        expects_array = ids.first.kind_of?(Array)
-        ids = ids.flatten.compact.uniq
+      def find(*args)
+        # Return an Array if ids are passed in an Array.
+        expects_array = args.first.kind_of?(Array)
+
+        # Extract options hash from argument list.
+        options = extract_options_from_args!(args)
+        conditions = " AND #{sanitize_sql(options[:conditions])}" if options[:conditions]
+
+        ids = args.flatten.compact.uniq
+        case ids.size
 
-        if ids.length > 1
-          ids_list = ids.map{ |id| "#{sanitize(id)}" }.join(", ")
-          objects  = find_all("#{primary_key} IN (#{ids_list})", primary_key)
+          # Raise if no ids passed.
+          when 0
+            raise RecordNotFound, "Couldn't find #{name} without an ID#{conditions}"
 
-          if objects.length == ids.length
-            return objects
+          # Find a single id.
+          when 1
+            unless result = find_first("#{primary_key} = #{sanitize(ids.first)}#{conditions}")
+              raise RecordNotFound, "Couldn't find #{name} with ID=#{ids.first}#{conditions}"
+            end
+
+            # Box result if expecting array.
+            expects_array ? [result] : result
+
+          # Find multiple ids.
           else
-            raise RecordNotFound, "Couldn't find #{name} with ID in (#{ids_list})"
-          end
-        elsif ids.length == 1
-          id = ids.first
-          sql = "SELECT * FROM #{table_name} WHERE #{primary_key} = #{sanitize(id)}"
-          sql << " AND #{type_condition}" unless descends_from_active_record?
-
-          if record = connection.select_one(sql, "#{name} Find")
-            expects_array ? [instantiate(record)] : instantiate(record)
-          else 
-            raise RecordNotFound, "Couldn't find #{name} with ID = #{id}"
-          end
-        else
-          raise RecordNotFound, "Couldn't find #{name} without an ID"
+            ids_list = ids.map { |id| sanitize(id) }.join(',')
+            result   = find_all("#{primary_key} IN (#{ids_list})#{conditions}", primary_key)
+            if result.size == ids.size
+              result
+            else
+              raise RecordNotFound, "Couldn't find #{name} with ID in (#{ids_list})#{conditions}"
+            end
         end
       end
 
+      # This method is deprecated in favor of find with the :conditions option.
       # Works like find, but the record matching +id+ must also meet the +conditions+.
       # +RecordNotFound+ is raised if no record can be found matching the +id+ or meeting the condition.
       # Example:
       #   Person.find_on_conditions 5, "first_name LIKE '%dav%' AND last_name = 'heinemeier'"
-      def find_on_conditions(id, conditions)
-        find_first("#{primary_key} = #{sanitize(id)} AND #{sanitize_conditions(conditions)}") || 
-            raise(RecordNotFound, "Couldn't find #{name} with #{primary_key} = #{id} on the condition of #{conditions}")
+      def find_on_conditions(ids, conditions)
+        find(ids, :conditions => conditions)
       end
-    
+
       # Returns an array of all the objects that could be instantiated from the associated
       # table in the database. The +conditions+ can be used to narrow the selection of objects (WHERE-part),
       # such as by "color = 'red'", and arrangement of the selection can be done through +orderings+ (ORDER BY-part),
@@ -288,8 +315,9 @@ module ActiveRecord #:nodoc:
         sql << "#{joins} " if joins
         add_conditions!(sql, conditions)
         sql << "ORDER BY #{orderings} " unless orderings.nil?
-        sql << "LIMIT #{sanitize_conditions(limit)} " unless limit.nil?
-    
+
+        connection.add_limit!(sql, sanitize_sql(limit)) unless limit.nil?
+
         find_by_sql(sql)
       end
   
@@ -297,8 +325,7 @@ module ActiveRecord #:nodoc:
       #   Post.find_by_sql "SELECT p.*, c.author FROM posts p, comments c WHERE p.id = c.post_id"
       #   Post.find_by_sql ["SELECT * FROM posts WHERE author = ? AND created > ?", author_id, start_date]
       def find_by_sql(sql)
-        sql = sanitize_conditions(sql)
-        connection.select_all(sql, "#{name} Load").inject([]) { |objects, record| objects << instantiate(record) }
+        connection.select_all(sanitize_sql(sql), "#{name} Load").inject([]) { |objects, record| objects << instantiate(record) }
       end
       
       # Returns the object for the first record responding to the conditions in +conditions+, 
@@ -307,13 +334,7 @@ module ActiveRecord #:nodoc:
       # +orderings+, like "income DESC, name", to control exactly which record is to be used. Example: 
       #   Employee.find_first "income > 50000", "income DESC, name"
       def find_first(conditions = nil, orderings = nil)
-        sql  = "SELECT * FROM #{table_name} "
-        add_conditions!(sql, conditions)
-        sql << "ORDER BY #{orderings} " unless orderings.nil?
-        sql << "LIMIT 1"
-    
-        record = connection.select_one(sql, "#{name} Load First")
-        instantiate(record) unless record.nil?
+        find_all(conditions, orderings, 1).first
       end
     
       # Creates an object, instantly saves it as a record (if the validation permits it), and returns it. If the save
@@ -613,7 +634,7 @@ module ActiveRecord #:nodoc:
 
         # Adds a sanitized version of +conditions+ to the +sql+ string. Note that it's the passed +sql+ string is changed.
         def add_conditions!(sql, conditions)
-          sql << "WHERE #{sanitize_conditions(conditions)} " unless conditions.nil?
+          sql << "WHERE #{sanitize_sql(conditions)} " unless conditions.nil?
           sql << (conditions.nil? ? "WHERE " : " AND ") + type_condition unless descends_from_active_record?
         end
         
@@ -630,6 +651,24 @@ module ActiveRecord #:nodoc:
           return table_name
         end
 
+        # Enables dynamic finders like find_by_user_name(user_name) and find_by_user_name_and_password(user_name, password) that are turned into 
+        # find_first(["user_name = ?", user_name]) and find_first(["user_name = ? AND password = ?", user_name, password]) respectively. Also works
+        # for find_all, but using find_all_by_amount(50) that are turned into find_all(["amount = ?", 50]).
+        # 
+        # It's even possible to use all the additional parameters to find_first and find_all. For example, the full interface for find_all_by_amount
+        # is actually find_all_by_amount(amount, orderings = nil, limit = nil, joins = nil).
+        def method_missing(method_id, *arguments)
+          method_name = method_id.id2name
+
+          if method_name =~ /find_(all_by|by)_([_a-z]+)/
+            finder, attributes = ($1 == "all_by" ? :find_all : :find_first), $2.split("_and_")
+            attributes.each { |attr_name| super unless column_methods_hash[attr_name.intern] }
+            conditions = attributes.collect { |attr_name| "#{attr_name} = ? "}.join(" AND ")
+            send(finder, [conditions, *arguments[0...attributes.length]], *arguments[attributes.length..-1])
+          else
+            super
+          end
+        end
 
       protected
         def subclasses
@@ -656,51 +695,50 @@ module ActiveRecord #:nodoc:
           end
         end
 
-        # Accepts either a condition array or string. The string is returned untouched, but the array has each of
-        # the condition values sanitized.
-        def sanitize_conditions(conditions)
-          return conditions unless conditions.is_a?(Array)
-
-          statement, *values = conditions
+        # Accepts an array or string.  The string is returned untouched, but the array has each value
+        # sanitized and interpolated into the sql statement.
+        #   ["name='%s' and group_id='%s'", "foo'bar", 4]  returns  "name='foo''bar' and group_id='4'"
+        def sanitize_sql(ary)
+          return ary unless ary.is_a?(Array)
 
-          if values[0].is_a?(Hash) && statement =~ /:\w+/
-            replace_named_bind_variables(statement, values[0])
-          elsif statement =~ /\?/ 
+          statement, *values = ary
+          if values.first.is_a?(Hash) and statement =~ /:\w+/
+            replace_named_bind_variables(statement, values.first)
+          elsif statement.include?('?')
             replace_bind_variables(statement, values)
           else
             statement % values.collect { |value| connection.quote_string(value.to_s) }
           end
         end
 
-        def replace_bind_variables(statement, values)
-          orig_statement = statement.clone
-          expected_number_of_variables = statement.count('?')
-          provided_number_of_variables = values.size
-
-          unless expected_number_of_variables == provided_number_of_variables
-            raise PreparedStatementInvalid, "wrong number of bind variables (#{provided_number_of_variables} for #{expected_number_of_variables})"
-          end
+        alias_method :sanitize_conditions, :sanitize_sql
 
-          until values.empty?
-            statement.sub!(/\?/, encode_quoted_value(values.shift))
-          end
-          
-          statement.gsub('?') { |all, match| connection.quote(values.shift) }
+        def replace_bind_variables(statement, values)
+          raise_if_bind_arity_mismatch(statement, statement.count('?'), values.size)
+          bound = values.dup
+          statement.gsub('?') { connection.quote(bound.shift) }
         end
 
-        def replace_named_bind_variables(statement, values_hash)
-          orig_statement = statement.clone
-          values_hash.keys.each do |k|
-            if statement.sub!(/:#{k.id2name}/, encode_quoted_value(values_hash.delete(k))).nil?
-              raise PreparedStatementInvalid, ":#{k} is not a variable in [#{orig_statement}]"
+        def replace_named_bind_variables(statement, bind_vars)
+          raise_if_bind_arity_mismatch(statement, statement.scan(/:(\w+)/).uniq.size, bind_vars.size)
+          statement.gsub(/:(\w+)/) do
+            match = $1.to_sym
+            if bind_vars.has_key?(match)
+              connection.quote(bind_vars[match])
+            else
+              raise PreparedStatementInvalid, "missing value for :#{match} in #{statement}"
             end
           end
+        end
 
-          if statement =~ /(:\w+)/
-            raise PreparedStatementInvalid, "No value provided for #{$1} in [#{orig_statement}]"
+        def raise_if_bind_arity_mismatch(statement, expected, provided)
+          unless expected == provided
+            raise PreparedStatementInvalid, "wrong number of bind variables (#{provided} for #{expected}) in: #{statement}"
           end
+        end
 
-          return statement
+        def extract_options_from_args!(args)
+          if args.last.is_a?(Hash) then args.pop else {} end
         end
         
         def encode_quoted_value(value)
@@ -867,8 +905,8 @@ module ActiveRecord #:nodoc:
 
       # A Person object with a name attribute can ask person.respond_to?("name"), person.respond_to?("name="), and
       # person.respond_to?("name?") which will all return true.
-      def respond_to?(method)
-        self.class.column_methods_hash[method.to_sym] || respond_to_without_attributes?(method)
+      def respond_to?(method, include_priv = false)
+        self.class.column_methods_hash[method.to_sym] || respond_to_without_attributes?(method, include_priv)
       end
       
     private
@@ -919,7 +957,7 @@ module ActiveRecord #:nodoc:
       # table with a master_id foreign key can instantiate master through Client#master.
       def method_missing(method_id, *arguments)
         method_name = method_id.id2name
-      
+
         if method_name =~ read_method? && @attributes.include?($1)
           return read_attribute($1)
         elsif method_name =~ read_untyped_method? && @attributes.include?($1)
@@ -959,7 +997,7 @@ module ActiveRecord #:nodoc:
 
       # Returns true if the attribute is of a text column and marked for serialization.
       def unserializable_attribute?(attr_name, column)
-        @attributes[attr_name] && column.send(:type) == :text && @attributes[attr_name].is_a?(String) && self.class.serialized_attributes[attr_name]
+        @attributes[attr_name] && [:text, :string].include?(column.send(:type)) && @attributes[attr_name].is_a?(String) && self.class.serialized_attributes[attr_name]
       end
 
       # Returns the unserialized object of the attribute.