activerecord 2.3.18 → 3.0.0.beta

data/lib/active_record/relation/finder_methods.rb

@@ -0,0 +1,315 @@
+module ActiveRecord
+  module FinderMethods
+    # Find operates with four different retrieval approaches:
+    #
+    # * Find by id - This can either be a specific id (1), a list of ids (1, 5, 6), or an array of ids ([5, 6, 10]).
+    #   If no record can be found for all of the listed ids, then RecordNotFound will be raised.
+    # * Find first - This will return the first record matched by the options used. These options can either be specific
+    #   conditions or merely an order. If no record can be matched, +nil+ is returned. Use
+    #   <tt>Model.find(:first, *args)</tt> or its shortcut <tt>Model.first(*args)</tt>.
+    # * Find last - This will return the last record matched by the options used. These options can either be specific
+    #   conditions or merely an order. If no record can be matched, +nil+ is returned. Use
+    #   <tt>Model.find(:last, *args)</tt> or its shortcut <tt>Model.last(*args)</tt>.
+    # * Find all - This will return all the records matched by the options used.
+    #   If no records are found, an empty array is returned. Use
+    #   <tt>Model.find(:all, *args)</tt> or its shortcut <tt>Model.all(*args)</tt>.
+    #
+    # All approaches accept an options hash as their last parameter.
+    #
+    # ==== Parameters
+    #
+    # * <tt>:conditions</tt> - An SQL fragment like "administrator = 1", <tt>[ "user_name = ?", username ]</tt>, or <tt>["user_name = :user_name", { :user_name => user_name }]</tt>. See conditions in the intro.
+    # * <tt>:order</tt> - An SQL fragment like "created_at DESC, name".
+    # * <tt>:group</tt> - An attribute name by which the result should be grouped. Uses the <tt>GROUP BY</tt> SQL-clause.
+    # * <tt>:having</tt> - Combined with +:group+ this can be used to filter the records that a <tt>GROUP BY</tt> returns. Uses the <tt>HAVING</tt> SQL-clause.
+    # * <tt>:limit</tt> - An integer determining the limit on the number of rows that should be returned.
+    # * <tt>:offset</tt> - An integer determining the offset from where the rows should be fetched. So at 5, it would skip rows 0 through 4.
+    # * <tt>:joins</tt> - Either an SQL fragment for additional joins like "LEFT JOIN comments ON comments.post_id = id" (rarely needed),
+    #   named associations in the same form used for the <tt>:include</tt> option, which will perform an <tt>INNER JOIN</tt> on the associated table(s),
+    #   or an array containing a mixture of both strings and named associations.
+    #   If the value is a string, then the records will be returned read-only since they will have attributes that do not correspond to the table's columns.
+    #   Pass <tt>:readonly => false</tt> to override.
+    # * <tt>:include</tt> - Names associations that should be loaded alongside. The symbols named refer
+    #   to already defined associations. See eager loading under Associations.
+    # * <tt>:select</tt> - By default, this is "*" as in "SELECT * FROM", but can be changed if you, for example, want to do a join but not
+    #   include the joined columns. Takes a string with the SELECT SQL fragment (e.g. "id, name").
+    # * <tt>:from</tt> - By default, this is the table name of the class, but can be changed to an alternate table name (or even the name
+    #   of a database view).
+    # * <tt>:readonly</tt> - Mark the returned records read-only so they cannot be saved or updated.
+    # * <tt>:lock</tt> - An SQL fragment like "FOR UPDATE" or "LOCK IN SHARE MODE".
+    #   <tt>:lock => true</tt> gives connection's default exclusive lock, usually "FOR UPDATE".
+    #
+    # ==== Examples
+    #
+    #   # find by id
+    #   Person.find(1)       # returns the object for ID = 1
+    #   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 the object with ID = 1
+    #   Person.find(1, :conditions => "administrator = 1", :order => "created_on DESC")
+    #
+    # Note that returned records may not be in the same order as the ids you
+    # provide since database rows are unordered. Give an explicit <tt>:order</tt>
+    # to ensure the results are sorted.
+    #
+    # ==== Examples
+    #
+    #   # find first
+    #   Person.find(:first) # returns the first object fetched by SELECT * FROM people
+    #   Person.find(:first, :conditions => [ "user_name = ?", user_name])
+    #   Person.find(:first, :conditions => [ "user_name = :u", { :u => user_name }])
+    #   Person.find(:first, :order => "created_on DESC", :offset => 5)
+    #
+    #   # find last
+    #   Person.find(:last) # returns the last object fetched by SELECT * FROM people
+    #   Person.find(:last, :conditions => [ "user_name = ?", user_name])
+    #   Person.find(:last, :order => "created_on DESC", :offset => 5)
+    #
+    #   # find all
+    #   Person.find(:all) # returns an array of objects for all the rows fetched by SELECT * FROM people
+    #   Person.find(:all, :conditions => [ "category IN (?)", categories], :limit => 50)
+    #   Person.find(:all, :conditions => { :friends => ["Bob", "Steve", "Fred"] }
+    #   Person.find(:all, :offset => 10, :limit => 10)
+    #   Person.find(:all, :include => [ :account, :friends ])
+    #   Person.find(:all, :group => "category")
+    #
+    # Example for find with a lock: Imagine two concurrent transactions:
+    # each will read <tt>person.visits == 2</tt>, add 1 to it, and save, resulting
+    # in two saves of <tt>person.visits = 3</tt>.  By locking the row, the second
+    # transaction has to wait until the first is finished; we get the
+    # expected <tt>person.visits == 4</tt>.
+    #
+    #   Person.transaction do
+    #     person = Person.find(1, :lock => true)
+    #     person.visits += 1
+    #     person.save!
+    #   end
+    def find(*args, &block)
+      return to_a.find(&block) if block_given?
+
+      options = args.extract_options!
+
+      if options.present?
+        apply_finder_options(options).find(*args)
+      else
+        case args.first
+        when :first, :last, :all
+          send(args.first)
+        else
+          find_with_ids(*args)
+        end
+      end
+    end
+
+    # A convenience wrapper for <tt>find(:first, *args)</tt>. You can pass in all the
+    # same arguments to this method as you can to <tt>find(:first)</tt>.
+    def first(*args)
+      args.any? ? apply_finder_options(args.first).first : find_first
+    end
+
+    # A convenience wrapper for <tt>find(:last, *args)</tt>. You can pass in all the
+    # same arguments to this method as you can to <tt>find(:last)</tt>.
+    def last(*args)
+      args.any? ? apply_finder_options(args.first).last : find_last
+    end
+
+    # A convenience wrapper for <tt>find(:all, *args)</tt>. You can pass in all the
+    # same arguments to this method as you can to <tt>find(:all)</tt>.
+    def all(*args)
+      args.any? ? apply_finder_options(args.first).to_a : to_a
+    end
+
+    # Returns true if a record exists in the table that matches the +id+ or
+    # conditions given, or false otherwise. The argument can take five forms:
+    #
+    # * Integer - Finds the record with this primary key.
+    # * String - Finds the record with a primary key corresponding to this
+    #   string (such as <tt>'5'</tt>).
+    # * Array - Finds the record that matches these +find+-style conditions
+    #   (such as <tt>['color = ?', 'red']</tt>).
+    # * Hash - Finds the record that matches these +find+-style conditions
+    #   (such as <tt>{:color => 'red'}</tt>).
+    # * No args - Returns false if the table is empty, true otherwise.
+    #
+    # For more information about specifying conditions as a Hash or Array,
+    # see the Conditions section in the introduction to ActiveRecord::Base.
+    #
+    # Note: You can't pass in a condition as a string (like <tt>name =
+    # 'Jamie'</tt>), since it would be sanitized and then queried against
+    # the primary key column, like <tt>id = 'name = \'Jamie\''</tt>.
+    #
+    # ==== Examples
+    #   Person.exists?(5)
+    #   Person.exists?('5')
+    #   Person.exists?(:name => "David")
+    #   Person.exists?(['name LIKE ?', "%#{query}%"])
+    #   Person.exists?
+    def exists?(id = nil)
+      case id
+      when Array, Hash
+        where(id).exists?
+      else
+        relation = select(primary_key).limit(1)
+        relation = relation.where(primary_key.eq(id)) if id
+        relation.first ? true : false
+      end
+    end
+
+    protected
+
+    def find_with_associations
+      including = (@eager_load_values + @includes_values).uniq
+      join_dependency = ActiveRecord::Associations::ClassMethods::JoinDependency.new(@klass, including, nil)
+      rows = construct_relation_for_association_find(join_dependency).to_a
+      join_dependency.instantiate(rows)
+    rescue ThrowResult
+      []
+    end
+
+    def construct_relation_for_association_calculations
+      including = (@eager_load_values + @includes_values).uniq
+      join_dependency = ActiveRecord::Associations::ClassMethods::JoinDependency.new(@klass, including, arel.joins(arel))
+
+      relation = except(:includes, :eager_load, :preload)
+      apply_join_dependency(relation, join_dependency)
+    end
+
+    def construct_relation_for_association_find(join_dependency)
+      relation = except(:includes, :eager_load, :preload, :select).select(@klass.send(:column_aliases, join_dependency))
+      apply_join_dependency(relation, join_dependency)
+    end
+
+    def apply_join_dependency(relation, join_dependency)
+      for association in join_dependency.join_associations
+        relation = association.join_relation(relation)
+      end
+
+      limitable_reflections = @klass.send(:using_limitable_reflections?, join_dependency.reflections)
+
+      if !limitable_reflections && relation.limit_value
+        limited_id_condition = construct_limited_ids_condition(relation.except(:select))
+        relation = relation.where(limited_id_condition)
+      end
+
+      relation = relation.except(:limit, :offset) unless limitable_reflections
+
+      relation
+    end
+
+    def construct_limited_ids_condition(relation)
+      orders = relation.order_values.join(", ")
+      values = @klass.connection.distinct("#{@klass.connection.quote_table_name @klass.table_name}.#{@klass.primary_key}", orders)
+
+      ids_array = relation.select(values).collect {|row| row[@klass.primary_key]}
+      ids_array.empty? ? raise(ThrowResult) : primary_key.in(ids_array)
+    end
+
+    def find_by_attributes(match, attributes, *args)
+      conditions = attributes.inject({}) {|h, a| h[a] = args[attributes.index(a)]; h}
+      result = where(conditions).send(match.finder)
+
+      if match.bang? && result.blank?
+        raise RecordNotFound, "Couldn't find #{@klass.name} with #{conditions.to_a.collect {|p| p.join(' = ')}.join(', ')}"
+      else
+        result
+      end
+    end
+
+    def find_or_instantiator_by_attributes(match, attributes, *args)
+      guard_protected_attributes = false
+
+      if args[0].is_a?(Hash)
+        guard_protected_attributes = true
+        attributes_for_create = args[0].with_indifferent_access
+        conditions = attributes_for_create.slice(*attributes).symbolize_keys
+      else
+        attributes_for_create = conditions = attributes.inject({}) {|h, a| h[a] = args[attributes.index(a)]; h}
+      end
+
+      record = where(conditions).first
+
+      unless record
+        record = @klass.new { |r| r.send(:attributes=, attributes_for_create, guard_protected_attributes) }
+        yield(record) if block_given?
+        record.save if match.instantiator == :create
+      end
+
+      record
+    end
+
+    def find_with_ids(*ids, &block)
+      return to_a.find(&block) if block_given?
+
+      expects_array = ids.first.kind_of?(Array)
+      return ids.first if expects_array && ids.first.empty?
+
+      ids = ids.flatten.compact.uniq
+
+      case ids.size
+      when 0
+        raise RecordNotFound, "Couldn't find #{@klass.name} without an ID"
+      when 1
+        result = find_one(ids.first)
+        expects_array ? [ result ] : result
+      else
+        find_some(ids)
+      end
+    end
+
+    def find_one(id)
+      record = where(primary_key.eq(id)).first
+
+      unless record
+        conditions = arel.send(:where_clauses).join(', ')
+        conditions = " [WHERE #{conditions}]" if conditions.present?
+        raise RecordNotFound, "Couldn't find #{@klass.name} with ID=#{id}#{conditions}"
+      end
+
+      record
+    end
+
+    def find_some(ids)
+      result = where(primary_key.in(ids)).all
+
+      expected_size =
+        if @limit_value && ids.size > @limit_value
+          @limit_value
+        else
+          ids.size
+        end
+
+      # 11 ids with limit 3, offset 9 should give 2 results.
+      if @offset_value && (ids.size - @offset_value < expected_size)
+        expected_size = ids.size - @offset_value
+      end
+
+      if result.size == expected_size
+        result
+      else
+        conditions = arel.send(:where_clauses).join(', ')
+        conditions = " [WHERE #{conditions}]" if conditions.present?
+
+        error = "Couldn't find all #{@klass.name.pluralize} with IDs "
+        error << "(#{ids.join(", ")})#{conditions} (found #{result.size} results, but was looking for #{expected_size})"
+        raise RecordNotFound, error
+      end
+    end
+
+    def find_first
+      if loaded?
+        @records.first
+      else
+        @first ||= limit(1).to_a[0]
+      end
+    end
+
+    def find_last
+      if loaded?
+        @records.last
+      else
+        @last ||= reverse_order.limit(1).to_a[0]
+      end
+    end
+
+  end
+end

