base.rb 129.3 KB
Newer Older
D
Initial  
David Heinemeier Hansson 已提交
1
require 'yaml'
2
require 'set'
D
Initial  
David Heinemeier Hansson 已提交
3 4

module ActiveRecord #:nodoc:
P
Pratik Naik 已提交
5
  # Generic Active Record exception class.
6
  class ActiveRecordError < StandardError
D
Initial  
David Heinemeier Hansson 已提交
7
  end
8

P
Pratik Naik 已提交
9
  # Raised when the single-table inheritance mechanism fails to locate the subclass
10
  # (for example due to improper usage of column that +inheritance_column+ points to).
11 12
  class SubclassNotFound < ActiveRecordError #:nodoc:
  end
13

14
  # Raised when an object assigned to an association has an incorrect type.
15
  #
16 17 18
  #   class Ticket < ActiveRecord::Base
  #     has_many :patches
  #   end
19
  #
20 21 22
  #   class Patch < ActiveRecord::Base
  #     belongs_to :ticket
  #   end
23
  #
24 25
  #   # Comments are not patches, this assignment raises AssociationTypeMismatch.
  #   @ticket.patches << Comment.new(:content => "Please attach tests to your patch.")
26
  class AssociationTypeMismatch < ActiveRecordError
D
Initial  
David Heinemeier Hansson 已提交
27
  end
28 29 30

  # Raised when unserialized object's type mismatches one specified for serializable field.
  class SerializationTypeMismatch < ActiveRecordError
D
Initial  
David Heinemeier Hansson 已提交
31
  end
32

P
Pratik Naik 已提交
33
  # Raised when adapter not specified on connection (or configuration file <tt>config/database.yml</tt> misses adapter field).
34
  class AdapterNotSpecified < ActiveRecordError
D
Initial  
David Heinemeier Hansson 已提交
35
  end
36

P
Pratik Naik 已提交
37
  # Raised when Active Record cannot find database adapter specified in <tt>config/database.yml</tt> or programmatically.
38
  class AdapterNotFound < ActiveRecordError
D
Initial  
David Heinemeier Hansson 已提交
39
  end
40

P
Pratik Naik 已提交
41
  # Raised when connection to the database could not been established (for example when <tt>connection=</tt> is given a nil object).
42
  class ConnectionNotEstablished < ActiveRecordError
D
Initial  
David Heinemeier Hansson 已提交
43
  end
44

P
Pratik Naik 已提交
45
  # Raised when Active Record cannot find record by given id or set of ids.
46
  class RecordNotFound < ActiveRecordError
D
Initial  
David Heinemeier Hansson 已提交
47
  end
48 49 50 51

  # Raised by ActiveRecord::Base.save! and ActiveRecord::Base.create! methods when record cannot be
  # saved because record is invalid.
  class RecordNotSaved < ActiveRecordError
52
  end
53 54 55

  # Raised when SQL statement cannot be executed by the database (for example, it's often the case for MySQL when Ruby driver used is too old).
  class StatementInvalid < ActiveRecordError
D
Initial  
David Heinemeier Hansson 已提交
56
  end
57

58
  # Raised when number of bind variables in statement given to <tt>:condition</tt> key (for example, when using +find+ method)
59 60
  # does not match number of expected variables.
  #
61
  # For example, in
62
  #
63
  #   Location.find :all, :conditions => ["lat = ? AND lng = ?", 53.7362]
64
  #
65
  # two placeholders are given but only one variable to fill them.
66
  class PreparedStatementInvalid < ActiveRecordError
67
  end
68 69 70 71 72

  # Raised on attempt to save stale record. Record is stale when it's being saved in another query after
  # instantiation, for example, when two users edit the same wiki page and one starts editing and saves
  # the page before the other.
  #
P
Pratik Naik 已提交
73
  # Read more about optimistic locking in ActiveRecord::Locking module RDoc.
74
  class StaleObjectError < ActiveRecordError
75
  end
76 77 78 79

  # Raised when association is being configured improperly or
  # user tries to use offset and limit together with has_many or has_and_belongs_to_many associations.
  class ConfigurationError < ActiveRecordError
80
  end
81 82 83

  # Raised on attempt to update record that is instantiated as read only.
  class ReadOnlyRecord < ActiveRecordError
84
  end
85

P
Pratik Naik 已提交
86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112
  # ActiveRecord::Transactions::ClassMethods.transaction uses this exception
  # to distinguish a deliberate rollback from other exceptional situations.
  # Normally, raising an exception will cause the +transaction+ method to rollback
  # the database transaction *and* pass on the exception. But if you raise an
  # ActiveRecord::Rollback exception, then the database transaction will be rolled back,
  # without passing on the exception.
  #
  # For example, you could do this in your controller to rollback a transaction:
  #
  #   class BooksController < ActionController::Base
  #     def create
  #       Book.transaction do
  #         book = Book.new(params[:book])
  #         book.save!
  #         if today_is_friday?
  #           # The system must fail on Friday so that our support department
  #           # won't be out of job. We silently rollback this transaction
  #           # without telling the user.
  #           raise ActiveRecord::Rollback, "Call tech support!"
  #         end
  #       end
  #       # ActiveRecord::Rollback is the only exception that won't be passed on
  #       # by ActiveRecord::Base.transaction, so this line will still be reached
  #       # even on Friday.
  #       redirect_to root_url
  #     end
  #   end
113
  class Rollback < ActiveRecordError
114
  end
115

P
Pratik Naik 已提交
116
  # Raised when attribute has a name reserved by Active Record (when attribute has name of one of Active Record instance methods).
117
  class DangerousAttributeError < ActiveRecordError
118
  end
119

P
Pratik Naik 已提交
120 121
  # Raised when you've tried to access a column which wasn't loaded by your finder.
  # Typically this is because <tt>:select</tt> has been specified.
122 123
  class MissingAttributeError < NoMethodError
  end
124

125 126 127 128
  # Raised when unknown attributes are supplied via mass assignment.
  class UnknownAttributeError < NoMethodError
  end

P
Pratik Naik 已提交
129
  # Raised when an error occurred while doing a mass assignment to an attribute through the
P
Pratik Naik 已提交
130 131 132
  # <tt>attributes=</tt> method. The exception has an +attribute+ property that is the name of the
  # offending attribute.
  class AttributeAssignmentError < ActiveRecordError
133 134 135 136 137 138 139
    attr_reader :exception, :attribute
    def initialize(message, exception, attribute)
      @exception = exception
      @attribute = attribute
      @message = message
    end
  end
140

P
Pratik Naik 已提交
141 142 143 144
  # Raised when there are multiple errors while doing a mass assignment through the +attributes+
  # method. The exception has an +errors+ property that contains an array of AttributeAssignmentError
  # objects, each corresponding to the error while assigning to an attribute.
  class MultiparameterAssignmentErrors < ActiveRecordError
145 146 147 148 149
    attr_reader :errors
    def initialize(errors)
      @errors = errors
    end
  end
150

151
  # Active Record objects don't specify their attributes directly, but rather infer them from the table definition with
D
Initial  
David Heinemeier Hansson 已提交
152 153
  # which they're linked. Adding, removing, and changing attributes and their type is done directly in the database. Any change
  # is instantly reflected in the Active Record objects. The mapping that binds a given Active Record class to a certain
154 155
  # database table will happen automatically in most common cases, but can be overwritten for the uncommon ones.
  #
D
Initial  
David Heinemeier Hansson 已提交
156
  # See the mapping rules in table_name and the full example in link:files/README.html for more insight.
157
  #
D
Initial  
David Heinemeier Hansson 已提交
158
  # == Creation
159
  #
160
  # Active Records accept constructor parameters either in a hash or as a block. The hash method is especially useful when
161
  # you're receiving the data from somewhere else, like an HTTP request. It works like this:
162
  #
163
  #   user = User.new(:name => "David", :occupation => "Code Artist")
D
Initial  
David Heinemeier Hansson 已提交
164
  #   user.name # => "David"
165
  #
D
Initial  
David Heinemeier Hansson 已提交
166
  # You can also use block initialization:
167
  #
D
Initial  
David Heinemeier Hansson 已提交
168 169 170 171
  #   user = User.new do |u|
  #     u.name = "David"
  #     u.occupation = "Code Artist"
  #   end
172
  #
D
Initial  
David Heinemeier Hansson 已提交
173
  # And of course you can just create a bare object and specify the attributes after the fact:
174
  #
D
Initial  
David Heinemeier Hansson 已提交
175 176 177
  #   user = User.new
  #   user.name = "David"
  #   user.occupation = "Code Artist"
178
  #
D
Initial  
David Heinemeier Hansson 已提交
179
  # == Conditions
180
  #
181
  # Conditions can either be specified as a string, array, or hash representing the WHERE-part of an SQL statement.
D
Initial  
David Heinemeier Hansson 已提交
182
  # The array form is to be used when the condition input is tainted and requires sanitization. The string form can
183
  # be used for statements that don't involve tainted data. The hash form works much like the array form, except
184
  # only equality and range is possible. Examples:
185
  #
186
  #   class User < ActiveRecord::Base
D
Initial  
David Heinemeier Hansson 已提交
187
  #     def self.authenticate_unsafely(user_name, password)
188
  #       find(:first, :conditions => "user_name = '#{user_name}' AND password = '#{password}'")
D
Initial  
David Heinemeier Hansson 已提交
189
  #     end
190
  #
D
Initial  
David Heinemeier Hansson 已提交
191
  #     def self.authenticate_safely(user_name, password)
192
  #       find(:first, :conditions => [ "user_name = ? AND password = ?", user_name, password ])
D
Initial  
David Heinemeier Hansson 已提交
193
  #     end
194 195 196 197
  #
  #     def self.authenticate_safely_simply(user_name, password)
  #       find(:first, :conditions => { :user_name => user_name, :password => password })
  #     end
D
Initial  
David Heinemeier Hansson 已提交
198
  #   end
199
  #
200
  # The <tt>authenticate_unsafely</tt> method inserts the parameters directly into the query and is thus susceptible to SQL-injection
201
  # attacks if the <tt>user_name</tt> and +password+ parameters come directly from an HTTP request. The <tt>authenticate_safely</tt>  and
202
  # <tt>authenticate_safely_simply</tt> both will sanitize the <tt>user_name</tt> and +password+ before inserting them in the query,
203
  # which will ensure that an attacker can't escape the query and fake the login (or worse).
204
  #
205
  # When using multiple parameters in the conditions, it can easily become hard to read exactly what the fourth or fifth
206
  # question mark is supposed to represent. In those cases, you can resort to named bind variables instead. That's done by replacing
207 208
  # the question marks with symbols and supplying a hash with values for the matching symbol keys:
  #
209
  #   Company.find(:first, :conditions => [
210
  #     "id = :id AND name = :name AND division = :division AND created_at > :accounting_date",
211 212 213
  #     { :id => 3, :name => "37signals", :division => "First", :accounting_date => '2005-01-01' }
  #   ])
  #
214 215 216 217 218 219
  # Similarly, a simple hash without a statement will generate conditions based on equality with the SQL AND
  # operator. For instance:
  #
  #   Student.find(:all, :conditions => { :first_name => "Harvey", :status => 1 })
  #   Student.find(:all, :conditions => params[:student])
  #
220 221 222
  # A range may be used in the hash to use the SQL BETWEEN operator:
  #
  #   Student.find(:all, :conditions => { :grade => 9..12 })
223
  #
P
Pratik Naik 已提交
224 225 226 227
  # An array may be used in the hash to use the SQL IN operator:
  #
  #   Student.find(:all, :conditions => { :grade => [9,11,12] })
  #
D
Initial  
David Heinemeier Hansson 已提交
228
  # == Overwriting default accessors
229
  #
230 231
  # All column values are automatically available through basic accessors on the Active Record object, but sometimes you
  # want to specialize this behavior. This can be done by overwriting the default accessors (using the same
P
Pratik Naik 已提交
232
  # name as the attribute) and calling <tt>read_attribute(attr_name)</tt> and <tt>write_attribute(attr_name, value)</tt> to actually change things.
D
Initial  
David Heinemeier Hansson 已提交
233
  # Example:
234
  #
D
Initial  
David Heinemeier Hansson 已提交
235 236
  #   class Song < ActiveRecord::Base
  #     # Uses an integer of seconds to hold the length of the song
237
  #
D
Initial  
David Heinemeier Hansson 已提交
238
  #     def length=(minutes)
239
  #       write_attribute(:length, minutes.to_i * 60)
D
Initial  
David Heinemeier Hansson 已提交
240
  #     end
241
  #
D
Initial  
David Heinemeier Hansson 已提交
242
  #     def length
243
  #       read_attribute(:length) / 60
D
Initial  
David Heinemeier Hansson 已提交
244 245
  #     end
  #   end
246
  #
P
Pratik Naik 已提交
247 248
  # You can alternatively use <tt>self[:attribute]=(value)</tt> and <tt>self[:attribute]</tt> instead of <tt>write_attribute(:attribute, value)</tt> and
  # <tt>read_attribute(:attribute)</tt> as a shorter form.
249
  #
250 251 252 253
  # == Attribute query methods
  #
  # In addition to the basic accessors, query methods are also automatically available on the Active Record object.
  # Query methods allow you to test whether an attribute value is present.
254
  #
255 256 257 258 259 260 261 262 263
  # For example, an Active Record User with the <tt>name</tt> attribute has a <tt>name?</tt> method that you can call
  # to determine whether the user has a name:
  #
  #   user = User.new(:name => "David")
  #   user.name? # => true
  #
  #   anonymous = User.new(:name => "")
  #   anonymous.name? # => false
  #
264
  # == Accessing attributes before they have been typecasted
265
  #
266
  # Sometimes you want to be able to read the raw attribute data without having the column-determined typecast run its course first.
P
Pratik Naik 已提交
267
  # That can be done by using the <tt><attribute>_before_type_cast</tt> accessors that all attributes have. For example, if your Account model
P
Pratik Naik 已提交
268
  # has a <tt>balance</tt> attribute, you can call <tt>account.balance_before_type_cast</tt> or <tt>account.id_before_type_cast</tt>.
269 270
  #
  # This is especially useful in validation situations where the user might supply a string for an integer field and you want to display
271
  # the original string back in an error message. Accessing the attribute normally would typecast the string to 0, which isn't what you
272 273
  # want.
  #
274 275
  # == Dynamic attribute-based finders
  #
276
  # Dynamic attribute-based finders are a cleaner way of getting (and/or creating) objects by simple queries without turning to SQL. They work by
D
David Heinemeier Hansson 已提交
277
  # appending the name of an attribute to <tt>find_by_</tt>, <tt>find_last_by_</tt>, or <tt>find_all_by_</tt>, so you get finders like <tt>Person.find_by_user_name</tt>,
P
Pratik Naik 已提交
278
  # <tt>Person.find_all_by_last_name</tt>, and <tt>Payment.find_by_transaction_id</tt>. So instead of writing
279 280
  # <tt>Person.find(:first, :conditions => ["user_name = ?", user_name])</tt>, you just do <tt>Person.find_by_user_name(user_name)</tt>.
  # And instead of writing <tt>Person.find(:all, :conditions => ["last_name = ?", last_name])</tt>, you just do <tt>Person.find_all_by_last_name(last_name)</tt>.
281
  #
282 283
  # 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
284
  # <tt>Person.find(:first, :conditions => ["user_name = ? AND password = ?", user_name, password])</tt>, you just do
285
  # <tt>Person.find_by_user_name_and_password(user_name, password)</tt>.
286
  #
P
Pratik Naik 已提交
287 288
  # It's even possible to use all the additional parameters to find. For example, the full interface for <tt>Payment.find_all_by_amount</tt>
  # is actually <tt>Payment.find_all_by_amount(amount, options)</tt>. And the full interface to <tt>Person.find_by_user_name</tt> is
289
  # actually <tt>Person.find_by_user_name(user_name, options)</tt>. So you could call <tt>Payment.find_all_by_amount(50, :order => "created_on")</tt>.
290
  # Also you may call <tt>Payment.find_last_by_amount(amount, options)</tt> returning the last record matching that amount and options.
291
  #
292
  # The same dynamic finder style can be used to create the object if it doesn't already exist. This dynamic finder is called with
293
  # <tt>find_or_create_by_</tt> and will return the object if it already exists and otherwise creates it, then returns it. Protected attributes won't be set unless they are given in a block. For example:
294 295 296
  #
  #   # No 'Summer' tag exists
  #   Tag.find_or_create_by_name("Summer") # equal to Tag.create(:name => "Summer")
297
  #
298 299 300
  #   # Now the 'Summer' tag does exist
  #   Tag.find_or_create_by_name("Summer") # equal to Tag.find_by_name("Summer")
  #
301 302 303
  #   # Now 'Bob' exist and is an 'admin'
  #   User.find_or_create_by_name('Bob', :age => 40) { |u| u.admin = true }
  #
P
Pratik Naik 已提交
304
  # Use the <tt>find_or_initialize_by_</tt> finder if you want to return a new record without saving it first. Protected attributes won't be set unless they are given in a block. For example:
305 306 307
  #
  #   # No 'Winter' tag exists
  #   winter = Tag.find_or_initialize_by_name("Winter")
308
  #   winter.new_record? # true
309
  #
310 311 312 313 314 315 316
  # To find by a subset of the attributes to be used for instantiating a new object, pass a hash instead of
  # a list of parameters. For example:
  #
  #   Tag.find_or_create_by_name(:name => "rails", :creator => current_user)
  #
  # That will either find an existing tag named "rails", or create a new one while setting the user that created it.
  #
317
  # == Saving arrays, hashes, and other non-mappable objects in text columns
318 319
  #
  # 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+.
320
  # This makes it possible to store arrays, hashes, and other non-mappable objects without doing any additional work. Example:
321
  #
D
Initial  
David Heinemeier Hansson 已提交
322 323 324
  #   class User < ActiveRecord::Base
  #     serialize :preferences
  #   end
325
  #
326
  #   user = User.create(:preferences => { "background" => "black", "display" => large })
D
Initial  
David Heinemeier Hansson 已提交
327
  #   User.find(user.id).preferences # => { "background" => "black", "display" => large }
