activerecord 1.0.0 → 4.0.0

data/lib/active_record/validations/uniqueness.rb

@@ -0,0 +1,225 @@
+module ActiveRecord
+  module Validations
+    class UniquenessValidator < ActiveModel::EachValidator # :nodoc:
+      def initialize(options)
+        if options[:conditions] && !options[:conditions].respond_to?(:call)
+          raise ArgumentError, "#{options[:conditions]} was passed as :conditions but is not callable. " \
+                               "Pass a callable instead: `conditions: -> { where(approved: true) }`"
+        end
+        super({ case_sensitive: true }.merge!(options))
+      end
+
+      # Unfortunately, we have to tie Uniqueness validators to a class.
+      def setup(klass)
+        @klass = klass
+      end
+
+      def validate_each(record, attribute, value)
+        finder_class = find_finder_class_for(record)
+        table = finder_class.arel_table
+        value = deserialize_attribute(record, attribute, value)
+
+        relation = build_relation(finder_class, table, attribute, value)
+        relation = relation.and(table[finder_class.primary_key.to_sym].not_eq(record.id)) if record.persisted?
+        relation = scope_relation(record, table, relation)
+        relation = finder_class.unscoped.where(relation)
+        relation = relation.merge(options[:conditions]) if options[:conditions]
+
+        if relation.exists?
+          error_options = options.except(:case_sensitive, :scope, :conditions)
+          error_options[:value] = value
+
+          record.errors.add(attribute, :taken, error_options)
+        end
+      end
+
+    protected
+
+      # The check for an existing value should be run from a class that
+      # isn't abstract. This means working down from the current class
+      # (self), to the first non-abstract class. Since classes don't know
+      # their subclasses, we have to build the hierarchy between self and
+      # the record's class.
+      def find_finder_class_for(record) #:nodoc:
+        class_hierarchy = [record.class]
+
+        while class_hierarchy.first != @klass
+          class_hierarchy.unshift(class_hierarchy.first.superclass)
+        end
+
+        class_hierarchy.detect { |klass| !klass.abstract_class? }
+      end
+
+      def build_relation(klass, table, attribute, value) #:nodoc:
+        if reflection = klass.reflect_on_association(attribute)
+          attribute = reflection.foreign_key
+          value = value.attributes[reflection.primary_key_column.name]
+        end
+
+        column = klass.columns_hash[attribute.to_s]
+        value  = klass.connection.type_cast(value, column)
+        value  = value.to_s[0, column.limit] if value && column.limit && column.text?
+
+        if !options[:case_sensitive] && value && column.text?
+          # will use SQL LOWER function before comparison, unless it detects a case insensitive collation
+          klass.connection.case_insensitive_comparison(table, attribute, column, value)
+        else
+          value = klass.connection.case_sensitive_modifier(value) unless value.nil?
+          table[attribute].eq(value)
+        end
+      end
+
+      def scope_relation(record, table, relation)
+        Array(options[:scope]).each do |scope_item|
+          if reflection = record.class.reflect_on_association(scope_item)
+            scope_value = record.send(reflection.foreign_key)
+            scope_item  = reflection.foreign_key
+          else
+            scope_value = record.read_attribute(scope_item)
+          end
+          relation = relation.and(table[scope_item].eq(scope_value))
+        end
+
+        relation
+      end
+
+      def deserialize_attribute(record, attribute, value)
+        coder = record.class.serialized_attributes[attribute.to_s]
+        value = coder.dump value if value && coder
+        value
+      end
+    end
+
+    module ClassMethods
+      # Validates whether the value of the specified attributes are unique
+      # across the system. Useful for making sure that only one user
+      # can be named "davidhh".
+      #
+      #   class Person < ActiveRecord::Base
+      #     validates_uniqueness_of :user_name
+      #   end
+      #
+      # It can also validate whether the value of the specified attributes are
+      # unique based on a <tt>:scope</tt> parameter:
+      #
+      #   class Person < ActiveRecord::Base
+      #     validates_uniqueness_of :user_name, scope: :account_id
+      #   end
+      #
+      # Or even multiple scope parameters. For example, making sure that a
+      # teacher can only be on the schedule once per semester for a particular
+      # class.
+      #
+      #   class TeacherSchedule < ActiveRecord::Base
+      #     validates_uniqueness_of :teacher_id, scope: [:semester_id, :class_id]
+      #   end
+      #
+      # It is also possible to limit the uniqueness constraint to a set of
+      # records matching certain conditions. In this example archived articles
+      # are not being taken into consideration when validating uniqueness
+      # of the title attribute:
+      #
+      #   class Article < ActiveRecord::Base
+      #     validates_uniqueness_of :title, conditions: -> { where.not(status: 'archived') }
+      #   end
+      #
+      # When the record is created, a check is performed to make sure that no
+      # record exists in the database with the given value for the specified
+      # attribute (that maps to a column). When the record is updated,
+      # the same check is made but disregarding the record itself.
+      #
+      # Configuration options:
+      #
+      # * <tt>:message</tt> - Specifies a custom error message (default is:
+      #   "has already been taken").
+      # * <tt>:scope</tt> - One or more columns by which to limit the scope of
+      #   the uniqueness constraint.
+      # * <tt>:conditions</tt> - Specify the conditions to be included as a
+      #   <tt>WHERE</tt> SQL fragment to limit the uniqueness constraint lookup
+      #   (e.g. <tt>conditions: -> { where(status: 'active') }</tt>).
+      # * <tt>:case_sensitive</tt> - Looks for an exact match. Ignored by
+      #   non-text columns (+true+ by default).
+      # * <tt>:allow_nil</tt> - If set to +true+, skips this validation if the
+      #   attribute is +nil+ (default is +false+).
+      # * <tt>:allow_blank</tt> - If set to +true+, skips this validation if the
+      #   attribute is blank (default is +false+).
+      # * <tt>:if</tt> - Specifies a method, proc or string to call to determine
+      #   if the validation should occur (e.g. <tt>if: :allow_validation</tt>,
+      #   or <tt>if: Proc.new { |user| user.signup_step > 2 }</tt>). The method,
+      #   proc or string should return or evaluate to a +true+ or +false+ value.
+      # * <tt>:unless</tt> - Specifies a method, proc or string to call to
+      #   determine if the validation should ot occur (e.g. <tt>unless: :skip_validation</tt>,
+      #   or <tt>unless: Proc.new { |user| user.signup_step <= 2 }</tt>). The
+      #   method, proc or string should return or evaluate to a +true+ or +false+
+      #   value.
+      #
+      # === Concurrency and integrity
+      #
+      # Using this validation method in conjunction with ActiveRecord::Base#save
+      # does not guarantee the absence of duplicate record insertions, because
+      # uniqueness checks on the application level are inherently prone to race
+      # conditions. For example, suppose that two users try to post a Comment at
+      # the same time, and a Comment's title must be unique. At the database-level,
+      # the actions performed by these users could be interleaved in the following manner:
+      #
+      #               User 1                 |               User 2
+      #  ------------------------------------+--------------------------------------
+      #  # User 1 checks whether there's     |
+      #  # already a comment with the title  |
+      #  # 'My Post'. This is not the case.  |
+      #  SELECT * FROM comments              |
+      #  WHERE title = 'My Post'             |
+      #                                      |
+      #                                      | # User 2 does the same thing and also
+      #                                      | # infers that his title is unique.
+      #                                      | SELECT * FROM comments
+      #                                      | WHERE title = 'My Post'
+      #                                      |
+      #  # User 1 inserts his comment.       |
+      #  INSERT INTO comments                |
+      #  (title, content) VALUES             |
+      #  ('My Post', 'hi!')                  |
+      #                                      |
+      #                                      | # User 2 does the same thing.
+      #                                      | INSERT INTO comments
+      #                                      | (title, content) VALUES
+      #                                      | ('My Post', 'hello!')
+      #                                      |
+      #                                      | # ^^^^^^
+      #                                      | # Boom! We now have a duplicate
+      #                                      | # title!
+      #
+      # This could even happen if you use transactions with the 'serializable'
+      # isolation level. The best way to work around this problem is to add a unique
+      # index to the database table using
+      # ActiveRecord::ConnectionAdapters::SchemaStatements#add_index. In the
+      # rare case that a race condition occurs, the database will guarantee
+      # the field's uniqueness.
+      #
+      # When the database catches such a duplicate insertion,
+      # ActiveRecord::Base#save will raise an ActiveRecord::StatementInvalid
+      # exception. You can either choose to let this error propagate (which
+      # will result in the default Rails exception page being shown), or you
+      # can catch it and restart the transaction (e.g. by telling the user
+      # that the title already exists, and asking him to re-enter the title).
+      # This technique is also known as optimistic concurrency control:
+      # http://en.wikipedia.org/wiki/Optimistic_concurrency_control.
+      #
+      # The bundled ActiveRecord::ConnectionAdapters distinguish unique index
+      # constraint errors from other types of database errors by throwing an
+      # ActiveRecord::RecordNotUnique exception. For other adapters you will
+      # have to parse the (database-specific) exception message to detect such
+      # a case.
+      #
+      # The following bundled adapters throw the ActiveRecord::RecordNotUnique exception:
+      #
+      # * ActiveRecord::ConnectionAdapters::MysqlAdapter.
+      # * ActiveRecord::ConnectionAdapters::Mysql2Adapter.
+      # * ActiveRecord::ConnectionAdapters::SQLite3Adapter.
+      # * ActiveRecord::ConnectionAdapters::PostgreSQLAdapter.
+      def validates_uniqueness_of(*attr_names)
+        validates_with UniquenessValidator, _merge_attributes(attr_names)
+      end
+    end
+  end
+end