data/lib/active_record/relation/predicate_builder.rb

@@ -0,0 +1,46 @@
+module ActiveRecord
+  class PredicateBuilder
+
+    def initialize(engine)
+      @engine = engine
+    end
+
+    def build_from_hash(attributes, default_table)
+      predicates = attributes.map do |column, value|
+        table = default_table
+
+        if value.is_a?(Hash)
+          table = Arel::Table.new(column, :engine => @engine)
+          build_from_hash(value, table)
+        else
+          column = column.to_s
+
+          if column.include?('.')
+            table_name, column = column.split('.', 2)
+            table = Arel::Table.new(table_name, :engine => @engine)
+          end
+
+          attribute = table[column] || Arel::Attribute.new(table, column.to_sym)
+
+          case value
+          when Array, ActiveRecord::Associations::AssociationCollection, ActiveRecord::NamedScope::Scope
+            values = value.to_a
+            attribute.in(values)
+          when Range
+            # TODO : Arel should handle ranges with excluded end.
+            if value.exclude_end?
+              [attribute.gteq(value.begin), attribute.lt(value.end)]
+            else
+              attribute.in(value)
+            end
+          else
+            attribute.eq(value)
+          end
+        end
+      end
+
+      predicates.flatten
+    end
+
+  end
+end

data/lib/active_record/relation/query_methods.rb