328
  #
329
  # You can also specify a class option as the second parameter that'll raise an exception if a serialized object is retrieved as a
D
Initial  
David Heinemeier Hansson 已提交
330
  # descendent of a class not in the hierarchy. Example:
331
  #
D
Initial  
David Heinemeier Hansson 已提交
332
  #   class User < ActiveRecord::Base
333
  #     serialize :preferences, Hash
D
Initial  
David Heinemeier Hansson 已提交
334
  #   end
335
  #
336
  #   user = User.create(:preferences => %w( one two three ))
D
Initial  
David Heinemeier Hansson 已提交
337
  #   User.find(user.id).preferences    # raises SerializationTypeMismatch
338
  #
D
Initial  
David Heinemeier Hansson 已提交
339 340
  # == Single table inheritance
  #
341
  # Active Record allows inheritance by storing the name of the class in a column that by default is named "type" (can be changed
D
Initial  
David Heinemeier Hansson 已提交
342 343 344 345 346 347 348
  # by overwriting <tt>Base.inheritance_column</tt>). This means that an inheritance looking like this:
  #
  #   class Company < ActiveRecord::Base; end
  #   class Firm < Company; end
  #   class Client < Company; end
  #   class PriorityClient < Client; end
  #
P
Pratik Naik 已提交
349 350
  # When you do <tt>Firm.create(:name => "37signals")</tt>, this record will be saved in the companies table with type = "Firm". You can then
  # fetch this row again using <tt>Company.find(:first, "name = '37signals'")</tt> and it will return a Firm object.
D
Initial  
David Heinemeier Hansson 已提交
351
  #
352 353 354
  # If you don't have a type column defined in your table, single-table inheritance won't be triggered. In that case, it'll work just
  # like normal subclasses with no special magic for differentiating between them or reloading the right type with find.
  #
D
Initial  
David Heinemeier Hansson 已提交
355 356
  # Note, all the attributes for all the cases are kept in the same table. Read more:
  # http://www.martinfowler.com/eaaCatalog/singleTableInheritance.html
357
  #
D
Initial  
David Heinemeier Hansson 已提交
358 359 360
  # == Connection to multiple databases in different models
  #
  # Connections are usually created through ActiveRecord::Base.establish_connection and retrieved by ActiveRecord::Base.connection.
361
  # All classes inheriting from ActiveRecord::Base will use this connection. But you can also set a class-specific connection.
P
Pratik Naik 已提交
362 363
  # For example, if Course is an ActiveRecord::Base, but resides in a different database, you can just say <tt>Course.establish_connection</tt>
  # and Course and all of its subclasses will use this connection instead.
D
Initial  
David Heinemeier Hansson 已提交
364 365 366 367 368
  #
  # This feature is implemented by keeping a connection pool in ActiveRecord::Base that is a Hash indexed by the class. If a connection is
  # requested, the retrieve_connection method will go up the class-hierarchy until a connection is found in the connection pool.
  #
  # == Exceptions
369
  #
P
Pratik Naik 已提交
370 371
  # * ActiveRecordError - Generic error class and superclass of all other errors raised by Active Record.
  # * AdapterNotSpecified - The configuration hash used in <tt>establish_connection</tt> didn't include an
D
Initial  
David Heinemeier Hansson 已提交
372
  #   <tt>:adapter</tt> key.
P
Pratik Naik 已提交
373
  # * AdapterNotFound - The <tt>:adapter</tt> key used in <tt>establish_connection</tt> specified a non-existent adapter
374
  #   (or a bad spelling of an existing one).
P
Pratik Naik 已提交
375 376 377 378 379 380 381 382 383
  # * AssociationTypeMismatch - The object assigned to the association wasn't of the type specified in the association definition.
  # * SerializationTypeMismatch - The serialized object wasn't of the class specified as the second parameter.
  # * ConnectionNotEstablished+ - No connection has been established. Use <tt>establish_connection</tt> before querying.
  # * RecordNotFound - No record responded to the +find+ method. Either the row with the given ID doesn't exist
  #   or the row didn't meet the additional restrictions. Some +find+ calls do not raise this exception to signal
  #   nothing was found, please check its documentation for further details.
  # * StatementInvalid - The database server rejected the SQL statement. The precise error is added in the message.
  # * MultiparameterAssignmentErrors - Collection of errors that occurred during a mass assignment using the
  #   <tt>attributes=</tt> method. The +errors+ property of this exception contains an array of AttributeAssignmentError
384
  #   objects that should be inspected to determine which attributes triggered the errors.
P
Pratik Naik 已提交
385
  # * AttributeAssignmentError - An error occurred while doing a mass assignment through the <tt>attributes=</tt> method.
386
  #   You can inspect the +attribute+ property of the exception object to determine which attribute triggered the error.
387
  #
388
  # *Note*: The attributes listed are class-level attributes (accessible from both the class and instance level).
P
Pratik Naik 已提交
389
  # So it's possible to assign a logger to the class through <tt>Base.logger=</tt> which will then be used by all
D
Initial  
David Heinemeier Hansson 已提交
390 391
  # instances in the current object space.
  class Base
P
Pratik Naik 已提交
392 393
    ##  
    # :singleton-method:
D
Initial  
David Heinemeier Hansson 已提交
394 395
    # Accepts a logger conforming to the interface of Log4r or the default Ruby 1.8+ Logger class, which is then passed
    # on to any new database connections made and which can be retrieved on both a class and instance level by calling +logger+.
396
    cattr_accessor :logger, :instance_writer => false
J
Jeremy Kemper 已提交
397

D
Initial  
David Heinemeier Hansson 已提交
398 399 400 401 402
    def self.inherited(child) #:nodoc:
      @@subclasses[self] ||= []
      @@subclasses[self] << child
      super
    end
J
Jeremy Kemper 已提交
403

D
David Heinemeier Hansson 已提交
404
    def self.reset_subclasses #:nodoc:
405
      nonreloadables = []
406
      subclasses.each do |klass|
407
        unless ActiveSupport::Dependencies.autoloaded? klass
408 409 410
          nonreloadables << klass
          next
        end
411 412 413
        klass.instance_variables.each { |var| klass.send(:remove_instance_variable, var) }
        klass.instance_methods(false).each { |m| klass.send :undef_method, m }
      end
414 415
      @@subclasses = {}
      nonreloadables.each { |klass| (@@subclasses[klass.superclass] ||= []) << klass }
416 417
    end

D
Initial  
David Heinemeier Hansson 已提交
418
    @@subclasses = {}
P
Pratik Naik 已提交
419 420 421
    
    ##
    # :singleton-method:
P
Pratik Naik 已提交
422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446
    # Contains the database configuration - as is typically stored in config/database.yml -
    # as a Hash.
    #
    # For example, the following database.yml...
    # 
    #   development:
    #     adapter: sqlite3
    #     database: db/development.sqlite3
    #   
    #   production:
    #     adapter: sqlite3
    #     database: db/production.sqlite3
    #
    # ...would result in ActiveRecord::Base.configurations to look like this:
    #
    #   {
    #      'development' => {
    #         'adapter'  => 'sqlite3',
    #         'database' => 'db/development.sqlite3'
    #      },
    #      'production' => {
    #         'adapter'  => 'sqlite3',
    #         'database' => 'db/production.sqlite3'
    #      }
    #   }
447
    cattr_accessor :configurations, :instance_writer => false
448 449
    @@configurations = {}

P
Pratik Naik 已提交
450 451
    ##
    # :singleton-method:
452
    # Accessor for the prefix type that will be prepended to every primary key column name. The options are :table_name and
D
Initial  
David Heinemeier Hansson 已提交
453 454
    # :table_name_with_underscore. If the first is specified, the Product class will look for "productid" instead of "id" as
    # the primary column. If the latter is specified, the Product class will look for "product_id" instead of "id". Remember
455
    # that this is a global setting for all Active Records.
456
    cattr_accessor :primary_key_prefix_type, :instance_writer => false
D
Initial  
David Heinemeier Hansson 已提交
457 458
    @@primary_key_prefix_type = nil

P
Pratik Naik 已提交
459 460
    ##
    # :singleton-method:
461
    # Accessor for the name of the prefix string to prepend to every table name. So if set to "basecamp_", all
462
    # table names will be named like "basecamp_projects", "basecamp_people", etc. This is a convenient way of creating a namespace
D
Initial  
David Heinemeier Hansson 已提交
463
    # for tables in a shared database. By default, the prefix is the empty string.
464
    cattr_accessor :table_name_prefix, :instance_writer => false
D
Initial  
David Heinemeier Hansson 已提交
465 466
    @@table_name_prefix = ""

P
Pratik Naik 已提交
467 468
    ##
    # :singleton-method:
D
Initial  
David Heinemeier Hansson 已提交
469 470
    # Works like +table_name_prefix+, but appends instead of prepends (set to "_basecamp" gives "projects_basecamp",
    # "people_basecamp"). By default, the suffix is the empty string.
471
    cattr_accessor :table_name_suffix, :instance_writer => false
D
Initial  
David Heinemeier Hansson 已提交
472 473
    @@table_name_suffix = ""

P
Pratik Naik 已提交
474 475
    ##
    # :singleton-method:
476
    # Indicates whether table names should be the pluralized versions of the corresponding class names.
P
Pratik Naik 已提交
477
    # If true, the default table name for a Product class will be +products+. If false, it would just be +product+.
D
Initial  
David Heinemeier Hansson 已提交
478
    # See table_name for the full rules on table/class naming. This is true, by default.
479
    cattr_accessor :pluralize_table_names, :instance_writer => false
D
Initial  
David Heinemeier Hansson 已提交
480 481
    @@pluralize_table_names = true

P
Pratik Naik 已提交
482 483
    ##
    # :singleton-method:
484
    # Determines whether to use ANSI codes to colorize the logging statements committed by the connection adapter. These colors
485
    # make it much easier to overview things during debugging (when used through a reader like +tail+ and on a black background), but
486
    # may complicate matters if you use software like syslog. This is true, by default.
487
    cattr_accessor :colorize_logging, :instance_writer => false
488 489
    @@colorize_logging = true

P
Pratik Naik 已提交
490 491
    ##
    # :singleton-method:
492 493
    # 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.
494
    cattr_accessor :default_timezone, :instance_writer => false
495
    @@default_timezone = :local
496

P
Pratik Naik 已提交
497 498
    ##
    # :singleton-method:
499 500
    # Specifies the format to use when dumping the database schema with Rails'
    # Rakefile.  If :sql, the schema is dumped as (potentially database-
501
    # specific) SQL statements.  If :ruby, the schema is dumped as an
502 503 504
    # ActiveRecord::Schema file which can be loaded into any database that
    # supports migrations.  Use :ruby if you want to have different database
    # adapters for, e.g., your development and test environments.
505
    cattr_accessor :schema_format , :instance_writer => false
506
    @@schema_format = :ruby
507

P
Pratik Naik 已提交
508 509
    ##
    # :singleton-method:
510 511 512 513
    # Specify whether or not to use timestamps for migration numbers
    cattr_accessor :timestamped_migrations , :instance_writer => false
    @@timestamped_migrations = true

514 515 516
    # Determine whether to store the full constant name including namespace when using STI
    superclass_delegating_accessor :store_full_sti_class
    self.store_full_sti_class = false
517

518 519 520 521
    # Stores the default scope for the class
    class_inheritable_accessor :default_scoping, :instance_writer => false
    self.default_scoping = []

D
Initial  
David Heinemeier Hansson 已提交
522
    class << self # Class methods
523
      # Find operates with four different retrieval approaches:
524
      #
P
Pratik Naik 已提交
525
      # * 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]).
526
      #   If no record can be found for all of the listed ids, then RecordNotFound will be raised.
P
Pratik Naik 已提交
527 528 529 530 531 532 533 534 535 536 537 538
      # * 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.
      #
P
Pratik Naik 已提交
539
      # ==== Parameters
P
Pratik Naik 已提交
540
      #
P
Pratik Naik 已提交
541
      # * <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.
P
Pratik Naik 已提交
542 543
      # * <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.
544
      # * <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.
P
Pratik Naik 已提交
545 546 547 548
      # * <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)
      #   or 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).
549
      #   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.
550
      #   Pass <tt>:readonly => false</tt> to override.
P
Pratik Naik 已提交
551
      # * <tt>:include</tt> - Names associations that should be loaded alongside. The symbols named refer
552
      #   to already defined associations. See eager loading under Associations.
P
Pratik Naik 已提交
553
      # * <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
P
Pratik Naik 已提交
554
      #   include the joined columns. Takes a string with the SELECT SQL fragment (e.g. "id, name").
P
Pratik Naik 已提交
555
      # * <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
556
      #   of a database view).
P
Pratik Naik 已提交
557 558
      # * <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".
559
      #   <tt>:lock => true</tt> gives connection's default exclusive lock, usually "FOR UPDATE".
560
      #
P
Pratik Naik 已提交
561 562 563
      # ==== Examples
      #
      #   # find by id
D
Initial  
David Heinemeier Hansson 已提交
564 565 566
      #   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)
567
      #   Person.find([1])     # returns an array for the object with ID = 1
568 569
      #   Person.find(1, :conditions => "administrator = 1", :order => "created_on DESC")
      #
570
      # Note that returned records may not be in the same order as the ids you
571
      # provide since database rows are unordered. Give an explicit <tt>:order</tt>
572 573
      # to ensure the results are sorted.
      #
P
Pratik Naik 已提交
574 575 576
      # ==== Examples
      #
      #   # find first
577
      #   Person.find(:first) # returns the first object fetched by SELECT * FROM people
578
      #   Person.find(:first, :conditions => [ "user_name = ?", user_name])
P
Pratik Naik 已提交
579
      #   Person.find(:first, :conditions => [ "user_name = :u", { :u => user_name }])
580 581
      #   Person.find(:first, :order => "created_on DESC", :offset => 5)
      #
P
Pratik Naik 已提交
582
      #   # find last
583 584 585 586
      #   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)
      #
P
Pratik Naik 已提交
587
      #   # find all
588
      #   Person.find(:all) # returns an array of objects for all the rows fetched by SELECT * FROM people
589
      #   Person.find(:all, :conditions => [ "category IN (?)", categories], :limit => 50)
P
Pratik Naik 已提交
590
      #   Person.find(:all, :conditions => { :friends => ["Bob", "Steve", "Fred"] }
591 592
      #   Person.find(:all, :offset => 10, :limit => 10)
      #   Person.find(:all, :include => [ :account, :friends ])
593
      #   Person.find(:all, :group => "category")
594
      #
P
Pratik Naik 已提交
595 596 597
      # 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
598
      # transaction has to wait until the first is finished; we get the
P
Pratik Naik 已提交
599 600
      # expected <tt>person.visits == 4</tt>.
      #
601 602 603 604 605
      #   Person.transaction do
      #     person = Person.find(1, :lock => true)
      #     person.visits += 1
      #     person.save!
      #   end
606
      def find(*args)
607
        options = args.extract_options!
608 609
        validate_find_options(options)
        set_readonly_option!(options)
610

611
        case args.first
612
          when :first then find_initial(options)
613
          when :last  then find_last(options)
614 615
          when :all   then find_every(options)
          else             find_from_ids(args, options)
D
Initial  
David Heinemeier Hansson 已提交
616 617
        end
      end
618

P
Pratik Naik 已提交
619 620
      # 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>.
621 622 623
      def first(*args)
        find(:first, *args)
      end
624

P
Pratik Naik 已提交
625 626
      # 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>.
627 628 629
      def last(*args)
        find(:last, *args)
      end
630

631 632 633 634 635
      # This is an alias for find(:all).  You can pass in all the same arguments to this method as you can
      # to find(:all)
      def all(*args)
        find(:all, *args)
      end
636

P
Pratik Naik 已提交
637
      # Executes a custom SQL query against your database and returns all the results.  The results will
638
      # be returned as an array with columns requested encapsulated as attributes of the model you call
P
Pratik Naik 已提交
639 640
      # this method from.  If you call <tt>Product.find_by_sql</tt> then the results will be returned in
      # a Product object with the attributes you specified in the SQL query.
641
      #
642 643
      # If you call a complicated SQL query which spans multiple tables the columns specified by the
      # SELECT will be attributes of the model, whether or not they are columns of the corresponding
644 645
      # table.
      #
P
Pratik Naik 已提交
646
      # The +sql+ parameter is a full SQL query as a string.  It will be called as is, there will be
647 648
      # no database agnostic conversions performed.  This should be a last resort because using, for example,
      # MySQL specific terms will lock you to using that particular database engine or require you to
P
Pratik Naik 已提交
649
      # change your call if you switch engines.
650 651
      #
      # ==== Examples
P
Pratik Naik 已提交
652
      #   # A simple SQL query spanning multiple tables
653 654 655 656 657 658
      #   Post.find_by_sql "SELECT p.title, c.author FROM posts p, comments c WHERE p.id = c.post_id"
      #   > [#<Post:0x36bff9c @attributes={"title"=>"Ruby Meetup", "first_name"=>"Quentin"}>, ...]
      #
      #   # You can use the same string replacement techniques as you can with ActiveRecord#find
      #   Post.find_by_sql ["SELECT title FROM posts WHERE author = ? AND created > ?", author_id, start_date]
      #   > [#<Post:0x36bff9c @attributes={"first_name"=>"The Cheap Man Buys Twice"}>, ...]
D
Initial  
David Heinemeier Hansson 已提交
659
      def find_by_sql(sql)
660
        connection.select_all(sanitize_sql(sql), "#{name} Load").collect! { |record| instantiate(record) }
D
Initial  
David Heinemeier Hansson 已提交
661
      end
662

P
Pratik Naik 已提交
663 664 665 666 667 668 669 670 671 672 673

      # Returns true if a record exists in the table that matches the +id+ or
      # conditions given, or false otherwise. The argument can take four 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>).
674
      #
P
Pratik Naik 已提交
675 676
      # For more information about specifying conditions as a Hash or Array,
      # see the Conditions section in the introduction to ActiveRecord::Base.
677
      #
P
Pratik Naik 已提交
678 679 680
      # 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>.