data/lib/active_record/validations.rb

@@ -1,205 +1,84 @@
 module ActiveRecord
-  # Active Records implement validation by overwriting Base#validate (or the variations, +validate_on_create+ and 
-  # +validate_on_update+). Each of these methods can inspect the state of the object, which usually means ensuring
-  # that a number of attributes have a certain value (such as not empty, within a given range, matching a certain regular expression).
+  # = Active Record RecordInvalid
   #
-  # Example:
+  # Raised by <tt>save!</tt> and <tt>create!</tt> when the record is invalid. Use the
+  # +record+ method to retrieve the record which did not validate.
   #
-  #   class Person < ActiveRecord::Base
-  #     protected
-  #       def validate
-  #         errors.add_on_empty %w( first_name last_name )
-  #         errors.add("phone_number", "has invalid format") unless phone_number =~ /[0-9]*/
-  #       end
-  #
-  #       def validate_on_create # is only run the first time a new object is saved
-  #         unless valid_discount?(membership_discount)
-  #           errors.add("membership_discount", "has expired")
-  #         end
-  #       end
-  #
-  #       def validate_on_update
-  #         errors.add_to_base("No changes have occured") if unchanged_attributes?
-  #       end
+  #   begin
+  #     complex_operation_that_calls_save!_internally
+  #   rescue ActiveRecord::RecordInvalid => invalid
+  #     puts invalid.record.errors
   #   end