@@ -0,0 +1,218 @@
+module ActiveRecord
+  module QueryMethods
+    extend ActiveSupport::Concern
+
+    included do
+      (ActiveRecord::Relation::ASSOCIATION_METHODS + ActiveRecord::Relation::MULTI_VALUE_METHODS).each do |query_method|
+        attr_accessor :"#{query_method}_values"
+
+        class_eval <<-CEVAL
+          def #{query_method}(*args)
+            new_relation = spawn
+            value = Array.wrap(args.flatten).reject {|x| x.blank? }
+            new_relation.#{query_method}_values += value if value.present?
+            new_relation
+          end
+        CEVAL
+      end
+
+      [:where, :having].each do |query_method|
+        class_eval <<-CEVAL
+          def #{query_method}(*args)
+            new_relation = spawn
+            value = build_where(*args)
+            new_relation.#{query_method}_values += [*value] if value.present?
+            new_relation
+          end
+        CEVAL
+      end
+
+      ActiveRecord::Relation::SINGLE_VALUE_METHODS.each do |query_method|
+        attr_accessor :"#{query_method}_value"
+
+        class_eval <<-CEVAL
+          def #{query_method}(value = true)
+            new_relation = spawn
+            new_relation.#{query_method}_value = value
+            new_relation
+          end
+        CEVAL
+      end
+    end
+
+    def lock(locks = true)
+      relation = spawn
+      case locks
+      when String, TrueClass, NilClass
+        spawn.tap {|new_relation| new_relation.lock_value = locks || true }
+      else
+        spawn.tap {|new_relation| new_relation.lock_value = false }
+      end
+    end
+
+    def reverse_order
+      order_clause = arel.send(:order_clauses).join(', ')
+      relation = except(:order)
+
+      if order_clause.present?
+        relation.order(reverse_sql_order(order_clause))
+      else
+        relation.order("#{@klass.table_name}.#{@klass.primary_key} DESC")
+      end
+    end
+
+    def arel
+      @arel ||= build_arel
+    end
+
+    def build_arel
+      arel = table
+
+      joined_associations = []
+      association_joins = []
+
+      joins = @joins_values.map {|j| j.respond_to?(:strip) ? j.strip : j}.uniq
+
+      # Build association joins first
+      joins.each do |join|
+        association_joins << join if [Hash, Array, Symbol].include?(join.class) && !array_of_strings?(join)
+      end
+
+      if association_joins.any?
+        join_dependency = ActiveRecord::Associations::ClassMethods::JoinDependency.new(@klass, association_joins.uniq, nil)
+        to_join = []
+
+        join_dependency.join_associations.each do |association|
+          if (association_relation = association.relation).is_a?(Array)
+            to_join << [association_relation.first, association.association_join.first]
+            to_join << [association_relation.last, association.association_join.last]
+          else
+            to_join << [association_relation, association.association_join]
+          end
+        end
+
+        to_join.each do |tj|
+          unless joined_associations.detect {|ja| ja[0] == tj[0] && ja[1] == tj[1] }
+            joined_associations << tj
+            arel = arel.join(tj[0]).on(*tj[1])
+          end
+        end
+      end
+
+      joins.each do |join|
+        next if join.blank?
+
+        @implicit_readonly = true
+
+        case join
+        when Relation::JoinOperation
+          arel = arel.join(join.relation, join.join_class).on(*join.on)
+        when Hash, Array, Symbol
+          if array_of_strings?(join)
+            join_string = join.join(' ')
+            arel = arel.join(join_string)
+          end
+        else
+          arel = arel.join(join)
+        end
+      end
+
+      @where_values.uniq.each do |where|
+        next if where.blank?
+
+        case where
+        when Arel::SqlLiteral
+          arel = arel.where(where)
+        else
+          sql = where.is_a?(String) ? where : where.to_sql
+          arel = arel.where(Arel::SqlLiteral.new("(#{sql})"))
+        end
+      end
+
+      @having_values.uniq.each do |h|
+        arel = h.is_a?(String) ? arel.having(h) : arel.having(*h)
+      end
+
+      if defined?(@limit_value) && @limit_value.present?
+        arel = arel.take(@limit_value)
+      end
+
+      if defined?(@offset_value) && @offset_value.present?
+        arel = arel.skip(@offset_value)
+      end
+
+      @group_values.uniq.each do |g|
+        arel = arel.group(g) if g.present?
+      end
+
+      @order_values.uniq.each do |o|
+        arel = arel.order(Arel::SqlLiteral.new(o.to_s)) if o.present?
+      end
+
+      selects = @select_values.uniq
+
+      quoted_table_name = @klass.quoted_table_name
+
+      if selects.present?
+        selects.each do |s|
+          @implicit_readonly = false
+          arel = arel.project(s) if s.present?
+        end
+      else
+        arel = arel.project(quoted_table_name + '.*')
+      end
+
+      arel =
+        if defined?(@from_value) && @from_value.present?
+          arel.from(@from_value)
+        else
+          arel.from(quoted_table_name)
+        end
+
+      case @lock_value
+      when TrueClass
+        arel = arel.lock
+      when String
+        arel = arel.lock(@lock_value)
+      end
+
+      arel
+    end
+
+    def build_where(*args)
+      return if args.blank?
+
+      builder = PredicateBuilder.new(table.engine)
+
+      conditions = if [String, Array].include?(args.first.class)
+        @klass.send(:sanitize_sql, args.size > 1 ? args : args.first)
+      elsif args.first.is_a?(Hash)
+        attributes = @klass.send(:expand_hash_conditions_for_aggregates, args.first)
+        builder.build_from_hash(attributes, table)
+      else
+        args.first
+      end
+
+      conditions
+    end
+
+    private
+
+    def reverse_sql_order(order_query)
+      order_query.to_s.split(/,/).each { |s|
+        if s.match(/\s(asc|ASC)$/)
+          s.gsub!(/\s(asc|ASC)$/, ' DESC')
+        elsif s.match(/\s(desc|DESC)$/)
+          s.gsub!(/\s(desc|DESC)$/, ' ASC')
+        else
+          s.concat(' DESC')
+        end
+      }.join(',')
+    end
+
+    def array_of_strings?(o)
+      o.is_a?(Array) && o.all?{|obj| obj.is_a?(String)}
+    end
+
+  end
+end