681 682
      #
      # ==== Examples
683
      #   Person.exists?(5)
684
      #   Person.exists?('5')
685
      #   Person.exists?(:name => "David")
686 687
      #   Person.exists?(['name LIKE ?', "%#{query}%"])
      def exists?(id_or_conditions)
688 689
        connection.select_all(
          construct_finder_sql(
690 691
            :select     => "#{quoted_table_name}.#{primary_key}",
            :conditions => expand_id_conditions(id_or_conditions),
692
            :limit      => 1
693
          ),
694 695
          "#{name} Exists"
        ).size > 0
D
Initial  
David Heinemeier Hansson 已提交
696
      end
697

698
      # Creates an object (or multiple objects) and saves it to the database, if validations pass.
699 700 701 702 703 704 705 706
      # The resulting object is returned whether the object was saved successfully to the database or not.
      #
      # The +attributes+ parameter can be either be a Hash or an Array of Hashes.  These Hashes describe the
      # attributes on the objects that are to be created.
      #
      # ==== Examples
      #   # Create a single new object
      #   User.create(:first_name => 'Jamie')
707
      #
708
      #   # Create an Array of new objects
P
Pratik Naik 已提交
709
      #   User.create([{ :first_name => 'Jamie' }, { :first_name => 'Jeremy' }])
710 711 712 713 714 715 716
      #
      #   # Create a single object and pass it into a block to set other attributes.
      #   User.create(:first_name => 'Jamie') do |u|
      #     u.is_admin = false
      #   end
      #
      #   # Creating an Array of new objects using a block, where the block is executed for each object:
P
Pratik Naik 已提交
717
      #   User.create([{ :first_name => 'Jamie' }, { :first_name => 'Jeremy' }]) do |u|
718
      #     u.is_admin = false
719
      #   end
720
      def create(attributes = nil, &block)
721
        if attributes.is_a?(Array)
722
          attributes.collect { |attr| create(attr, &block) }
723 724
        else
          object = new(attributes)
725
          yield(object) if block_given?
726 727 728
          object.save
          object
        end
D
Initial  
David Heinemeier Hansson 已提交
729 730
      end

731 732
      # Updates an object (or multiple objects) and saves it to the database, if validations pass.
      # The resulting object is returned whether the object was saved successfully to the database or not.
733
      #
P
Pratik Naik 已提交
734
      # ==== Parameters
735
      #
P
Pratik Naik 已提交
736 737
      # * +id+ - This should be the id or an array of ids to be updated.
      # * +attributes+ - This should be a Hash of attributes to be set on the object, or an array of Hashes.
738 739 740 741
      #
      # ==== Examples
      #
      #   # Updating one record:
P
Pratik Naik 已提交
742
      #   Person.update(15, { :user_name => 'Samuel', :group => 'expert' })
743
      #
744
      #   # Updating multiple records:
P
Pratik Naik 已提交
745
      #   people = { 1 => { "first_name" => "David" }, 2 => { "first_name" => "Jeremy" } }
746
      #   Person.update(people.keys, people.values)
D
Initial  
David Heinemeier Hansson 已提交
747
      def update(id, attributes)
748 749
        if id.is_a?(Array)
          idx = -1
750
          id.collect { |one_id| idx += 1; update(one_id, attributes[idx]) }
751 752 753 754 755
        else
          object = find(id)
          object.update_attributes(attributes)
          object
        end
D
Initial  
David Heinemeier Hansson 已提交
756 757
      end

758 759 760
      # Delete an object (or multiple objects) where the +id+ given matches the primary_key.  A SQL +DELETE+ command
      # is executed on the database which means that no callbacks are fired off running this.  This is an efficient method
      # of deleting records that don't need cleaning up after or other actions to be taken.
761
      #
P
Pratik Naik 已提交
762 763
      # Objects are _not_ instantiated with this method, and so +:dependent+ rules
      # defined on associations are not honered.
764
      #
P
Pratik Naik 已提交
765
      # ==== Parameters
766
      #
P
Pratik Naik 已提交
767
      # * +id+ - Can be either an Integer or an Array of Integers.
768 769 770 771 772
      #
      # ==== Examples
      #
      #   # Delete a single object
      #   Todo.delete(1)
773
      #
774 775 776
      #   # Delete multiple objects
      #   todos = [1,2,3]
      #   Todo.delete(todos)
777
      def delete(id)
778
        delete_all([ "#{connection.quote_column_name(primary_key)} IN (?)", id ])
779
      end
780

781 782 783
      # Destroy an object (or multiple objects) that has the given id, the object is instantiated first,
      # therefore all callbacks and filters are fired off before the object is deleted.  This method is
      # less efficient than ActiveRecord#delete but allows cleanup methods and other actions to be run.
784 785
      #
      # This essentially finds the object (or multiple objects) with the given id, creates a new object
786 787
      # from the attributes, and then calls destroy on it.
      #
P
Pratik Naik 已提交
788
      # ==== Parameters
789
      #
P
Pratik Naik 已提交
790
      # * +id+ - Can be either an Integer or an Array of Integers.
791 792 793 794 795
      #
      # ==== Examples
      #
      #   # Destroy a single object
      #   Todo.destroy(1)
796
      #
797 798 799
      #   # Destroy multiple objects
      #   todos = [1,2,3]
      #   Todo.destroy(todos)
800
      def destroy(id)
801 802 803 804 805
        if id.is_a?(Array)
          id.map { |one_id| destroy(one_id) }
        else
          find(id).destroy
        end
806 807
      end

808
      # Updates all records with details given if they match a set of conditions supplied, limits and order can
P
Pratik Naik 已提交
809 810
      # also be supplied. This method constructs a single SQL UPDATE statement and sends it straight to the
      # database. It does not instantiate the involved models and it does not trigger Active Record callbacks.
811
      #
P
Pratik Naik 已提交
812
      # ==== Parameters
813
      #
P
Pratik Naik 已提交
814 815
      # * +updates+ - A string of column and value pairs that will be set on any records that match conditions.
      #               What goes into the SET clause.
P
Pratik Naik 已提交
816
      # * +conditions+ - An SQL fragment like "administrator = 1" or [ "user_name = ?", username ]. See conditions in the intro for more info.
P
Pratik Naik 已提交
817
      # * +options+ - Additional options are <tt>:limit</tt> and <tt>:order</tt>, see the examples for usage.
818 819 820 821 822
      #
      # ==== Examples
      #
      #   # Update all billing objects with the 3 different attributes given
      #   Billing.update_all( "category = 'authorized', approved = 1, author = 'David'" )
823
      #
824 825 826 827
      #   # Update records that match our conditions
      #   Billing.update_all( "author = 'David'", "title LIKE '%Rails%'" )
      #
      #   # Update records that match our conditions but limit it to 5 ordered by date
828
      #   Billing.update_all( "author = 'David'", "title LIKE '%Rails%'",
829
      #                         :order => 'created_at', :limit => 5 )
830
      def update_all(updates, conditions = nil, options = {})
831
        sql  = "UPDATE #{quoted_table_name} SET #{sanitize_sql_for_assignment(updates)} "
832

833
        scope = scope(:find)
834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849

        select_sql = ""
        add_conditions!(select_sql, conditions, scope)

        if options.has_key?(:limit) || (scope && scope[:limit])
          # Only take order from scope if limit is also provided by scope, this
          # is useful for updating a has_many association with a limit.
          add_order!(select_sql, options[:order], scope)

          add_limit!(select_sql, options, scope)
          sql.concat(connection.limited_update_conditions(select_sql, quoted_table_name, connection.quote_column_name(primary_key)))
        else
          add_order!(select_sql, options[:order], nil)
          sql.concat(select_sql)
        end

850
        connection.update(sql, "#{name} Update")
D
Initial  
David Heinemeier Hansson 已提交
851
      end
852

P
Pratik Naik 已提交
853 854
      # Destroys the records matching +conditions+ by instantiating each record and calling their +destroy+ method.
      # This means at least 2*N database queries to destroy N records, so avoid +destroy_all+ if you are deleting
855 856 857
      # many records. If you want to simply delete records without worrying about dependent associations or
      # callbacks, use the much faster +delete_all+ method instead.
      #
P
Pratik Naik 已提交
858
      # ==== Parameters
859
      #
P
Pratik Naik 已提交
860
      # * +conditions+ - Conditions are specified the same way as with +find+ method.
861 862 863
      #
      # ==== Example
      #
P
Pratik Naik 已提交
864
      #   Person.destroy_all("last_login < '2004-04-04'")
865 866 867
      #
      # This loads and destroys each person one by one, including its dependent associations and before_ and
      # after_destroy callbacks.
P
Pratik Naik 已提交
868 869 870 871
      #
      # +conditions+ can be anything that +find+ also accepts:
      #
      #   Person.destroy_all(:last_login => 6.hours.ago)
D
Initial  
David Heinemeier Hansson 已提交
872
      def destroy_all(conditions = nil)
873
        find(:all, :conditions => conditions).each { |object| object.destroy }
D
Initial  
David Heinemeier Hansson 已提交
874
      end
875

876
      # Deletes the records matching +conditions+ without instantiating the records first, and hence not
P
Pratik Naik 已提交
877
      # calling the +destroy+ method nor invoking callbacks. This is a single SQL DELETE statement that
P
Pratik Naik 已提交
878 879
      # goes straight to the database, much more efficient than +destroy_all+. Be careful with relations
      # though, in particular <tt>:dependent</tt> rules defined on associations are not honored.
880
      #
P
Pratik Naik 已提交
881
      # ==== Parameters
882
      #
P
Pratik Naik 已提交
883
      # * +conditions+ - Conditions are specified the same way as with +find+ method.
884 885 886
      #
      # ==== Example
      #
P
Pratik Naik 已提交
887 888
      #   Post.delete_all("person_id = 5 AND (category = 'Something' OR category = 'Else')")
      #   Post.delete_all(["person_id = ? AND (category = ? OR category = ?)", 5, 'Something', 'Else'])
889
      #
P
Pratik Naik 已提交
890
      # Both calls delete the affected posts all at once with a single DELETE statement. If you need to destroy dependent
P
Pratik Naik 已提交
891
      # associations or call your <tt>before_*</tt> or +after_destroy+ callbacks, use the +destroy_all+ method instead.
D
Initial  
David Heinemeier Hansson 已提交
892
      def delete_all(conditions = nil)
893
        sql = "DELETE FROM #{quoted_table_name} "
894
        add_conditions!(sql, conditions, scope(:find))
D
Initial  
David Heinemeier Hansson 已提交
895 896 897 898
        connection.delete(sql, "#{name} Delete all")
      end

      # Returns the result of an SQL statement that should only include a COUNT(*) in the SELECT part.
899
      # The use of this method should be restricted to complicated SQL queries that can't be executed
900 901
      # using the ActiveRecord::Calculations class methods.  Look into those before using this.
      #
P
Pratik Naik 已提交
902
      # ==== Parameters
903
      #
P
Pratik Naik 已提交
904
      # * +sql+ - An SQL statement which should return a count query from the database, see the example below.
905 906 907
      #
      # ==== Examples
      #
908
      #   Product.count_by_sql "SELECT COUNT(*) FROM sales s, customers c WHERE s.customer_id = c.id"
D
Initial  
David Heinemeier Hansson 已提交
909
      def count_by_sql(sql)
910
        sql = sanitize_conditions(sql)
911
        connection.select_value(sql, "#{name} Count").to_i
D
Initial  
David Heinemeier Hansson 已提交
912
      end
913

914 915 916 917 918 919
      # A generic "counter updater" implementation, intended primarily to be
      # used by increment_counter and decrement_counter, but which may also
      # be useful on its own. It simply does a direct SQL update for the record
      # with the given ID, altering the given hash of counters by the amount
      # given by the corresponding value:
      #
P
Pratik Naik 已提交
920
      # ==== Parameters
921
      #
P
Pratik Naik 已提交
922 923 924
      # * +id+ - The id of the object you wish to update a counter on.
      # * +counters+ - An Array of Hashes containing the names of the fields
      #   to update as keys and the amount to update the field by as values.
925
      #
926
      # ==== Examples
927 928
      #
      #   # For the Post with id of 5, decrement the comment_count by 1, and
929
      #   # increment the action_count by 1
930
      #   Post.update_counters 5, :comment_count => -1, :action_count => 1
931
      #   # Executes the following SQL:
932 933 934 935 936 937 938
      #   # UPDATE posts
      #   #    SET comment_count = comment_count - 1,
      #   #        action_count = action_count + 1
      #   #  WHERE id = 5
      def update_counters(id, counters)
        updates = counters.inject([]) { |list, (counter_name, increment)|
          sign = increment < 0 ? "-" : "+"
939
          list << "#{connection.quote_column_name(counter_name)} = COALESCE(#{connection.quote_column_name(counter_name)}, 0) #{sign} #{increment.abs}"
940
        }.join(", ")
941
        update_all(updates, "#{connection.quote_column_name(primary_key)} = #{quote_value(id)}")
942 943
      end

944 945
      # Increment a number field by one, usually representing a count.
      #
946 947
      # This is used for caching aggregate values, so that they don't need to be computed every time.
      # For example, a DiscussionBoard may cache post_count and comment_count otherwise every time the board is
948
      # shown it would have to run an SQL query to find how many posts and comments there are.
949
      #
P
Pratik Naik 已提交
950
      # ==== Parameters
951
      #
P
Pratik Naik 已提交
952 953
      # * +counter_name+ - The name of the field that should be incremented.
      # * +id+ - The id of the object that should be incremented.
954 955 956 957 958
      #
      # ==== Examples
      #
      #   # Increment the post_count column for the record with an id of 5
      #   DiscussionBoard.increment_counter(:post_count, 5)
D
Initial  
David Heinemeier Hansson 已提交
959
      def increment_counter(counter_name, id)
960
        update_counters(id, counter_name => 1)
D
Initial  
David Heinemeier Hansson 已提交
961 962
      end

963 964 965 966
      # Decrement a number field by one, usually representing a count.
      #
      # This works the same as increment_counter but reduces the column value by 1 instead of increasing it.
      #
P
Pratik Naik 已提交
967
      # ==== Parameters
968
      #
P
Pratik Naik 已提交
969 970
      # * +counter_name+ - The name of the field that should be decremented.
      # * +id+ - The id of the object that should be decremented.
971 972 973 974 975
      #
      # ==== Examples
      #
      #   # Decrement the post_count column for the record with an id of 5
      #   DiscussionBoard.decrement_counter(:post_count, 5)
D
Initial  
David Heinemeier Hansson 已提交
976
      def decrement_counter(counter_name, id)
977
        update_counters(id, counter_name => -1)
D
Initial  
David Heinemeier Hansson 已提交
978 979
      end

D
David Heinemeier Hansson 已提交
980

P
Pratik Naik 已提交
981 982 983 984 985 986 987 988 989
      # Attributes named in this macro are protected from mass-assignment,
      # such as <tt>new(attributes)</tt>,
      # <tt>update_attributes(attributes)</tt>, or
      # <tt>attributes=(attributes)</tt>.
      #
      # Mass-assignment to these attributes will simply be ignored, to assign
      # to them you can use direct writer methods. This is meant to protect
      # sensitive attributes from being overwritten by malicious users
      # tampering with URLs or forms.
D
Initial  
David Heinemeier Hansson 已提交
990 991 992 993 994 995 996 997 998 999 1000 1001
      #
      #   class Customer < ActiveRecord::Base
      #     attr_protected :credit_rating
      #   end
      #
      #   customer = Customer.new("name" => David, "credit_rating" => "Excellent")
      #   customer.credit_rating # => nil
      #   customer.attributes = { "description" => "Jolly fellow", "credit_rating" => "Superb" }
      #   customer.credit_rating # => nil
      #
      #   customer.credit_rating = "Average"
      #   customer.credit_rating # => "Average"
1002
      #
P
Pratik Naik 已提交
1003 1004
      # To start from an all-closed default and enable attributes as needed,
      # have a look at +attr_accessible+.
D
Initial  
David Heinemeier Hansson 已提交
1005
      def attr_protected(*attributes)
1006
        write_inheritable_attribute(:attr_protected, Set.new(attributes.map(&:to_s)) + (protected_attributes || []))
D
Initial  
David Heinemeier Hansson 已提交
1007
      end
1008

1009
      # Returns an array of all the attributes that have been protected from mass-assignment.
D
Initial  
David Heinemeier Hansson 已提交
1010
      def protected_attributes # :nodoc:
1011
        read_inheritable_attribute(:attr_protected)
D
Initial  
David Heinemeier Hansson 已提交
1012 1013
      end

P
Pratik Naik 已提交
1014 1015 1016 1017
      # Specifies a white list of model attributes that can be set via
      # mass-assignment, such as <tt>new(attributes)</tt>,
      # <tt>update_attributes(attributes)</tt>, or
      # <tt>attributes=(attributes)</tt>
1018
      #
P
Pratik Naik 已提交
1019 1020 1021 1022 1023 1024 1025
      # This is the opposite of the +attr_protected+ macro: Mass-assignment
      # will only set attributes in this list, to assign to the rest of
      # attributes you can use direct writer methods. This is meant to protect
      # sensitive attributes from being overwritten by malicious users
      # tampering with URLs or forms. If you'd rather start from an all-open
      # default and restrict attributes as needed, have a look at
      # +attr_protected+.
1026 1027
      #
      #   class Customer < ActiveRecord::Base
1028
      #     attr_accessible :name, :nickname
1029 1030
      #   end
      #
1031 1032 1033 1034
      #   customer = Customer.new(:name => "David", :nickname => "Dave", :credit_rating => "Excellent")
      #   customer.credit_rating # => nil
      #   customer.attributes = { :name => "Jolly fellow", :credit_rating => "Superb" }
      #   customer.credit_rating # => nil
1035
      #
1036 1037
      #   customer.credit_rating = "Average"
      #   customer.credit_rating # => "Average"
D
Initial  
David Heinemeier Hansson 已提交
1038
      def attr_accessible(*attributes)
1039
        write_inheritable_attribute(:attr_accessible, Set.new(attributes.map(&:to_s)) + (accessible_attributes || []))