-  #
-  #   person = Person.new("first_name" => "David", "phone_number" => "what?")
-  #   person.save                         # => false (and doesn't do the save)
-  #   person.errors.empty?                # => false
-  #   person.count                        # => 2
-  #   person.errors.on "last_name"        # => "can't be empty"
-  #   person.errors.on "phone_number"     # => "has invalid format"
-  #   person.each_full { |msg| puts msg } # => "Last name can't be empty\n" +
-  #                                            "Phone number has invalid format"
-  #
-  #   person.attributes = { "last_name" => "Heinemeier", "phone_number" => "555-555" }
-  #   person.save # => true (and person is now saved in the database)
-  #
-  # An +Errors+ object is automatically created for every Active Record.
-  module Validations
-    def self.append_features(base) # :nodoc:
-      super
-
-      base.class_eval do
-        alias_method :save_without_validation, :save
-        alias_method :save, :save_with_validation
-
-        alias_method :update_attribute_without_validation_skipping, :update_attribute
-        alias_method :update_attribute, :update_attribute_with_validation_skipping
-      end
-    end
-
-    # The validation process on save can be skipped by passing false. The regular Base#save method is
-    # replaced with this when the validations module is mixed in, which it is by default.
-    def save_with_validation(perform_validation = true)
-      if perform_validation && valid? || !perform_validation then save_without_validation else false end
+  class RecordInvalid < ActiveRecordError
+    attr_reader :record # :nodoc:
+    def initialize(record) # :nodoc:
+      @record = record
+      errors = @record.errors.full_messages.join(", ")
+      super(I18n.t(:"#{@record.class.i18n_scope}.errors.messages.record_invalid", :errors => errors, :default => :"errors.messages.record_invalid"))
     end