D
Initial  
David Heinemeier Hansson 已提交
1040
      end
1041

1042
      # Returns an array of all the attributes that have been made accessible to mass-assignment.
D
Initial  
David Heinemeier Hansson 已提交
1043
      def accessible_attributes # :nodoc:
1044
        read_inheritable_attribute(:attr_accessible)
D
Initial  
David Heinemeier Hansson 已提交
1045 1046
      end

1047 1048
       # Attributes listed as readonly can be set for a new record, but will be ignored in database updates afterwards.
       def attr_readonly(*attributes)
1049
         write_inheritable_attribute(:attr_readonly, Set.new(attributes.map(&:to_s)) + (readonly_attributes || []))
1050 1051 1052 1053
       end

       # Returns an array of all the attributes that have been specified as readonly.
       def readonly_attributes
1054
         read_inheritable_attribute(:attr_readonly)
1055
       end
D
David Heinemeier Hansson 已提交
1056

1057 1058 1059
      # If you have an attribute that needs to be saved to the database as an object, and retrieved as the same object,
      # then specify the name of that attribute using this method and it will be handled automatically.
      # The serialization is done through YAML. If +class_name+ is specified, the serialized object must be of that
P
Pratik Naik 已提交
1060
      # class on retrieval or SerializationTypeMismatch will be raised.
D
David Heinemeier Hansson 已提交
1061
      #
P
Pratik Naik 已提交
1062
      # ==== Parameters
D
David Heinemeier Hansson 已提交
1063
      #
P
Pratik Naik 已提交
1064 1065
      # * +attr_name+ - The field name that should be serialized.
      # * +class_name+ - Optional, class name that the object type should be equal to.
D
David Heinemeier Hansson 已提交
1066 1067 1068 1069 1070 1071
      #
      # ==== Example
      #   # Serialize a preferences attribute
      #   class User
      #     serialize :preferences
      #   end
D
Initial  
David Heinemeier Hansson 已提交
1072
      def serialize(attr_name, class_name = Object)
1073
        serialized_attributes[attr_name.to_s] = class_name
D
Initial  
David Heinemeier Hansson 已提交
1074
      end
1075

D
Initial  
David Heinemeier Hansson 已提交
1076 1077
      # Returns a hash of all the attributes that have been specified for serialization as keys and their class restriction as values.
      def serialized_attributes
1078
        read_inheritable_attribute(:attr_serialized) or write_inheritable_attribute(:attr_serialized, {})
D
Initial  
David Heinemeier Hansson 已提交
1079 1080
      end

D
David Heinemeier Hansson 已提交
1081

D
Initial  
David Heinemeier Hansson 已提交
1082
      # Guesses the table name (in forced lower-case) based on the name of the class in the inheritance hierarchy descending
P
Pratik Naik 已提交
1083
      # directly from ActiveRecord::Base. So if the hierarchy looks like: Reply < Message < ActiveRecord::Base, then Message is used
1084
      # to guess the table name even when called on Reply. The rules used to do the guess are handled by the Inflector class
1085
      # in Active Support, which knows almost all common English inflections. You can add new inflections in config/initializers/inflections.rb.
D
Initial  
David Heinemeier Hansson 已提交
1086
      #
1087
      # Nested classes are given table names prefixed by the singular form of
P
Pratik Naik 已提交
1088 1089 1090
      # the parent's table name. Enclosing modules are not considered.
      #
      # ==== Examples
1091 1092
      #
      #   class Invoice < ActiveRecord::Base; end;
1093 1094
      #   file                  class               table_name
      #   invoice.rb            Invoice             invoices
1095 1096 1097 1098 1099 1100 1101 1102
      #
      #   class Invoice < ActiveRecord::Base; class Lineitem < ActiveRecord::Base; end; end;
      #   file                  class               table_name
      #   invoice.rb            Invoice::Lineitem   invoice_lineitems
      #
      #   module Invoice; class Lineitem < ActiveRecord::Base; end; end;
      #   file                  class               table_name
      #   invoice/lineitem.rb   Invoice::Lineitem   lineitems
D
Initial  
David Heinemeier Hansson 已提交
1103
      #
P
Pratik Naik 已提交
1104 1105
      # Additionally, the class-level +table_name_prefix+ is prepended and the
      # +table_name_suffix+ is appended.  So if you have "myapp_" as a prefix,
1106 1107 1108 1109 1110
      # the table name guess for an Invoice class becomes "myapp_invoices".
      # Invoice::Lineitem becomes "myapp_invoice_lineitems".
      #
      # You can also overwrite this class method to allow for unguessable
      # links, such as a Mouse class with a link to a "mice" table. Example:
D
Initial  
David Heinemeier Hansson 已提交
1111 1112
      #
      #   class Mouse < ActiveRecord::Base
1113
      #     set_table_name "mice"
D
Initial  
David Heinemeier Hansson 已提交
1114
      #   end
1115
      def table_name
1116 1117 1118
        reset_table_name
      end

D
David Heinemeier Hansson 已提交
1119
      def reset_table_name #:nodoc:
1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135
        base = base_class

        name =
          # STI subclasses always use their superclass' table.
          unless self == base
            base.table_name
          else
            # Nested classes are prefixed with singular parent table name.
            if parent < ActiveRecord::Base && !parent.abstract_class?
              contained = parent.table_name
              contained = contained.singularize if parent.pluralize_table_names
              contained << '_'
            end
            name = "#{table_name_prefix}#{contained}#{undecorated_table_name(base.name)}#{table_name_suffix}"
          end

D
David Heinemeier Hansson 已提交
1136
        set_table_name(name)
1137
        name
D
Initial  
David Heinemeier Hansson 已提交
1138 1139
      end

1140
      # Defines the primary key field -- can be overridden in subclasses. Overwriting will negate any effect of the
D
Initial  
David Heinemeier Hansson 已提交
1141 1142
      # primary_key_prefix_type setting, though.
      def primary_key
1143 1144 1145
        reset_primary_key
      end

D
David Heinemeier Hansson 已提交
1146
      def reset_primary_key #:nodoc:
1147 1148 1149 1150 1151 1152
        key = get_primary_key(base_class.name)
        set_primary_key(key)
        key
      end

      def get_primary_key(base_name) #:nodoc:
1153
        key = 'id'
D
Initial  
David Heinemeier Hansson 已提交
1154 1155
        case primary_key_prefix_type
          when :table_name
1156
            key = base_name.to_s.foreign_key(false)
D
Initial  
David Heinemeier Hansson 已提交
1157
          when :table_name_with_underscore
1158
            key = base_name.to_s.foreign_key
D
Initial  
David Heinemeier Hansson 已提交
1159
        end
1160
        key
D
Initial  
David Heinemeier Hansson 已提交
1161 1162
      end

1163 1164
      # Defines the column name for use with single table inheritance
      # -- can be set in subclasses like so: self.inheritance_column = "type_id"
D
Initial  
David Heinemeier Hansson 已提交
1165
      def inheritance_column
1166
        @inheritance_column ||= "type".freeze
D
Initial  
David Heinemeier Hansson 已提交
1167 1168
      end

1169 1170
      # Lazy-set the sequence name to the connection's default.  This method
      # is only ever called once since set_sequence_name overrides it.
D
David Heinemeier Hansson 已提交
1171
      def sequence_name #:nodoc:
1172 1173 1174
        reset_sequence_name
      end

D
David Heinemeier Hansson 已提交
1175
      def reset_sequence_name #:nodoc:
1176 1177 1178
        default = connection.default_sequence_name(table_name, primary_key)
        set_sequence_name(default)
        default
1179 1180
      end

1181
      # Sets the table name to use to the given value, or (if the value
1182
      # is nil or false) to the value returned by the given block.
1183 1184 1185 1186
      #
      #   class Project < ActiveRecord::Base
      #     set_table_name "project"
      #   end
1187
      def set_table_name(value = nil, &block)
1188 1189 1190 1191 1192 1193
        define_attr_method :table_name, value, &block
      end
      alias :table_name= :set_table_name

      # Sets the name of the primary key column to use to the given value,
      # or (if the value is nil or false) to the value returned by the given
1194
      # block.
1195 1196 1197 1198
      #
      #   class Project < ActiveRecord::Base
      #     set_primary_key "sysid"
      #   end
1199
      def set_primary_key(value = nil, &block)
1200 1201 1202 1203 1204 1205
        define_attr_method :primary_key, value, &block
      end
      alias :primary_key= :set_primary_key

      # Sets the name of the inheritance column to use to the given value,
      # or (if the value # is nil or false) to the value returned by the
1206
      # given block.
1207 1208 1209 1210 1211 1212
      #
      #   class Project < ActiveRecord::Base
      #     set_inheritance_column do
      #       original_inheritance_column + "_id"
      #     end
      #   end
1213
      def set_inheritance_column(value = nil, &block)
1214 1215 1216 1217
        define_attr_method :inheritance_column, value, &block
      end
      alias :inheritance_column= :set_inheritance_column

1218 1219
      # Sets the name of the sequence to use when generating ids to the given
      # value, or (if the value is nil or false) to the value returned by the
1220 1221
      # given block. This is required for Oracle and is useful for any
      # database which relies on sequences for primary key generation.
1222
      #
1223 1224 1225 1226 1227
      # If a sequence name is not explicitly set when using Oracle or Firebird,
      # it will default to the commonly used pattern of: #{table_name}_seq
      #
      # If a sequence name is not explicitly set when using PostgreSQL, it
      # will discover the sequence corresponding to your primary key for you.
1228 1229 1230 1231
      #
      #   class Project < ActiveRecord::Base
      #     set_sequence_name "projectseq"   # default would have been "project_seq"
      #   end
1232
      def set_sequence_name(value = nil, &block)
1233 1234 1235 1236
        define_attr_method :sequence_name, value, &block
      end
      alias :sequence_name= :set_sequence_name

D
Initial  
David Heinemeier Hansson 已提交
1237 1238 1239
      # Turns the +table_name+ back into a class name following the reverse rules of +table_name+.
      def class_name(table_name = table_name) # :nodoc:
        # remove any prefix and/or suffix from the table name
1240 1241 1242
        class_name = table_name[table_name_prefix.length..-(table_name_suffix.length + 1)].camelize
        class_name = class_name.singularize if pluralize_table_names
        class_name
D
Initial  
David Heinemeier Hansson 已提交
1243 1244
      end

1245 1246
      # Indicates whether the table associated with this class exists
      def table_exists?
1247
        connection.table_exists?(table_name)
1248 1249
      end

D
Initial  
David Heinemeier Hansson 已提交
1250 1251
      # Returns an array of column objects for the table associated with this class.
      def columns
1252
        unless defined?(@columns) && @columns
1253
          @columns = connection.columns(table_name, "#{name} Columns")
1254
          @columns.each { |column| column.primary = column.name == primary_key }
1255 1256
        end
        @columns
D
Initial  
David Heinemeier Hansson 已提交
1257
      end
1258

1259
      # Returns a hash of column objects for the table associated with this class.
D
Initial  
David Heinemeier Hansson 已提交
1260 1261 1262
      def columns_hash
        @columns_hash ||= columns.inject({}) { |hash, column| hash[column.name] = column; hash }
      end
1263

D
David Heinemeier Hansson 已提交
1264
      # Returns an array of column names as strings.
1265
      def column_names
1266
        @column_names ||= columns.map { |column| column.name }
1267
      end
D
Initial  
David Heinemeier Hansson 已提交
1268

1269 1270
      # Returns an array of column objects where the primary id, all columns ending in "_id" or "_count",
      # and columns used for single table inheritance have been removed.
D
Initial  
David Heinemeier Hansson 已提交
1271
      def content_columns
1272
        @content_columns ||= columns.reject { |c| c.primary || c.name =~ /(_id|_count)$/ || c.name == inheritance_column }
D
Initial  
David Heinemeier Hansson 已提交
1273 1274 1275 1276
      end

      # Returns a hash of all the methods added to query each of the columns in the table with the name of the method as the key
      # and true as the value. This makes it possible to do O(1) lookups in respond_to? to check if a given method for attribute
1277
      # is available.
D
David Heinemeier Hansson 已提交
1278
      def column_methods_hash #:nodoc:
1279
        @dynamic_methods_hash ||= column_names.inject(Hash.new(false)) do |methods, attr|
1280 1281 1282 1283 1284
          attr_name = attr.to_s
          methods[attr.to_sym]       = attr_name
          methods["#{attr}=".to_sym] = attr_name
          methods["#{attr}?".to_sym] = attr_name
          methods["#{attr}_before_type_cast".to_sym] = attr_name
D
Initial  
David Heinemeier Hansson 已提交
1285 1286 1287
          methods
        end
      end
1288

P
Pratik Naik 已提交
1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314
      # Resets all the cached information about columns, which will cause them
      # to be reloaded on the next request.
      #
      # The most common usage pattern for this method is probably in a migration,
      # when just after creating a table you want to populate it with some default
      # values, eg:
      #
      #  class CreateJobLevels < ActiveRecord::Migration
      #    def self.up
      #      create_table :job_levels do |t|
      #        t.integer :id
      #        t.string :name
      #
      #        t.timestamps
      #      end
      #
      #      JobLevel.reset_column_information
      #      %w{assistant executive manager director}.each do |type|
      #        JobLevel.create(:name => type)
      #      end
      #    end
      #
      #    def self.down
      #      drop_table :job_levels
      #    end
      #  end
1315
      def reset_column_information
1316 1317
        generated_methods.each { |name| undef_method(name) }
        @column_names = @columns = @columns_hash = @content_columns = @dynamic_methods_hash = @generated_methods = @inheritance_column = nil
1318 1319
      end

1320
      def reset_column_information_and_inheritable_attributes_for_all_subclasses#:nodoc:
1321 1322
        subclasses.each { |klass| klass.reset_inheritable_attributes; klass.reset_column_information }
      end
D
Initial  
David Heinemeier Hansson 已提交
1323

1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337
      def self_and_descendents_from_active_record#nodoc:
        klass = self
        classes = [klass]
        while klass != klass.base_class  
          classes << klass = klass.superclass
        end
        classes
      rescue
        # OPTIMIZE this rescue is to fix this test: ./test/cases/reflection_test.rb:56:in `test_human_name_for_column'
        # Appearantly the method base_class causes some trouble.
        # It now works for sure.
        [self]
      end

D
Initial  
David Heinemeier Hansson 已提交
1338 1339
      # Transforms attribute key names into a more humane format, such as "First name" instead of "first_name". Example:
      #   Person.human_attribute_name("first_name") # => "First name"
1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351
      # This used to be depricated in favor of humanize, but is now preferred, because it automatically uses the I18n
      # module now.
      # Specify +options+ with additional translating options.
      def human_attribute_name(attribute_key_name, options = {})
        defaults = self_and_descendents_from_active_record.map do |klass|
          :"#{klass.name.underscore}.#{attribute_key_name}"
        end
        defaults << options[:default] if options[:default]
        defaults.flatten!
        defaults << attribute_key_name.humanize
        options[:count] ||= 1
        I18n.translate(defaults.shift, options.merge(:default => defaults, :scope => [:activerecord, :attributes]))
D
Initial  
David Heinemeier Hansson 已提交
1352
      end
I
Iain Hecker 已提交
1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363

      # Transform the modelname into a more humane format, using I18n.
      # Defaults to the basic humanize method.
      # Default scope of the translation is activerecord.models
      # Specify +options+ with additional translating options.
      def human_name(options = {})
        defaults = self_and_descendents_from_active_record.map do |klass|
          :"#{klass.name.underscore}"
        end 
        defaults << self.name.humanize
        I18n.translate(defaults.shift, {:scope => [:activerecord, :models], :count => 1, :default => defaults}.merge(options))
D
Initial  
David Heinemeier Hansson 已提交
1364
      end
1365

1366 1367 1368 1369 1370 1371 1372
      # True if this isn't a concrete subclass needing a STI type condition.
      def descends_from_active_record?
        if superclass.abstract_class?
          superclass.descends_from_active_record?
        else
          superclass == Base || !columns_hash.include?(inheritance_column)
        end
D
Initial  
David Heinemeier Hansson 已提交
1373 1374
      end

1375 1376 1377 1378 1379
      def finder_needs_type_condition? #:nodoc:
        # This is like this because benchmarking justifies the strange :false stuff
        :true == (@finder_needs_type_condition ||= descends_from_active_record? ? :false : :true)
      end

1380
      # Returns a string like 'Post id:integer, title:string, body:text'
1381
      def inspect
1382 1383 1384 1385
        if self == Base
          super
        elsif abstract_class?
          "#{super}(abstract)"
1386
        elsif table_exists?
1387 1388
          attr_list = columns.map { |c| "#{c.name}: #{c.type}" } * ', '
          "#{super}(#{attr_list})"
1389 1390
        else
          "#{super}(Table doesn't exist)"
1391
        end
1392 1393
      end

1394 1395

      def quote_value(value, column = nil) #:nodoc:
1396
        connection.quote(value,column)
1397 1398
      end

1399
      # Used to sanitize objects before they're used in an SQL SELECT statement. Delegates to <tt>connection.quote</tt>.
1400
      def sanitize(object) #:nodoc:
1401
        connection.quote(object)
D
Initial  
David Heinemeier Hansson 已提交
1402 1403
      end

1404
      # Log and benchmark multiple statements in a single block. Example:
D
Initial  
David Heinemeier Hansson 已提交
1405 1406 1407 1408
      #
      #   Project.benchmark("Creating project") do
      #     project = Project.create("name" => "stuff")
      #     project.create_manager("name" => "David")
1409
      #     project.milestones << Milestone.find(:all)
D
Initial  
David Heinemeier Hansson 已提交
1410
      #   end
1411
      #
1412 1413 1414
      # The benchmark is only recorded if the current level of the logger is less than or equal to the <tt>log_level</tt>,
      # which makes it easy to include benchmarking statements in production software that will remain inexpensive because
      # the benchmark will only be conducted if the log level is low enough.
1415
      #
1416
      # The logging of the multiple statements is turned off unless <tt>use_silence</tt> is set to false.
1417
      def benchmark(title, log_level = Logger::DEBUG, use_silence = true)
1418
        if logger && logger.level <= log_level
1419
          result = nil
J
Jeremy Kemper 已提交
1420 1421
          ms = Benchmark.ms { result = use_silence ? silence { yield } : yield }
          logger.add(log_level, '%s (%.1fms)' % [title, ms])
1422 1423 1424 1425
          result
        else
          yield
        end
1426
      end
1427

1428 1429
      # Silences the logger for the duration of the block.
      def silence
1430 1431 1432
        old_logger_level, logger.level = logger.level, Logger::ERROR if logger
        yield
      ensure
1433
        logger.level = old_logger_level if logger
D
Initial  
David Heinemeier Hansson 已提交
1434
      end
1435

1436 1437 1438
      # Overwrite the default class equality method to provide support for association proxies.
      def ===(object)
        object.is_a?(self)
1439
      end
1440

1441 1442 1443 1444 1445 1446 1447
      # Returns the base AR subclass that this class descends from. If A
      # extends AR::Base, A.base_class will return A. If B descends from A
      # through some arbitrarily deep hierarchy, B.base_class will return A.
      def base_class
        class_of_active_record_descendant(self)
      end

P
Pratik Naik 已提交
1448
      # Set this to true if this is an abstract class (see <tt>abstract_class?</tt>).
1449 1450 1451 1452 1453
      attr_accessor :abstract_class

      # Returns whether this class is a base AR class.  If A is a base class and
      # B descends from A, then B.base_class will return B.
      def abstract_class?
1454
        defined?(@abstract_class) && @abstract_class == true
1455 1456
      end

1457
      def respond_to?(method_id, include_private = false)
1458 1459
        if match = DynamicFinderMatch.match(method_id)
          return true if all_attributes_exists?(match.attribute_names)
1460 1461 1462 1463
        end
        super
      end

1464 1465 1466 1467
      def sti_name
        store_full_sti_class ? name : name.demodulize
      end

1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481
      # Merges conditions so that the result is a valid +condition+
      def merge_conditions(*conditions)
        segments = []

        conditions.each do |condition|
          unless condition.blank?
            sql = sanitize_sql(condition)
            segments << sql unless sql.blank?
          end
        end

        "(#{segments.join(') AND (')})" unless segments.empty?
      end

D
Initial  
David Heinemeier Hansson 已提交
1482
      private
1483
        def find_initial(options)
1484
          options.update(:limit => 1)
1485 1486
          find_every(options).first
        end
1487

1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500
        def find_last(options)
          order = options[:order]

          if order
            order = reverse_sql_order(order)
          elsif !scoped?(:find, :order)
            order = "#{table_name}.#{primary_key} DESC"
          end

          if scoped?(:find, :order)
            scoped_order = reverse_sql_order(scope(:find, :order))
            scoped_methods.select { |s| s[:find].update(:order => scoped_order) }
          end
1501

1502 1503 1504 1505 1506 1507 1508 1509 1510
          find_initial(options.merge({ :order => order }))
        end

        def reverse_sql_order(order_query)
          reversed_query = order_query.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')
1511
            elsif !s.match(/\s(asc|ASC|desc|DESC)$/)
1512 1513 1514 1515
              s.concat(' DESC')
            end
          }.join(',')
        end
1516

1517
        def find_every(options)
1518 1519 1520 1521 1522 1523 1524 1525 1526 1527
          include_associations = merge_includes(scope(:find, :include), options[:include])

          if include_associations.any? && references_eager_loaded_tables?(options)
            records = find_with_associations(options)
          else
            records = find_by_sql(construct_finder_sql(options))
            if include_associations.any?
              preload_associations(records, include_associations)
            end
          end
1528 1529 1530 1531 1532

          records.each { |record| record.readonly! } if options[:readonly]

          records
        end
1533

1534
        def find_from_ids(ids, options)
1535
          expects_array = ids.first.kind_of?(Array)
1536
          return ids.first if expects_array && ids.first.empty?
1537

1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549
          ids = ids.flatten.compact.uniq

          case ids.size
            when 0
              raise RecordNotFound, "Couldn't find #{name} without an ID"
            when 1
              result = find_one(ids.first, options)
              expects_array ? [ result ] : result
            else
              find_some(ids, options)
          end
        end
1550

1551 1552
        def find_one(id, options)
          conditions = " AND (#{sanitize_sql(options[:conditions])})" if options[:conditions]
1553
          options.update :conditions => "#{quoted_table_name}.#{connection.quote_column_name(primary_key)} = #{quote_value(id,columns_hash[primary_key])}#{conditions}"
1554

1555 1556 1557 1558
          # Use find_every(options).first since the primary key condition
          # already ensures we have a single record. Using find_initial adds
          # a superfluous :limit => 1.
          if result = find_every(options).first
1559 1560 1561 1562 1563
            result
          else
            raise RecordNotFound, "Couldn't find #{name} with ID=#{id}#{conditions}"
          end
        end
1564

1565 1566
        def find_some(ids, options)
          conditions = " AND (#{sanitize_sql(options[:conditions])})" if options[:conditions]
1567
          ids_list   = ids.map { |id| quote_value(id,columns_hash[primary_key]) }.join(',')
1568
          options.update :conditions => "#{quoted_table_name}.#{connection.quote_column_name(primary_key)} IN (#{ids_list})#{conditions}"
1569 1570 1571

          result = find_every(options)

1572
          # Determine expected size from limit and offset, not just ids.size.
1573 1574 1575 1576 1577 1578
          expected_size =
            if options[:limit] && ids.size > options[:limit]
              options[:limit]
            else
              ids.size
            end
1579 1580 1581 1582 1583

          # 11 ids with limit 3, offset 9 should give 2 results.
          if options[:offset] && (ids.size - options[:offset] < expected_size)
            expected_size = ids.size - options[:offset]
          end
1584 1585

          if result.size == expected_size
1586 1587
            result
          else
1588
            raise RecordNotFound, "Couldn't find all #{name.pluralize} with IDs (#{ids_list})#{conditions} (found #{result.size} results, but was looking for #{expected_size})"
1589 1590 1591
          end
        end

1592 1593 1594
        # Finder methods must instantiate through this method to work with the
        # single-table inheritance model that makes it possible to create
        # objects of different types from the same table.
D
Initial  
David Heinemeier Hansson 已提交
1595
        def instantiate(record)
1596
          object =
1597
            if subclass_name = record[inheritance_column]
1598
              # No type given.
1599 1600
              if subclass_name.empty?
                allocate
1601

1602
              else
1603 1604
                # Ignore type if no column is present since it was probably
                # pulled in from a sloppy join.
1605
                unless columns_hash.include?(inheritance_column)
1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617
                  allocate

                else
                  begin
                    compute_type(subclass_name).allocate
                  rescue NameError
                    raise SubclassNotFound,
                      "The single-table inheritance mechanism failed to locate the subclass: '#{record[inheritance_column]}'. " +
                      "This error is raised because the column '#{inheritance_column}' is reserved for storing the class in case of inheritance. " +
                      "Please rename this column if you didn't intend it to be used for storing the inheritance class " +
                      "or overwrite #{self.to_s}.inheritance_column to use another column for that information."
                  end
1618 1619 1620 1621
                end
              end
            else
              allocate
1622
            end
1623

D
Initial  
David Heinemeier Hansson 已提交
1624
          object.instance_variable_set("@attributes", record)
1625
          object.instance_variable_set("@attributes_cache", Hash.new)
1626 1627 1628 1629 1630 1631 1632 1633 1634

          if object.respond_to_without_attributes?(:after_find)
            object.send(:callback, :after_find)
          end

          if object.respond_to_without_attributes?(:after_initialize)
            object.send(:callback, :after_initialize)
          end

1635
          object
D
Initial  
David Heinemeier Hansson 已提交
1636
        end
1637

1638 1639
        # Nest the type name in the same module as this class.
        # Bar is "MyApp::Business::Bar" relative to MyApp::Business::Foo
D
Initial  
David Heinemeier Hansson 已提交
1640
        def type_name_with_module(type_name)
1641 1642 1643 1644 1645
          if store_full_sti_class
            type_name
          else
            (/^::/ =~ type_name) ? type_name : "#{parent.name}::#{type_name}"
          end
D
Initial  
David Heinemeier Hansson 已提交
1646 1647
        end

1648 1649 1650 1651 1652 1653 1654 1655
        def default_select(qualified)
          if qualified
            quoted_table_name + '.*'
          else
            '*'
          end
        end

1656
        def construct_finder_sql(options)
1657
          scope = scope(:find)
1658
          sql  = "SELECT #{options[:select] || (scope && scope[:select]) || default_select(options[:joins] || (scope && scope[:joins]))} "
1659
          sql << "FROM #{(scope && scope[:from]) || options[:from] || quoted_table_name} "
1660

1661
          add_joins!(sql, options[:joins], scope)
1662
          add_conditions!(sql, options[:conditions], scope)
1663

1664
          add_group!(sql, options[:group], options[:having], scope)
1665
          add_order!(sql, options[:order], scope)
1666
          add_limit!(sql, options, scope)
1667
          add_lock!(sql, options, scope)
1668

1669
          sql
1670
        end
1671

1672 1673
        # Merges includes so that the result is a valid +include+
        def merge_includes(first, second)
1674
         (safe_to_array(first) + safe_to_array(second)).uniq
1675 1676
        end

1677 1678 1679 1680 1681 1682 1683 1684 1685
        def merge_joins(*joins)
          if joins.any?{|j| j.is_a?(String) || array_of_strings?(j) }
            joins = joins.collect do |join|
              join = [join] if join.is_a?(String)
              unless array_of_strings?(join)
                join_dependency = ActiveRecord::Associations::ClassMethods::InnerJoinDependency.new(self, join, nil)
                join = join_dependency.join_associations.collect { |assoc| assoc.association_join }
              end
              join
1686
            end
1687
            joins.flatten.uniq
1688
          else
1689
            joins.collect{|j| safe_to_array(j)}.flatten.uniq
1690 1691 1692
          end
        end

1693
        # Object#to_a is deprecated, though it does have the desired behavior
1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704
        def safe_to_array(o)
          case o
          when NilClass
            []
          when Array
            o
          else
            [o]
          end
        end

1705 1706 1707 1708
        def array_of_strings?(o)
          o.is_a?(Array) && o.all?{|obj| obj.is_a?(String)}
        end

1709 1710 1711
        def add_order!(sql, order, scope = :auto)
          scope = scope(:find) if :auto == scope
          scoped_order = scope[:order] if scope
1712 1713
          if order
            sql << " ORDER BY #{order}"
1714
            sql << ", #{scoped_order}" if scoped_order
1715
          else
1716
            sql << " ORDER BY #{scoped_order}" if scoped_order
1717 1718
          end
        end
1719

1720
        def add_group!(sql, group, having, scope = :auto)
1721 1722
          if group
            sql << " GROUP BY #{group}"
1723
            sql << " HAVING #{having}" if having
1724 1725 1726 1727
          else
            scope = scope(:find) if :auto == scope
            if scope && (scoped_group = scope[:group])
              sql << " GROUP BY #{scoped_group}"
1728
              sql << " HAVING #{scoped_having}" if (scoped_having = scope[:having])
1729 1730
            end
          end
1731
        end
1732

1733
        # The optional scope argument is for the current <tt>:find</tt> scope.
1734 1735
        def add_limit!(sql, options, scope = :auto)
          scope = scope(:find) if :auto == scope
1736 1737 1738 1739 1740 1741

          if scope
            options[:limit] ||= scope[:limit]
            options[:offset] ||= scope[:offset]
          end

1742
          connection.add_limit_offset!(sql, options)
1743
        end
1744

1745 1746
        # The optional scope argument is for the current <tt>:find</tt> scope.
        # The <tt>:lock</tt> option has precedence over a scoped <tt>:lock</tt>.
1747
        def add_lock!(sql, options, scope = :auto)
1748
          scope = scope(:find) if :auto == scope
1749 1750 1751 1752
          options = options.reverse_merge(:lock => scope[:lock]) if scope
          connection.add_lock!(sql, options)
        end

1753
        # The optional scope argument is for the current <tt>:find</tt> scope.
1754
        def add_joins!(sql, joins, scope = :auto)
1755
          scope = scope(:find) if :auto == scope
1756 1757 1758
          merged_joins = scope && scope[:joins] && joins ? merge_joins(scope[:joins], joins) : (joins || scope && scope[:joins])
          case merged_joins
          when Symbol, Hash, Array
1759 1760 1761 1762 1763 1764
            if array_of_strings?(merged_joins)
              sql << merged_joins.join(' ') + " "
            else
              join_dependency = ActiveRecord::Associations::ClassMethods::InnerJoinDependency.new(self, merged_joins, nil)
              sql << " #{join_dependency.join_associations.collect { |assoc| assoc.association_join }.join} "
            end
1765 1766
          when String
            sql << " #{merged_joins} "
1767
          end
1768
        end
1769

1770
        # Adds a sanitized version of +conditions+ to the +sql+ string. Note that the passed-in +sql+ string is changed.
1771
        # The optional scope argument is for the current <tt>:find</tt> scope.
1772 1773
        def add_conditions!(sql, conditions, scope = :auto)
          scope = scope(:find) if :auto == scope
1774 1775 1776 1777 1778
          conditions = [conditions]
          conditions << scope[:conditions] if scope
          conditions << type_condition if finder_needs_type_condition?
          merged_conditions = merge_conditions(*conditions)
          sql << "WHERE #{merged_conditions} " unless merged_conditions.blank?
D
Initial  
David Heinemeier Hansson 已提交
1779
        end
1780

1781 1782
        def type_condition(table_alias=nil)
          quoted_table_alias = self.connection.quote_table_name(table_alias || table_name)
1783
          quoted_inheritance_column = connection.quote_column_name(inheritance_column)
1784 1785
          type_condition = subclasses.inject("#{quoted_table_alias}.#{quoted_inheritance_column} = '#{sti_name}' ") do |condition, subclass|
            condition << "OR #{quoted_table_alias}.#{quoted_inheritance_column} = '#{subclass.sti_name}' "
1786
          end
1787 1788

          " (#{type_condition}) "
D
Initial  
David Heinemeier Hansson 已提交
1789 1790 1791
        end

        # Guesses the table name, but does not decorate it with prefix and suffix information.
1792
        def undecorated_table_name(class_name = base_class.name)
1793 1794
          table_name = class_name.to_s.demodulize.underscore
          table_name = table_name.pluralize if pluralize_table_names
1795
          table_name
D
Initial  
David Heinemeier Hansson 已提交
1796 1797
        end

1798 1799
        # 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, :conditions => ["user_name = ?", user_name]) and  find(:first, :conditions => ["user_name = ? AND password = ?", user_name, password])
1800
        # respectively. Also works for find(:all) by using find_all_by_amount(50) that is turned into find(:all, :conditions => ["amount = ?", 50]).
1801
        #
1802 1803
        # It's even possible to use all the additional parameters to find. For example, the full interface for find_all_by_amount
        # is actually find_all_by_amount(amount, options).
1804
        #
1805
        # This also enables you to initialize a record if it is not found, such as find_or_initialize_by_amount(amount)
1806
        # or find_or_create_by_user_and_password(user, password).
1807 1808 1809
        #
        # Each dynamic finder or initializer/creator is also defined in the class after it is first invoked, so that future
        # attempts to use it do not run through method_missing.
1810
        def method_missing(method_id, *arguments, &block)
1811 1812
          if match = DynamicFinderMatch.match(method_id)
            attribute_names = match.attribute_names
1813
            super unless all_attributes_exists?(attribute_names)
1814 1815
            if match.finder?
              finder = match.finder
1816
              bang = match.bang?