-
-    # Updates a single attribute and saves the record without going through the normal validation procedure.
-    # This is especially useful for boolean flags on existing records. The regular +update_attribute+ method
-    # in Base is replaced with this when the validations module is mixed in, which it is by default.
-    def update_attribute_with_validation_skipping(name, value)
-      @attributes[name] = value
-      save(false)
-    end
-
-    # Runs validate and validate_on_create or validate_on_update and returns true if no errors were added otherwise false.
-    def valid?
-      errors.clear
-      validate
-      if new_record? then validate_on_create else validate_on_update end
-      errors.empty?
-    end
-
-    # Returns the Errors object that holds all information about attribute error messages.
-    def errors
-      @errors = Errors.new(self) if @errors.nil?
-      @errors
-    end
-
-    protected
-      # Overwrite this method for validation checks on all saves and use Errors.add(field, msg) for invalid attributes.
-      def validate #:doc:
-      end 
-
-      # Overwrite this method for validation checks used only on creation.
-      def validate_on_create #:doc:
-      end
-
-      # Overwrite this method for validation checks used only on updates.
-      def validate_on_update # :doc:
-      end
   end
 
-  # Active Record validation is reported to and from this object, which is used by Base#save to
-  # determine whether the object in a valid state to be saved. See usage example in Validations.
-  class Errors
-    def initialize(base) # :nodoc:
-      @base, @errors = base, {}
-    end
-    
-    # Adds an error to the base object instead of any particular attribute. This is used
-    # to report errors that doesn't tie to any specific attribute, but rather to the object
-    # as a whole. These error messages doesn't get prepended with any field name when iterating
-    # with each_full, so they should be complete sentences.
-    def add_to_base(msg)
-      add(:base, msg)
-    end
-
-    # Adds an error message (+msg+) to the +attribute+, which will be returned on a call to <tt>on(attribute)</tt>
-    # for the same attribute and ensure that this error object returns false when asked if +empty?+. More than one
-    # error can be added to the same +attribute+ in which case an array will be returned on a call to <tt>on(attribute)</tt>.
-    # If no +msg+ is supplied, "invalid" is assumed.
-    def add(attribute, msg = "invalid")
-      @errors[attribute] = [] if @errors[attribute].nil?
-      @errors[attribute] << msg
-    end
-
-    # Will add an error message to each of the attributes in +attributes+ that is empty (defined by <tt>attribute_present?</tt>).
-    def add_on_empty(attributes, msg = "can't be empty")
-      [attributes].flatten.each { |attr| add(attr, msg) unless @base.attribute_present?(attr) }
-    end
-
-    # Will add an error message to each of the attributes in +attributes+ that has a length outside of the passed boundary +range+. 
-    # If the length is above the boundary, the too_long_msg message will be used. If below, the too_short_msg.
-    def add_on_boundary_breaking(attributes, range, too_long_msg = "is too long (max is %d characters)", too_short_msg = "is too short (min is %d characters)")
-      for attr in [attributes].flatten
-        add(attr, too_short_msg % range.begin) if @base.attribute_present?(attr) && @base.send(attr).length < range.begin
-        add(attr, too_long_msg % range.end) if @base.attribute_present?(attr) && @base.send(attr).length > range.end
+  # = Active Record Validations
+  #
+  # Active Record includes the majority of its validations from <tt>ActiveModel::Validations</tt>
+  # all of which accept the <tt>:on</tt> argument to define the context where the
+  # validations are active. Active Record will always supply either the context of
+  # <tt>:create</tt> or <tt>:update</tt> dependent on whether the model is a
+  # <tt>new_record?</tt>.
+  module Validations
+    extend ActiveSupport::Concern
+    include ActiveModel::Validations
+
+    module ClassMethods
+      # Creates an object just like Base.create but calls <tt>save!</tt> instead of +save+
+      # so an exception is raised if the record is invalid.
+      def create!(attributes = nil, &block)
+        if attributes.is_a?(Array)
+          attributes.collect { |attr| create!(attr, &block) }
+        else
+          object = new(attributes)
+          yield(object) if block_given?
+          object.save!
+          object
+        end
       end
     end
 