1817 1818 1819 1820 1821 1822 1823 1824
              self.class_eval %{
                def self.#{method_id}(*args)
                  options = args.extract_options!
                  attributes = construct_attributes_from_arguments([:#{attribute_names.join(',:')}], args)
                  finder_options = { :conditions => attributes }
                  validate_find_options(options)
                  set_readonly_option!(options)

1825
                  #{'result = ' if bang}if options[:conditions]
1826
                    with_scope(:find => finder_options) do
1827
                      find(:#{finder}, options)
1828 1829
                    end
                  else
1830
                    find(:#{finder}, options.merge(finder_options))
1831
                  end
1832
                  #{'result || raise(RecordNotFound)' if bang}
1833
                end
1834 1835 1836 1837 1838 1839 1840 1841 1842 1843 1844 1845 1846 1847 1848
              }, __FILE__, __LINE__
              send(method_id, *arguments)
            elsif match.instantiator?
              instantiator = match.instantiator
              self.class_eval %{
                def self.#{method_id}(*args)
                  guard_protected_attributes = false

                  if args[0].is_a?(Hash)
                    guard_protected_attributes = true
                    attributes = args[0].with_indifferent_access
                    find_attributes = attributes.slice(*[:#{attribute_names.join(',:')}])
                  else
                    find_attributes = attributes = construct_attributes_from_arguments([:#{attribute_names.join(',:')}], args)
                  end
1849

1850 1851
                  options = { :conditions => find_attributes }
                  set_readonly_option!(options)
1852

1853
                  record = find(:first, options)
1854

1855
                  if record.nil?
1856 1857 1858 1859 1860 1861 1862
                    record = self.new { |r| r.send(:attributes=, attributes, guard_protected_attributes) }
                    #{'yield(record) if block_given?'}
                    #{'record.save' if instantiator == :create}
                    record
                  else
                    record
                  end
1863
                end
1864
              }, __FILE__, __LINE__
1865
              send(method_id, *arguments, &block)
1866
            end
1867 1868 1869 1870
          else
            super
          end
        end
D
Initial  
David Heinemeier Hansson 已提交
1871

1872 1873 1874 1875 1876 1877
        def construct_attributes_from_arguments(attribute_names, arguments)
          attributes = {}
          attribute_names.each_with_index { |name, idx| attributes[name] = arguments[idx] }
          attributes
        end

1878 1879 1880 1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891 1892
        # Similar in purpose to +expand_hash_conditions_for_aggregates+.
        def expand_attribute_names_for_aggregates(attribute_names)
          expanded_attribute_names = []
          attribute_names.each do |attribute_name|
            unless (aggregation = reflect_on_aggregation(attribute_name.to_sym)).nil?
              aggregate_mapping(aggregation).each do |field_attr, aggregate_attr|
                expanded_attribute_names << field_attr
              end
            else
              expanded_attribute_names << attribute_name
            end
          end
          expanded_attribute_names
        end

1893
        def all_attributes_exists?(attribute_names)
1894
          attribute_names = expand_attribute_names_for_aggregates(attribute_names)
1895
          attribute_names.all? { |name| column_methods_hash.include?(name.to_sym) }
1896
        end
1897

1898 1899 1900
        def attribute_condition(argument)
          case argument
            when nil   then "IS ?"
1901
            when Array, ActiveRecord::Associations::AssociationCollection, ActiveRecord::NamedScope::Scope then "IN (?)"
1902
            when Range then "BETWEEN ? AND ?"
1903 1904 1905 1906
            else            "= ?"
          end
        end

1907 1908 1909 1910
        # Interpret Array and Hash as conditions and anything else as an id.
        def expand_id_conditions(id_or_conditions)
          case id_or_conditions
            when Array, Hash then id_or_conditions
1911
            else sanitize_sql(primary_key => id_or_conditions)
1912 1913 1914 1915
          end
        end


P
Pratik Naik 已提交
1916 1917
        # Defines an "attribute" method (like +inheritance_column+ or
        # +table_name+). A new (class) method will be created with the
1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931 1932 1933 1934 1935
        # given name. If a value is specified, the new method will
        # return that value (as a string). Otherwise, the given block
        # will be used to compute the value of the method.
        #
        # The original method will be aliased, with the new name being
        # prefixed with "original_". This allows the new method to
        # access the original value.
        #
        # Example:
        #
        #   class A < ActiveRecord::Base
        #     define_attr_method :primary_key, "sysid"
        #     define_attr_method( :inheritance_column ) do
        #       original_inheritance_column + "_id"
        #     end
        #   end
        def define_attr_method(name, value=nil, &block)
          sing = class << self; self; end
1936
          sing.send :alias_method, "original_#{name}", name
1937 1938 1939
          if block_given?
            sing.send :define_method, name, &block
          else
1940 1941 1942 1943
            # use eval instead of a block to work around a memory leak in dev
            # mode in fcgi
            sing.class_eval "def #{name}; #{value.to_s.inspect}; end"
          end
1944 1945
        end

D
Initial  
David Heinemeier Hansson 已提交
1946
      protected
1947
        # Scope parameters to method calls within the block.  Takes a hash of method_name => parameters hash.
1948 1949
        # method_name may be <tt>:find</tt> or <tt>:create</tt>. <tt>:find</tt> parameters may include the <tt>:conditions</tt>, <tt>:joins</tt>,
        # <tt>:include</tt>, <tt>:offset</tt>, <tt>:limit</tt>, and <tt>:readonly</tt> options. <tt>:create</tt> parameters are an attributes hash.
1950 1951 1952 1953 1954 1955 1956 1957 1958 1959 1960
        #
        #   class Article < ActiveRecord::Base
        #     def self.create_with_scope
        #       with_scope(:find => { :conditions => "blog_id = 1" }, :create => { :blog_id => 1 }) do
        #         find(1) # => SELECT * from articles WHERE blog_id = 1 AND id = 1
        #         a = create(1)
        #         a.blog_id # => 1
        #       end
        #     end
        #   end
        #
D
David Heinemeier Hansson 已提交
1961
        # In nested scopings, all previous parameters are overwritten by the innermost rule, with the exception of
1962
        # <tt>:conditions</tt> and <tt>:include</tt> options in <tt>:find</tt>, which are merged.
1963 1964 1965 1966
        #
        #   class Article < ActiveRecord::Base
        #     def self.find_with_scope
        #       with_scope(:find => { :conditions => "blog_id = 1", :limit => 1 }, :create => { :blog_id => 1 }) do
P
Pratik Naik 已提交
1967
        #         with_scope(:find => { :limit => 10 })
1968 1969 1970 1971 1972 1973 1974 1975 1976
        #           find(:all) # => SELECT * from articles WHERE blog_id = 1 LIMIT 10
        #         end
        #         with_scope(:find => { :conditions => "author_id = 3" })
        #           find(:all) # => SELECT * from articles WHERE blog_id = 1 AND author_id = 3 LIMIT 1
        #         end
        #       end
        #     end
        #   end
        #
1977
        # You can ignore any previous scopings by using the <tt>with_exclusive_scope</tt> method.
1978 1979 1980 1981 1982 1983 1984 1985 1986 1987
        #
        #   class Article < ActiveRecord::Base
        #     def self.find_with_exclusive_scope
        #       with_scope(:find => { :conditions => "blog_id = 1", :limit => 1 }) do
        #         with_exclusive_scope(:find => { :limit => 10 })
        #           find(:all) # => SELECT * from articles LIMIT 10
        #         end
        #       end
        #     end
        #   end
P
Pratik Naik 已提交
1988 1989 1990
        #
        # *Note*: the +:find+ scope also has effect on update and deletion methods,
        # like +update_all+ and +delete_all+.
1991 1992 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002
        def with_scope(method_scoping = {}, action = :merge, &block)
          method_scoping = method_scoping.method_scoping if method_scoping.respond_to?(:method_scoping)

          # Dup first and second level of hash (method and params).
          method_scoping = method_scoping.inject({}) do |hash, (method, params)|
            hash[method] = (params == true) ? params : params.dup
            hash
          end

          method_scoping.assert_valid_keys([ :find, :create ])

          if f = method_scoping[:find]
2003
            f.assert_valid_keys(VALID_FIND_OPTIONS)
2004 2005 2006 2007 2008 2009 2010 2011 2012 2013 2014 2015
            set_readonly_option! f
          end

          # Merge scopings
          if action == :merge && current_scoped_methods
            method_scoping = current_scoped_methods.inject(method_scoping) do |hash, (method, params)|
              case hash[method]
                when Hash
                  if method == :find
                    (hash[method].keys + params.keys).uniq.each do |key|
                      merge = hash[method][key] && params[key] # merge if both scopes have the same key
                      if key == :conditions && merge
2016
                        hash[method][key] = merge_conditions(params[key], hash[method][key])
2017
                      elsif key == :include && merge
2018
                        hash[method][key] = merge_includes(hash[method][key], params[key]).uniq
2019 2020
                      elsif key == :joins && merge
                        hash[method][key] = merge_joins(params[key], hash[method][key])
2021 2022 2023 2024 2025 2026 2027 2028 2029 2030 2031 2032 2033 2034 2035 2036 2037 2038 2039 2040 2041 2042 2043 2044 2045 2046 2047 2048
                      else
                        hash[method][key] = hash[method][key] || params[key]
                      end
                    end
                  else
                    hash[method] = params.merge(hash[method])
                  end
                else
                  hash[method] = params
              end
              hash
            end
          end

          self.scoped_methods << method_scoping

          begin
            yield
          ensure
            self.scoped_methods.pop
          end
        end

        # Works like with_scope, but discards any nested properties.
        def with_exclusive_scope(method_scoping = {}, &block)
          with_scope(method_scoping, :overwrite, &block)
        end

D
David Heinemeier Hansson 已提交
2049
        def subclasses #:nodoc:
D
Initial  
David Heinemeier Hansson 已提交
2050 2051 2052
          @@subclasses[self] ||= []
          @@subclasses[self] + extra = @@subclasses[self].inject([]) {|list, subclass| list + subclass.subclasses }
        end
2053

2054 2055 2056 2057 2058 2059 2060
        # Sets the default options for the model. The format of the
        # <tt>method_scoping</tt> argument is the same as in with_scope.
        #
        #   class Person < ActiveRecord::Base
        #     default_scope :find => { :order => 'last_name, first_name' }
        #   end
        def default_scope(options = {})
2061
          self.default_scoping << { :find => options, :create => (options.is_a?(Hash) && options.has_key?(:conditions)) ? options[:conditions] : {} }
2062 2063
        end

2064
        # Test whether the given method and optional key are scoped.
D
David Heinemeier Hansson 已提交
2065
        def scoped?(method, key = nil) #:nodoc:
2066 2067 2068
          if current_scoped_methods && (scope = current_scoped_methods[method])
            !key || scope.has_key?(key)
          end
2069 2070 2071
        end

        # Retrieve the scope for the given method and optional key.
D
David Heinemeier Hansson 已提交
2072
        def scope(method, key = nil) #:nodoc:
2073
          if current_scoped_methods && (scope = current_scoped_methods[method])
2074 2075 2076 2077
            key ? scope[key] : scope
          end
        end

2078
        def scoped_methods #:nodoc:
2079
          Thread.current[:"#{self}_scoped_methods"] ||= self.default_scoping.dup
2080
        end
2081

D
David Heinemeier Hansson 已提交
2082
        def current_scoped_methods #:nodoc:
2083
          scoped_methods.last
2084
        end
2085

2086 2087
        # Returns the class type of the record using the current module as a prefix. So descendents of
        # MyApp::Business::Account would appear as MyApp::Business::AccountSubclass.
D
Initial  
David Heinemeier Hansson 已提交
2088
        def compute_type(type_name)
2089
          modularized_name = type_name_with_module(type_name)
2090 2091 2092 2093 2094 2095
          silence_warnings do
            begin
              class_eval(modularized_name, __FILE__, __LINE__)
            rescue NameError
              class_eval(type_name, __FILE__, __LINE__)
            end
D
Initial  
David Heinemeier Hansson 已提交
2096 2097 2098
          end
        end

P
Pratik Naik 已提交
2099
        # Returns the class descending directly from Active Record in the inheritance hierarchy.
2100
        def class_of_active_record_descendant(klass)
2101
          if klass.superclass == Base || klass.superclass.abstract_class?
2102
            klass
D
Initial  
David Heinemeier Hansson 已提交
2103 2104 2105
          elsif klass.superclass.nil?
            raise ActiveRecordError, "#{name} doesn't belong in a hierarchy descending from ActiveRecord"
          else
2106
            class_of_active_record_descendant(klass.superclass)
D
Initial  
David Heinemeier Hansson 已提交
2107 2108 2109
          end
        end

P
Pratik Naik 已提交
2110
        # Returns the name of the class descending directly from Active Record in the inheritance hierarchy.
D
David Heinemeier Hansson 已提交
2111
        def class_name_of_active_record_descendant(klass) #:nodoc:
2112
          klass.base_class.name
2113 2114
        end

P
Pratik Naik 已提交
2115
        # Accepts an array, hash, or string of SQL conditions and sanitizes
2116
        # them into a valid SQL fragment for a WHERE clause.
2117 2118 2119
        #   ["name='%s' and group_id='%s'", "foo'bar", 4]  returns  "name='foo''bar' and group_id='4'"
        #   { :name => "foo'bar", :group_id => 4 }  returns "name='foo''bar' and group_id='4'"
        #   "name='foo''bar' and group_id='4'" returns "name='foo''bar' and group_id='4'"
2120
        def sanitize_sql_for_conditions(condition)
2121 2122
          return nil if condition.blank?

2123 2124
          case condition
            when Array; sanitize_sql_array(condition)
2125
            when Hash;  sanitize_sql_hash_for_conditions(condition)
2126 2127
            else        condition
          end
2128
        end
2129
        alias_method :sanitize_sql, :sanitize_sql_for_conditions
2130

P
Pratik Naik 已提交
2131
        # Accepts an array, hash, or string of SQL conditions and sanitizes
2132 2133 2134 2135 2136 2137 2138 2139 2140 2141
        # them into a valid SQL fragment for a SET clause.
        #   { :name => nil, :group_id => 4 }  returns "name = NULL , group_id='4'"
        def sanitize_sql_for_assignment(assignments)
          case assignments
            when Array; sanitize_sql_array(assignments)
            when Hash;  sanitize_sql_hash_for_assignment(assignments)
            else        assignments
          end
        end

2142 2143 2144 2145 2146
        def aggregate_mapping(reflection)
          mapping = reflection.options[:mapping] || [reflection.name, reflection.name]
          mapping.first.is_a?(Array) ? mapping : [mapping]
        end

P
Pratik Naik 已提交
2147
        # Accepts a hash of SQL conditions and replaces those attributes
2148 2149 2150 2151 2152 2153 2154 2155 2156 2157 2158 2159 2160 2161 2162 2163 2164 2165 2166 2167 2168 2169 2170 2171 2172 2173 2174 2175 2176
        # that correspond to a +composed_of+ relationship with their expanded
        # aggregate attribute values.
        # Given:
        #     class Person < ActiveRecord::Base
        #       composed_of :address, :class_name => "Address",
        #         :mapping => [%w(address_street street), %w(address_city city)]
        #     end
        # Then:
        #     { :address => Address.new("813 abc st.", "chicago") }
        #       # => { :address_street => "813 abc st.", :address_city => "chicago" }
        def expand_hash_conditions_for_aggregates(attrs)
          expanded_attrs = {}
          attrs.each do |attr, value|
            unless (aggregation = reflect_on_aggregation(attr.to_sym)).nil?
              mapping = aggregate_mapping(aggregation)
              mapping.each do |field_attr, aggregate_attr|
                if mapping.size == 1 && !value.respond_to?(aggregate_attr)
                  expanded_attrs[field_attr] = value
                else
                  expanded_attrs[field_attr] = value.send(aggregate_attr)
                end
              end
            else
              expanded_attrs[attr] = value
            end
          end
          expanded_attrs
        end

2177
        # Sanitizes a hash of attribute/value pairs into SQL conditions for a WHERE clause.
2178 2179 2180 2181
        #   { :name => "foo'bar", :group_id => 4 }
        #     # => "name='foo''bar' and group_id= 4"
        #   { :status => nil, :group_id => [1,2,3] }
        #     # => "status IS NULL and group_id IN (1,2,3)"
2182 2183
        #   { :age => 13..18 }
        #     # => "age BETWEEN 13 AND 18"
2184 2185
        #   { 'other_records.id' => 7 }
        #     # => "`other_records`.`id` = 7"
2186 2187
        #   { :other_records => { :id => 7 } }
        #     # => "`other_records`.`id` = 7"
2188 2189 2190
        # And for value objects on a composed_of relationship:
        #   { :address => Address.new("123 abc st.", "chicago") }
        #     # => "address_street='123 abc st.' and address_city='chicago'"
2191
        def sanitize_sql_hash_for_conditions(attrs, table_name = quoted_table_name)
2192 2193
          attrs = expand_hash_conditions_for_aggregates(attrs)

2194
          conditions = attrs.map do |attr, value|
2195 2196 2197 2198 2199 2200 2201 2202
            unless value.is_a?(Hash)
              attr = attr.to_s

              # Extract table name from qualified attribute names.
              if attr.include?('.')
                table_name, attr = attr.split('.', 2)
                table_name = connection.quote_table_name(table_name)
              end
2203

2204
              "#{table_name}.#{connection.quote_column_name(attr)} #{attribute_condition(value)}"
2205
            else
2206
              sanitize_sql_hash_for_conditions(value, connection.quote_table_name(attr.to_s))
2207
            end
2208 2209
          end.join(' AND ')

2210
          replace_bind_variables(conditions, expand_range_bind_variables(attrs.values))
2211
        end
2212 2213 2214 2215 2216 2217
        alias_method :sanitize_sql_hash, :sanitize_sql_hash_for_conditions

        # Sanitizes a hash of attribute/value pairs into SQL conditions for a SET clause.
        #   { :status => nil, :group_id => 1 }
        #     # => "status = NULL , group_id = 1"
        def sanitize_sql_hash_for_assignment(attrs)
2218
          attrs.map do |attr, value|
2219 2220 2221
            "#{connection.quote_column_name(attr)} = #{quote_bound_value(value)}"
          end.join(', ')
        end
2222

2223
        # Accepts an array of conditions.  The array has each value
P
Pratik Naik 已提交
2224
        # sanitized and interpolated into the SQL statement.
2225
        #   ["name='%s' and group_id='%s'", "foo'bar", 4]  returns  "name='foo''bar' and group_id='4'"
2226
        def sanitize_sql_array(ary)
2227 2228 2229 2230
          statement, *values = ary
          if values.first.is_a?(Hash) and statement =~ /:\w+/
            replace_named_bind_variables(statement, values.first)
          elsif statement.include?('?')
2231 2232
            replace_bind_variables(statement, values)
          else
2233
            statement % values.collect { |value| connection.quote_string(value.to_s) }
2234
          end
2235 2236
        end

2237 2238
        alias_method :sanitize_conditions, :sanitize_sql

D
David Heinemeier Hansson 已提交
2239
        def replace_bind_variables(statement, values) #:nodoc:
2240
          raise_if_bind_arity_mismatch(statement, statement.count('?'), values.size)
2241
          bound = values.dup
2242
          statement.gsub('?') { quote_bound_value(bound.shift) }
2243 2244
        end

D
David Heinemeier Hansson 已提交
2245
        def replace_named_bind_variables(statement, bind_vars) #:nodoc:
2246 2247 2248 2249
          statement.gsub(/(:?):([a-zA-Z]\w*)/) do
            if $1 == ':' # skip postgresql casts
              $& # return the whole match
            elsif bind_vars.include?(match = $2.to_sym)
2250
              quote_bound_value(bind_vars[match])
2251 2252
            else
              raise PreparedStatementInvalid, "missing value for :#{match} in #{statement}"
2253 2254
            end
          end
2255 2256
        end

2257
        def expand_range_bind_variables(bind_vars) #:nodoc:
2258 2259 2260
          expanded = []

          bind_vars.each do |var|
2261 2262
            next if var.is_a?(Hash)

2263
            if var.is_a?(Range)
2264 2265
              expanded << var.first
              expanded << var.last
2266
            else
2267
              expanded << var
2268
            end
2269
          end
2270 2271

          expanded
2272 2273
        end

D
David Heinemeier Hansson 已提交
2274
        def quote_bound_value(value) #:nodoc:
2275
          if value.respond_to?(:map) && !value.acts_like?(:string)
2276 2277
            if value.respond_to?(:empty?) && value.empty?
              connection.quote(nil)
2278 2279 2280
            else
              value.map { |v| connection.quote(v) }.join(',')
            end
2281 2282
          else
            connection.quote(value)
2283 2284 2285
          end
        end

D
David Heinemeier Hansson 已提交
2286
        def raise_if_bind_arity_mismatch(statement, expected, provided) #:nodoc:
2287 2288 2289
          unless expected == provided
            raise PreparedStatementInvalid, "wrong number of bind variables (#{provided} for #{expected}) in: #{statement}"
          end
2290
        end
2291

2292
        VALID_FIND_OPTIONS = [ :conditions, :include, :joins, :limit, :offset,
2293
                               :order, :select, :readonly, :group, :having, :from, :lock ]
2294

D
David Heinemeier Hansson 已提交
2295
        def validate_find_options(options) #:nodoc:
2296 2297
          options.assert_valid_keys(VALID_FIND_OPTIONS)
        end
2298

D
David Heinemeier Hansson 已提交
2299
        def set_readonly_option!(options) #:nodoc:
2300 2301 2302
          # Inherit :readonly from finder scope if set.  Otherwise,
          # if :joins is not blank then :readonly defaults to true.
          unless options.has_key?(:readonly)
J
Jeremy Kemper 已提交
2303 2304
            if scoped_readonly = scope(:find, :readonly)
              options[:readonly] = scoped_readonly
2305
            elsif !options[:joins].blank? && !options[:select]
2306 2307 2308
              options[:readonly] = true
            end
          end
D
Initial  
David Heinemeier Hansson 已提交
2309
        end
2310

D
David Heinemeier Hansson 已提交
2311
        def encode_quoted_value(value) #:nodoc:
2312
          quoted_value = connection.quote(value)
2313 2314
          quoted_value = "'#{quoted_value[1..-2].gsub(/\'/, "\\\\'")}'" if quoted_value.include?("\\\'") # (for ruby mode) "
          quoted_value
2315
        end
D
Initial  
David Heinemeier Hansson 已提交
2316 2317 2318 2319 2320
    end

    public
      # New objects can be instantiated as either empty (pass no construction parameter) or pre-set with
      # attributes but not yet saved (pass a hash with key names matching the associated table column names).
2321
      # In both instances, valid attribute keys are determined by the column names of the associated table --
D
Initial  
David Heinemeier Hansson 已提交
2322 2323 2324
      # hence you can't have attributes that aren't part of the table columns.
      def initialize(attributes = nil)
        @attributes = attributes_from_column_definition
2325
        @attributes_cache = {}
D
Initial  
David Heinemeier Hansson 已提交
2326 2327 2328
        @new_record = true
        ensure_proper_type
        self.attributes = attributes unless attributes.nil?
2329
        self.class.send(:scope, :create).each { |att,value| self.send("#{att}=", value) } if self.class.send(:scoped?, :create)
2330 2331 2332
        result = yield self if block_given?
        callback(:after_initialize) if respond_to_without_attributes?(:after_initialize)
        result
D
Initial  
David Heinemeier Hansson 已提交
2333
      end
2334

2335 2336
      # A model instance's primary key is always available as model.id
      # whether you name it the default 'id' or set it to something else.
D
Initial  
David Heinemeier Hansson 已提交
2337
      def id
2338
        attr_name = self.class.primary_key
2339
        column = column_for_attribute(attr_name)
2340

2341 2342 2343 2344
        self.class.send(:define_read_method, :id, attr_name, column)
        # now that the method exists, call it
        self.send attr_name.to_sym

D
Initial  
David Heinemeier Hansson 已提交
2345
      end
2346

P
Pratik Naik 已提交
2347 2348 2349 2350
      # Returns a String, which Action Pack uses for constructing an URL to this
      # object. The default implementation returns this record's id as a String,
      # or nil if this record's unsaved.
      #
P
Pratik Naik 已提交
2351 2352 2353
      # For example, suppose that you have a User model, and that you have a
      # <tt>map.resources :users</tt> route. Normally, +user_path+ will
      # construct a path with the user object's 'id' in it:
P
Pratik Naik 已提交
2354 2355
      #
      #   user = User.find_by_name('Phusion')
2356
      #   user_path(user)  # => "/users/1"
P
Pratik Naik 已提交
2357
      #
P
Pratik Naik 已提交
2358 2359
      # You can override +to_param+ in your model to make +user_path+ construct
      # a path using the user's name instead of the user's id:
P
Pratik Naik 已提交
2360 2361 2362 2363 2364 2365 2366 2367
      #
      #   class User < ActiveRecord::Base
      #     def to_param  # overridden
      #       name
      #     end
      #   end
      #   
      #   user = User.find_by_name('Phusion')
2368
      #   user_path(user)  # => "/users/Phusion"
2369
      def to_param
2370
        # We can't use alias_method here, because method 'id' optimizes itself on the fly.
2371
        (id = self.id) ? id.to_s : nil # Be sure to stringify the id for routes
2372
      end
2373

P
Pratik Naik 已提交
2374 2375 2376
      # Returns a cache key that can be used to identify this record.
      #
      # ==== Examples
2377 2378 2379 2380 2381
      #
      #   Product.new.cache_key     # => "products/new"
      #   Product.find(5).cache_key # => "products/5" (updated_at not available)
      #   Person.find(5).cache_key  # => "people/5-20071224150000" (updated_at available)
      def cache_key
2382
        case
2383
        when new_record?
J
Jeremy Kemper 已提交
2384 2385 2386
          "#{self.class.model_name.cache_key}/new"
        when timestamp = self[:updated_at]
          "#{self.class.model_name.cache_key}/#{id}-#{timestamp.to_s(:number)}"
2387
        else
J
Jeremy Kemper 已提交
2388
          "#{self.class.model_name.cache_key}/#{id}"
2389 2390
        end
      end
2391

2392
      def id_before_type_cast #:nodoc:
2393 2394 2395
        read_attribute_before_type_cast(self.class.primary_key)
      end

2396
      def quoted_id #:nodoc:
2397
        quote_value(id, column_for_attribute(self.class.primary_key))
2398
      end
2399

D
Initial  
David Heinemeier Hansson 已提交
2400 2401 2402 2403
      # Sets the primary ID.
      def id=(value)
        write_attribute(self.class.primary_key, value)
      end
2404

D
Initial  
David Heinemeier Hansson 已提交
2405
      # Returns true if this object hasn't been saved yet -- that is, a record for the object doesn't exist yet.
2406
      def new_record?
2407
        defined?(@new_record) && @new_record
2408
      end
2409

P
Pratik Naik 已提交
2410 2411
      # :call-seq:
      #   save(perform_validation = true)
2412
      #
P
Pratik Naik 已提交
2413 2414 2415 2416 2417 2418 2419 2420 2421 2422 2423 2424 2425 2426
      # Saves the model.
      #
      # If the model is new a record gets created in the database, otherwise
      # the existing record gets updated.
      #
      # If +perform_validation+ is true validations run. If any of them fail
      # the action is cancelled and +save+ returns +false+. If the flag is
      # false validations are bypassed altogether. See
      # ActiveRecord::Validations for more information. 
      #
      # There's a series of callbacks associated with +save+. If any of the
      # <tt>before_*</tt> callbacks return +false+ the action is cancelled and
      # +save+ returns +false+. See ActiveRecord::Callbacks for further
      # details. 
D
Initial  
David Heinemeier Hansson 已提交
2427 2428 2429
      def save
        create_or_update
      end
2430

P
Pratik Naik 已提交
2431 2432 2433 2434 2435 2436 2437 2438 2439 2440 2441 2442 2443
      # Saves the model.
      #
      # If the model is new a record gets created in the database, otherwise
      # the existing record gets updated.
      #
      # With <tt>save!</tt> validations always run. If any of them fail
      # ActiveRecord::RecordInvalid gets raised. See ActiveRecord::Validations
      # for more information. 
      #
      # There's a series of callbacks associated with <tt>save!</tt>. If any of
      # the <tt>before_*</tt> callbacks return +false+ the action is cancelled
      # and <tt>save!</tt> raises ActiveRecord::RecordNotSaved. See
      # ActiveRecord::Callbacks for further details. 
2444
      def save!
2445
        create_or_update || raise(RecordNotSaved)
2446
      end
2447

2448 2449 2450 2451 2452
      # Deletes the record in the database and freezes this instance to reflect that no changes should
      # be made (since they can't be persisted).
      #
      # Unlike #destroy, this method doesn't run any +before_delete+ and +after_delete+
      # callbacks, nor will it enforce any association +:dependent+ rules.
P
Pratik Naik 已提交
2453 2454 2455
      # 
      # In addition to deleting this record, any defined +before_delete+ and +after_delete+
      # callbacks are run, and +:dependent+ rules defined on associations are run.
2456 2457 2458 2459 2460
      def delete
        self.class.delete(id) unless new_record?
        freeze
      end

D
Initial  
David Heinemeier Hansson 已提交
2461 2462 2463
      # Deletes the record in the database and freezes this instance to reflect that no changes should
      # be made (since they can't be persisted).
      def destroy
2464
        unless new_record?
2465 2466 2467 2468 2469
          connection.delete(
            "DELETE FROM #{self.class.quoted_table_name} " +
            "WHERE #{connection.quote_column_name(self.class.primary_key)} = #{quoted_id}",
            "#{self.class.name} Destroy"
          )
D
Initial  
David Heinemeier Hansson 已提交
2470 2471 2472 2473 2474
        end

        freeze
      end

J
Jeremy Kemper 已提交
2475 2476 2477 2478 2479
      # Returns a clone of the record that hasn't been assigned an id yet and
      # is treated as a new record.  Note that this is a "shallow" clone:
      # it copies the object's attributes only, not its associations.
      # The extent of a "deep" clone is application-specific and is therefore
      # left to the application to implement according to its need.
D
Initial  
David Heinemeier Hansson 已提交
2480
      def clone
2481
        attrs = clone_attributes(:read_attribute_before_type_cast)
D
David Heinemeier Hansson 已提交
2482
        attrs.delete(self.class.primary_key)
2483 2484 2485
        record = self.class.new
        record.send :instance_variable_set, '@attributes', attrs
        record
D
Initial  
David Heinemeier Hansson 已提交
2486
      end
2487

2488
      # Returns an instance of the specified +klass+ with the attributes of the current record. This is mostly useful in relation to
2489
      # single-table inheritance structures where you want a subclass to appear as the superclass. This can be used along with record
2490
      # identification in Action Pack to allow, say, <tt>Client < Company</tt> to do something like render <tt>:partial => @client.becomes(Company)</tt>
2491 2492 2493 2494 2495 2496 2497
      # to render that instance using the companies/company partial instead of clients/client.
      #
      # Note: The new instance will share a link to the same attributes as the original class. So any change to the attributes in either
      # instance will affect the other.
      def becomes(klass)
        returning klass.new do |became|
          became.instance_variable_set("@attributes", @attributes)
D
David Heinemeier Hansson 已提交
2498
          became.instance_variable_set("@attributes_cache", @attributes_cache)
2499 2500 2501 2502
          became.instance_variable_set("@new_record", new_record?)
        end
      end

2503 2504 2505
      # 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.
D
Initial  
David Heinemeier Hansson 已提交
2506
      def update_attribute(name, value)
2507
        send(name.to_s + '=', value)
2508
        save(false)
2509 2510
      end

2511
      # Updates all the attributes from the passed-in Hash and saves the record. If the object is invalid, the saving will
2512
      # fail and false will be returned.
2513
      def update_attributes(attributes)
2514
        self.attributes = attributes
2515
        save
D
Initial  
David Heinemeier Hansson 已提交
2516
      end
2517

2518 2519 2520 2521 2522
      # Updates an object just like Base.update_attributes but calls save! instead of save so an exception is raised if the record is invalid.
      def update_attributes!(attributes)
        self.attributes = attributes
        save!
      end
D
Initial  
David Heinemeier Hansson 已提交
2523

P
Pratik Naik 已提交
2524 2525 2526
      # Initializes +attribute+ to zero if +nil+ and adds the value passed as +by+ (default is 1).
      # The increment is performed directly on the underlying attribute, no setter is invoked.
      # Only makes sense for number-based attributes. Returns +self+.
2527
      def increment(attribute, by = 1)
2528
        self[attribute] ||= 0
2529
        self[attribute] += by
2530 2531
        self
      end
2532

P
Pratik Naik 已提交
2533 2534 2535 2536
      # Wrapper around +increment+ that saves the record. This method differs from
      # its non-bang version in that it passes through the attribute setter.
      # Saving is not subjected to validation checks. Returns +true+ if the
      # record could be saved.
2537 2538
      def increment!(attribute, by = 1)
        increment(attribute, by).update_attribute(attribute, self[attribute])
2539 2540
      end

P
Pratik Naik 已提交
2541 2542 2543
      # Initializes +attribute+ to zero if +nil+ and subtracts the value passed as +by+ (default is 1).
      # The decrement is performed directly on the underlying attribute, no setter is invoked.
      # Only makes sense for number-based attributes. Returns +self+.
2544
      def decrement(attribute, by = 1)
2545
        self[attribute] ||= 0
2546
        self[attribute] -= by
2547 2548 2549
        self
      end

P
Pratik Naik 已提交
2550 2551 2552 2553
      # Wrapper around +decrement+ that saves the record. This method differs from
      # its non-bang version in that it passes through the attribute setter.
      # Saving is not subjected to validation checks. Returns +true+ if the
      # record could be saved.
2554 2555
      def decrement!(attribute, by = 1)
        decrement(attribute, by).update_attribute(attribute, self[attribute])
2556
      end
2557

P
Pratik Naik 已提交
2558 2559 2560 2561
      # Assigns to +attribute+ the boolean opposite of <tt>attribute?</tt>. So
      # if the predicate returns +true+ the attribute will become +false+. This
      # method toggles directly the underlying value without calling any setter.
      # Returns +self+.
2562
      def toggle(attribute)
2563
        self[attribute] = !send("#{attribute}?")
2564 2565 2566
        self
      end

P
Pratik Naik 已提交
2567 2568 2569 2570
      # Wrapper around +toggle+ that saves the record. This method differs from
      # its non-bang version in that it passes through the attribute setter.
      # Saving is not subjected to validation checks. Returns +true+ if the
      # record could be saved.
2571 2572 2573 2574
      def toggle!(attribute)
        toggle(attribute).update_attribute(attribute, self[attribute])
      end

2575
      # Reloads the attributes of this object from the database.
2576 2577 2578 2579
      # The optional options argument is passed to find when reloading so you
      # may do e.g. record.reload(:lock => true) to reload the same record with
      # an exclusive row lock.
      def reload(options = nil)
2580
        clear_aggregation_cache
2581
        clear_association_cache
2582
        @attributes.update(self.class.find(self.id, options).instance_variable_get('@attributes'))
2583
        @attributes_cache = {}
2584
        self
2585 2586
      end

2587
      # Returns the value of the attribute identified by <tt>attr_name</tt> after it has been typecast (for example,
D
Initial  
David Heinemeier Hansson 已提交
2588 2589
      # "2004-12-12" in a data column is cast to a date object, like Date.new(2004, 12, 12)).
      # (Alias for the protected read_attribute method).
2590
      def [](attr_name)
2591
        read_attribute(attr_name)
D
Initial  
David Heinemeier Hansson 已提交
2592
      end
2593

D
Initial  
David Heinemeier Hansson 已提交
2594 2595
      # Updates the attribute identified by <tt>attr_name</tt> with the specified +value+.
      # (Alias for the protected write_attribute method).
2596
      def []=(attr_name, value)
2597
        write_attribute(attr_name, value)
D
Initial  
David Heinemeier Hansson 已提交
2598 2599 2600
      end

      # Allows you to set all the attributes at once by passing in a hash with keys
P
Pratik Naik 已提交
2601 2602 2603 2604 2605 2606
      # matching the attribute names (which again matches the column names).
      #
      # If +guard_protected_attributes+ is true (the default), then sensitive
      # attributes can be protected from this form of mass-assignment by using
      # the +attr_protected+ macro. Or you can alternatively specify which
      # attributes *can* be accessed with the +attr_accessible+ macro. Then all the
2607
      # attributes not included in that won't be allowed to be mass-assigned.
P
Pratik Naik 已提交
2608 2609 2610 2611 2612 2613 2614 2615 2616 2617 2618 2619
      #
      #   class User < ActiveRecord::Base
      #     attr_protected :is_admin
      #   end
      #   
      #   user = User.new
      #   user.attributes = { :username => 'Phusion', :is_admin => true }
      #   user.username   # => "Phusion"
      #   user.is_admin?  # => false
      #   
      #   user.send(:attributes=, { :username => 'Phusion', :is_admin => true }, false)
      #   user.is_admin?  # => true
2620
      def attributes=(new_attributes, guard_protected_attributes = true)
D
David Heinemeier Hansson 已提交
2621 2622
        return if new_attributes.nil?
        attributes = new_attributes.dup
2623
        attributes.stringify_keys!
D
Initial  
David Heinemeier Hansson 已提交
2624 2625

        multi_parameter_attributes = []
2626
        attributes = remove_attributes_protected_from_mass_assignment(attributes) if guard_protected_attributes
2627

2628
        attributes.each do |k, v|
2629 2630 2631 2632 2633
          if k.include?("(")
            multi_parameter_attributes << [ k, v ]
          else
            respond_to?(:"#{k}=") ? send(:"#{k}=", v) : raise(UnknownAttributeError, "unknown attribute: #{k}")
          end
D
Initial  
David Heinemeier Hansson 已提交
2634
        end
D
David Heinemeier Hansson 已提交
2635

D
Initial  
David Heinemeier Hansson 已提交
2636 2637 2638
        assign_multiparameter_attributes(multi_parameter_attributes)
      end

D
David Heinemeier Hansson 已提交
2639

2640
      # Returns a hash of all the attributes with their names as keys and the values of the attributes as values.
2641
      def attributes
2642 2643
        self.attribute_names.inject({}) do |attrs, name|
          attrs[name] = read_attribute(name)
2644
          attrs
2645
        end
2646 2647
      end

2648
      # Returns a hash of attributes before typecasting and deserialization.
2649
      def attributes_before_type_cast
2650
        self.attribute_names.inject({}) do |attrs, name|
2651
          attrs[name] = read_attribute_before_type_cast(name)
2652
          attrs
2653
        end
2654 2655
      end

2656 2657 2658 2659
      # Format attributes nicely for inspect.
      def attribute_for_inspect(attr_name)
        value = read_attribute(attr_name)

2660
        if value.is_a?(String) && value.length > 50
2661
          "#{value[0..50]}...".inspect
2662 2663
        elsif value.is_a?(Date) || value.is_a?(Time)
          %("#{value.to_s(:db)}")
2664 2665 2666 2667 2668
        else
          value.inspect
        end
      end

D
Initial  
David Heinemeier Hansson 已提交
2669
      # Returns true if the specified +attribute+ has been set by the user or by a database load and is neither
2670
      # nil nor empty? (the latter only applies to objects that respond to empty?, most notably Strings).
D
Initial  
David Heinemeier Hansson 已提交
2671
      def attribute_present?(attribute)
2672
        value = read_attribute(attribute)
2673
        !value.blank?
D
Initial  
David Heinemeier Hansson 已提交
2674 2675
      end

2676 2677 2678 2679 2680
      # Returns true if the given attribute is in the attributes hash
      def has_attribute?(attr_name)
        @attributes.has_key?(attr_name.to_s)
      end

D
Initial  
David Heinemeier Hansson 已提交
2681 2682 2683 2684 2685 2686 2687
      # Returns an array of names for the attributes available on this object sorted alphabetically.
      def attribute_names
        @attributes.keys.sort
      end

      # Returns the column object for the named attribute.
      def column_for_attribute(name)
2688
        self.class.columns_hash[name.to_s]
D
Initial  
David Heinemeier Hansson 已提交
2689
      end
2690

2691
      # Returns true if the +comparison_object+ is the same object, or is of the same type and has the same id.
D
Initial  
David Heinemeier Hansson 已提交
2692
      def ==(comparison_object)
2693
        comparison_object.equal?(self) ||
2694 2695
          (comparison_object.instance_of?(self.class) &&
            comparison_object.id == id &&
2696
            !comparison_object.new_record?)
D
Initial  
David Heinemeier Hansson 已提交
2697 2698 2699 2700 2701 2702
      end

      # Delegates to ==
      def eql?(comparison_object)
        self == (comparison_object)
      end
2703

D
Initial  
David Heinemeier Hansson 已提交
2704 2705 2706
      # Delegates to id in order to allow two records of the same type and id to work with something like:
      #   [ Person.find(1), Person.find(2), Person.find(3) ] & [ Person.find(1), Person.find(4) ] # => [ Person.find(1) ]
      def hash
2707
        id.hash
D
Initial  
David Heinemeier Hansson 已提交
2708 2709
      end

2710
      # Freeze the attributes hash such that associations are still accessible, even on destroyed records.
2711
      def freeze
2712
        @attributes.freeze; self
2713
      end
2714

2715
      # Returns +true+ if the attributes hash has been frozen.
2716 2717 2718
      def frozen?
        @attributes.frozen?
      end
2719

2720 2721
      # Returns +true+ if the record is read only. Records loaded through joins with piggy-back
      # attributes will be marked as read only since they cannot be saved.
2722
      def readonly?
2723
        defined?(@readonly) && @readonly == true
2724 2725
      end

2726 2727
      # Marks this record as read only.
      def readonly!
2728 2729
        @readonly = true
      end
2730

2731
      # Returns the contents of the record as a nicely formatted string.
2732
      def inspect
2733
        attributes_as_nice_string = self.class.column_names.collect { |name|
2734 2735 2736 2737
          if has_attribute?(name) || new_record?
            "#{name}: #{attribute_for_inspect(name)}"
          end
        }.compact.join(", ")
2738
        "#<#{self.class} #{attributes_as_nice_string}>"
2739
      end
2740

D
Initial  
David Heinemeier Hansson 已提交
2741 2742
    private
      def create_or_update
2743
        raise ReadOnlyRecord if readonly?
2744 2745
        result = new_record? ? create : update
        result != false
D
Initial  
David Heinemeier Hansson 已提交
2746 2747
      end

2748
      # Updates the associated record with values matching those of the instance attributes.
2749
      # Returns the number of affected rows.
2750 2751
      def update(attribute_names = @attributes.keys)
        quoted_attributes = attributes_with_quotes(false, false, attribute_names)
2752
        return 0 if quoted_attributes.empty?
D
Initial  
David Heinemeier Hansson 已提交
2753
        connection.update(
2754
          "UPDATE #{self.class.quoted_table_name} " +
2755
          "SET #{quoted_comma_pair_list(connection, quoted_attributes)} " +
2756
          "WHERE #{connection.quote_column_name(self.class.primary_key)} = #{quote_value(id)}",
D
Initial  
David Heinemeier Hansson 已提交
2757 2758 2759 2760
          "#{self.class.name} Update"
        )
      end

2761 2762
      # Creates a record with values matching those of the instance attributes
      # and returns its id.
D
Initial  
David Heinemeier Hansson 已提交
2763
      def create
2764
        if self.id.nil? && connection.prefetch_primary_key?(self.class.table_name)
2765 2766
          self.id = connection.next_sequence_value(self.class.sequence_name)
        end
2767

2768 2769 2770 2771 2772
        quoted_attributes = attributes_with_quotes

        statement = if quoted_attributes.empty?
          connection.empty_insert_statement(self.class.table_name)
        else
2773
          "INSERT INTO #{self.class.quoted_table_name} " +
D
Initial  
David Heinemeier Hansson 已提交
2774
          "(#{quoted_column_names.join(', ')}) " +
2775 2776 2777 2778 2779
          "VALUES(#{quoted_attributes.values.join(', ')})"
        end

        self.id = connection.insert(statement, "#{self.class.name} Create",
          self.class.primary_key, self.id, self.class.sequence_name)
2780

D
Initial  
David Heinemeier Hansson 已提交
2781
        @new_record = false
2782
        id
D
Initial  
David Heinemeier Hansson 已提交
2783 2784
      end

P
Pratik Naik 已提交
2785 2786 2787
      # Sets the attribute used for single table inheritance to this class name if this is not the ActiveRecord::Base descendent.
      # Considering the hierarchy Reply < Message < ActiveRecord::Base, this makes it possible to do Reply.new without having to
      # set <tt>Reply[Reply.inheritance_column] = "Reply"</tt> yourself. No such attribute would be set for objects of the
D
Initial  
David Heinemeier Hansson 已提交
2788 2789 2790
      # Message class in that example.
      def ensure_proper_type
        unless self.class.descends_from_active_record?
2791
          write_attribute(self.class.inheritance_column, self.class.sti_name)
D
Initial  
David Heinemeier Hansson 已提交
2792 2793 2794
        end
      end

2795
      def convert_number_column_value(value)
2796 2797 2798 2799 2800 2801 2802 2803
        if value == false
          0
        elsif value == true
          1
        elsif value.is_a?(String) && value.blank?
          nil
        else
          value
2804
        end
D
Initial  
David Heinemeier Hansson 已提交
2805 2806 2807
      end

      def remove_attributes_protected_from_mass_assignment(attributes)
2808 2809 2810 2811
        safe_attributes =
          if self.class.accessible_attributes.nil? && self.class.protected_attributes.nil?
            attributes.reject { |key, value| attributes_protected_by_default.include?(key.gsub(/\(.+/, "")) }
          elsif self.class.protected_attributes.nil?
2812
            attributes.reject { |key, value| !self.class.accessible_attributes.include?(key.gsub(/\(.+/, "")) || attributes_protected_by_default.include?(key.gsub(/\(.+/, "")) }
2813
          elsif self.class.accessible_attributes.nil?
2814
            attributes.reject { |key, value| self.class.protected_attributes.include?(key.gsub(/\(.+/,"")) || attributes_protected_by_default.include?(key.gsub(/\(.+/, "")) }
2815 2816 2817 2818 2819 2820 2821
          else
            raise "Declare either attr_protected or attr_accessible for #{self.class}, but not both."
          end

        removed_attributes = attributes.keys - safe_attributes.keys

        if removed_attributes.any?
2822
          log_protected_attribute_removal(removed_attributes)
D
Initial  
David Heinemeier Hansson 已提交
2823
        end
2824 2825

        safe_attributes
D
Initial  
David Heinemeier Hansson 已提交
2826
      end
2827

2828 2829 2830
      # Removes attributes which have been marked as readonly.
      def remove_readonly_attributes(attributes)
        unless self.class.readonly_attributes.nil?
2831
          attributes.delete_if { |key, value| self.class.readonly_attributes.include?(key.gsub(/\(.+/,"")) }
2832 2833 2834 2835
        else
          attributes
        end
      end
D
Initial  
David Heinemeier Hansson 已提交
2836

2837 2838 2839 2840
      def log_protected_attribute_removal(*attributes)
        logger.debug "WARNING: Can't mass-assign these protected attributes: #{attributes.join(', ')}"
      end

2841 2842
      # The primary key and inheritance column can never be set by mass-assignment for security reasons.
      def attributes_protected_by_default
2843 2844 2845
        default = [ self.class.primary_key, self.class.inheritance_column ]
        default << 'id' unless self.class.primary_key.eql? 'id'
        default
2846 2847
      end

2848
      # Returns a copy of the attributes hash where all the values have been safely quoted for use in
2849
      # an SQL statement.
2850
      def attributes_with_quotes(include_primary_key = true, include_readonly_attributes = true, attribute_names = @attributes.keys)
2851
        quoted = {}
2852
        connection = self.class.connection
2853
        attribute_names.each do |name|
2854 2855 2856 2857 2858 2859 2860 2861 2862
          if (column = column_for_attribute(name)) && (include_primary_key || !column.primary)
            value = read_attribute(name)

            # We need explicit to_yaml because quote() does not properly convert Time/Date fields to YAML.
            if value && self.class.serialized_attributes.has_key?(name) && (value.acts_like?(:date) || value.acts_like?(:time))
              value = value.to_yaml
            end

            quoted[name] = connection.quote(value, column)
2863
          end
D
Initial  
David Heinemeier Hansson 已提交
2864
        end
2865
        include_readonly_attributes ? quoted : remove_readonly_attributes(quoted)
D
Initial  
David Heinemeier Hansson 已提交
2866
      end
2867

D
Initial  
David Heinemeier Hansson 已提交
2868
      # Quote strings appropriately for SQL statements.
2869
      def quote_value(value, column = nil)
2870
        self.class.connection.quote(value, column)
D
Initial  
David Heinemeier Hansson 已提交
2871 2872
      end

P
Pratik Naik 已提交
2873
      # Interpolate custom SQL string in instance context.
D
Initial  
David Heinemeier Hansson 已提交
2874 2875
      # Optional record argument is meant for custom insert_sql.
      def interpolate_sql(sql, record = nil)
2876
        instance_eval("%@#{sql.gsub('@', '\@')}@")
D
Initial  
David Heinemeier Hansson 已提交
2877 2878 2879 2880 2881 2882 2883
      end

      # Initializes the attributes array with keys matching the columns from the linked table and
      # the values matching the corresponding default value of that column, so
      # that a new instance, or one populated from a passed-in Hash, still has all the attributes
      # that instances loaded from the database would.
      def attributes_from_column_definition
2884
        self.class.columns.inject({}) do |attributes, column|
2885
          attributes[column.name] = column.default unless column.name == self.class.primary_key
D
Initial  
David Heinemeier Hansson 已提交
2886 2887 2888 2889 2890 2891 2892 2893
          attributes
        end
      end

      # Instantiates objects for all attribute classes that needs more than one constructor parameter. This is done
      # by calling new on the column type or aggregation type (through composed_of) object with these parameters.
      # So having the pairs written_on(1) = "2004", written_on(2) = "6", written_on(3) = "24", will instantiate
      # written_on (a date type) with Date.new("2004", "6", "24"). You can also specify a typecast character in the
2894
      # parentheses to have the parameters typecasted before they're used in the constructor. Use i for Fixnum, f for Float,
2895
      # s for String, and a for Array. If all the values for a given attribute are empty, the attribute will be set to nil.
D
Initial  
David Heinemeier Hansson 已提交
2896 2897 2898 2899 2900
      def assign_multiparameter_attributes(pairs)
        execute_callstack_for_multiparameter_attributes(
          extract_callstack_for_multiparameter_attributes(pairs)
        )
      end
2901

2902
      def instantiate_time_object(name, values)
2903
        if self.class.send(:create_time_zone_conversion_attribute?, name, column_for_attribute(name))
2904
          Time.zone.local(*values)
2905
        else
2906
          Time.time_with_datetime_fallback(@@default_timezone, *values)
2907
        end
2908 2909
      end

D
Initial  
David Heinemeier Hansson 已提交
2910
      def execute_callstack_for_multiparameter_attributes(callstack)
2911
        errors = []
D
Initial  
David Heinemeier Hansson 已提交
2912
        callstack.each do |name, values|
2913
          klass = (self.class.reflect_on_aggregation(name.to_sym) || column_for_attribute(name)).klass
D
Initial  
David Heinemeier Hansson 已提交
2914 2915 2916
          if values.empty?
            send(name + "=", nil)
          else
2917
            begin
2918
              value = if Time == klass
2919
                instantiate_time_object(name, values)
2920 2921 2922 2923
              elsif Date == klass
                begin
                  Date.new(*values)
                rescue ArgumentError => ex # if Date.new raises an exception on an invalid date
2924
                  instantiate_time_object(name, values).to_date # we instantiate Time object and convert it back to a date thus using Time's logic in handling invalid dates
2925 2926 2927 2928 2929 2930
                end
              else
                klass.new(*values)
              end

              send(name + "=", value)
2931 2932 2933
            rescue => ex
              errors << AttributeAssignmentError.new("error on assignment #{values.inspect} to #{name}", ex, name)
            end
D
Initial  
David Heinemeier Hansson 已提交
2934 2935
          end
        end
2936 2937 2938
        unless errors.empty?
          raise MultiparameterAssignmentErrors.new(errors), "#{errors.size} error(s) on assignment of multiparameter attributes"
        end
D
Initial  
David Heinemeier Hansson 已提交
2939
      end
2940

D
Initial  
David Heinemeier Hansson 已提交
2941 2942 2943 2944 2945 2946 2947 2948 2949
      def extract_callstack_for_multiparameter_attributes(pairs)
        attributes = { }

        for pair in pairs
          multiparameter_name, value = pair
          attribute_name = multiparameter_name.split("(").first
          attributes[attribute_name] = [] unless attributes.include?(attribute_name)

          unless value.empty?
2950
            attributes[attribute_name] <<
2951
              [ find_parameter_position(multiparameter_name), type_cast_attribute_value(multiparameter_name, value) ]
D
Initial  
David Heinemeier Hansson 已提交
2952 2953 2954 2955 2956
          end
        end

        attributes.each { |name, values| attributes[name] = values.sort_by{ |v| v.first }.collect { |v| v.last } }
      end
2957

D
Initial  
David Heinemeier Hansson 已提交
2958 2959 2960
      def type_cast_attribute_value(multiparameter_name, value)
        multiparameter_name =~ /\([0-9]*([a-z])\)/ ? value.send("to_" + $1) : value
      end
2961

D
Initial  
David Heinemeier Hansson 已提交
2962 2963 2964
      def find_parameter_position(multiparameter_name)
        multiparameter_name.scan(/\(([0-9]*).*\)/).first.first
      end
2965

D
Initial  
David Heinemeier Hansson 已提交
2966 2967 2968 2969 2970 2971
      # Returns a comma-separated pair list, like "key1 = val1, key2 = val2".
      def comma_pair_list(hash)
        hash.inject([]) { |list, pair| list << "#{pair.first} = #{pair.last}" }.join(", ")
      end

      def quoted_column_names(attributes = attributes_with_quotes)
2972
        connection = self.class.connection
2973
        attributes.keys.collect do |column_name|
2974
          connection.quote_column_name(column_name)
2975
        end
D
Initial  
David Heinemeier Hansson 已提交
2976 2977
      end

2978 2979 2980 2981
      def self.quoted_table_name
        self.connection.quote_table_name(self.table_name)
      end

2982 2983 2984 2985
      def quote_columns(quoter, hash)
        hash.inject({}) do |quoted, (name, value)|
          quoted[quoter.quote_column_name(name)] = value
          quoted
2986
        end
D
Initial  
David Heinemeier Hansson 已提交
2987 2988
      end

2989 2990
      def quoted_comma_pair_list(quoter, hash)
        comma_pair_list(quote_columns(quoter, hash))
D
Initial  
David Heinemeier Hansson 已提交
2991 2992 2993
      end

      def object_from_yaml(string)
2994
        return string unless string.is_a?(String) && string =~ /^---/
2995
        YAML::load(string) rescue string
D
Initial  
David Heinemeier Hansson 已提交
2996
      end
2997 2998

      def clone_attributes(reader_method = :read_attribute, attributes = {})
2999 3000 3001
        self.attribute_names.inject(attributes) do |attrs, name|
          attrs[name] = clone_attribute_value(reader_method, name)
          attrs
3002 3003 3004 3005 3006
        end
      end

      def clone_attribute_value(reader_method, attribute_name)
        value = send(reader_method, attribute_name)
3007
        value.duplicable? ? value.clone : value
3008 3009 3010
      rescue TypeError, NoMethodError
        value
      end
D
Initial  
David Heinemeier Hansson 已提交
3011
  end
J
Joshua Peek 已提交
3012 3013 3014 3015 3016 3017 3018 3019 3020 3021 3022

  Base.class_eval do
    extend QueryCache
    include Validations
    include Locking::Optimistic, Locking::Pessimistic
    include AttributeMethods
    include Dirty
    include Callbacks, Observing, Timestamp
    include Associations, AssociationPreload, NamedScope
    include Aggregations, Transactions, Reflection, Calculations, Serialization
  end
3023
end
3024 3025 3026

# TODO: Remove this and make it work with LAZY flag
require 'active_record/connection_adapters/abstract_adapter'