-    alias :add_on_boundry_breaking :add_on_boundary_breaking
-
-    # Returns true if the specified +attribute+ has errors associated with it.
-    def invalid?(attribute)
-      !@errors[attribute].nil?
+    # The validation process on save can be skipped by passing <tt>validate: false</tt>.
+    # The regular Base#save method is replaced with this when the validations
+    # module is mixed in, which it is by default.
+    def save(options={})
+      perform_validations(options) ? super : false
     end
 
-    # * Returns nil, if no errors are associated with the specified +attribute+.
-    # * Returns the error message, if one error is associated with the specified +attribute+.
-    # * Returns an array of error messages, if more than one error is associated with the specified +attribute+.
-    def on(attribute)
-      if @errors[attribute].nil?
-        nil
-      elsif @errors[attribute].length == 1
-        @errors[attribute].first
-      else
-        @errors[attribute]
-      end
+    # 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.
+    def save!(options={})
+      perform_validations(options) ? super : raise(RecordInvalid.new(self))
     end
 
-    alias :[] :on
-
-    # Returns errors assigned to base object through add_to_base according to the normal rules of on(attribute).
-    def on_base
-      on(:base)
-    end
-    
-    # Yields each attribute and associated message per error added.
-    def each
-      @errors.each_key { |attr| @errors[attr].each { |msg| yield attr, msg } }
-    end
-    
-    # Yields each full error message added. So Person.errors.add("first_name", "can't be empty") will be returned
-    # through iteration as "First name can't be empty".
-    def each_full
-      full_messages.each { |msg| yield msg }
+    # Runs all the validations within the specified context. Returns +true+ if
+    # no errors are found, +false+ otherwise.
+    #
+    # If the argument is +false+ (default is +nil+), the context is set to <tt>:create</tt> if
+    # <tt>new_record?</tt> is +true+, and to <tt>:update</tt> if it is not.
+    #
+    # Validations with no <tt>:on</tt> option will run no matter the context. Validations with
+    # some <tt>:on</tt> option will only run in the specified context.
+    def valid?(context = nil)
+      context ||= (new_record? ? :create : :update)
+      output = super(context)
+      errors.empty? && output
     end
 
-    # Returns all the full error messages in an array.
-    def full_messages
-      full_messages = []
-      
-      @errors.each_key do |attr| 
-        @errors[attr].each do |msg|
-          if attr == :base
-            full_messages << msg
-          else
-            full_messages << @base.class.human_attribute_name(attr) + " " + msg
-          end
-        end
-      end
-      
-      return full_messages
-    end
+  protected
 
-    # Returns true if no errors have been added.
-    def empty?
-      return @errors.empty?
-    end
-    
-    # Removes all the errors that have been added.
-    def clear
-      @errors = {}
-    end
-    
-    # Returns the total number of errors added. Two errors added to the same attribute will be counted as such
-    # with this as well.
-    def count
-      error_count = 0
-      @errors.each_value { |attribute| error_count += attribute.length }
-      error_count
+    def perform_validations(options={}) # :nodoc:
+      options[:validate] == false || valid?(options[:context])
     end
   end
 end
+
+require "active_record/validations/associated"
+require "active_record/validations/uniqueness"
+require "active_record/validations/presence"

data/lib/active_record/version.rb

@@ -0,0 +1,11 @@
+module ActiveRecord
+  # Returns the version of the currently loaded ActiveRecord as a Gem::Version
+  def self.version
+    Gem::Version.new "4.0.0"
+  end
+
+  module VERSION #:nodoc:
+    MAJOR, MINOR, TINY, PRE = ActiveRecord.version.segments
+    STRING = ActiveRecord.version.to_s
+  end
+end