Skip to content
This repository
tag: v2.3.14
Fetching contributors…

Octocat-spinner-32-eaf2f5

Cannot retrieve contributors at this time

file 361 lines (330 sloc) 14.923 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 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 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360
require 'observer'

module ActiveRecord
  # Callbacks are hooks into the lifecycle of an Active Record object that allow you to trigger logic
  # before or after an alteration of the object state. This can be used to make sure that associated and
  # dependent objects are deleted when +destroy+ is called (by overwriting +before_destroy+) or to massage attributes
  # before they're validated (by overwriting +before_validation+). As an example of the callbacks initiated, consider
  # the <tt>Base#save</tt> call for a new record:
  #
  # * (-) <tt>save</tt>
  # * (-) <tt>valid</tt>
  # * (1) <tt>before_validation</tt>
  # * (2) <tt>before_validation_on_create</tt>
  # * (-) <tt>validate</tt>
  # * (-) <tt>validate_on_create</tt>
  # * (3) <tt>after_validation</tt>
  # * (4) <tt>after_validation_on_create</tt>
  # * (5) <tt>before_save</tt>
  # * (6) <tt>before_create</tt>
  # * (-) <tt>create</tt>
  # * (7) <tt>after_create</tt>
  # * (8) <tt>after_save</tt>
  #
  # That's a total of eight callbacks, which gives you immense power to react and prepare for each state in the
  # Active Record lifecycle. The sequence for calling <tt>Base#save</tt> an existing record is similar, except that each
  # <tt>_on_create</tt> callback is replaced by the corresponding <tt>_on_update</tt> callback.
  #
  # Examples:
  # class CreditCard < ActiveRecord::Base
  # # Strip everything but digits, so the user can specify "555 234 34" or
  # # "5552-3434" or both will mean "55523434"
  # def before_validation_on_create
  # self.number = number.gsub(/[^0-9]/, "") if attribute_present?("number")
  # end
  # end
  #
  # class Subscription < ActiveRecord::Base
  # before_create :record_signup
  #
  # private
  # def record_signup
  # self.signed_up_on = Date.today
  # end
  # end
  #
  # class Firm < ActiveRecord::Base
  # # Destroys the associated clients and people when the firm is destroyed
  # before_destroy { |record| Person.destroy_all "firm_id = #{record.id}" }
  # before_destroy { |record| Client.destroy_all "client_of = #{record.id}" }
  # end
  #
  # == Inheritable callback queues
  #
  # Besides the overwritable callback methods, it's also possible to register callbacks through the use of the callback macros.
  # Their main advantage is that the macros add behavior into a callback queue that is kept intact down through an inheritance
  # hierarchy. Example:
  #
  # class Topic < ActiveRecord::Base
  # before_destroy :destroy_author
  # end
  #
  # class Reply < Topic
  # before_destroy :destroy_readers
  # end
  #
  # Now, when <tt>Topic#destroy</tt> is run only +destroy_author+ is called. When <tt>Reply#destroy</tt> is run, both +destroy_author+ and
  # +destroy_readers+ are called. Contrast this to the situation where we've implemented the save behavior through overwriteable
  # methods:
  #
  # class Topic < ActiveRecord::Base
  # def before_destroy() destroy_author end
  # end
  #
  # class Reply < Topic
  # def before_destroy() destroy_readers end
  # end
  #
  # In that case, <tt>Reply#destroy</tt> would only run +destroy_readers+ and _not_ +destroy_author+. So, use the callback macros when
  # you want to ensure that a certain callback is called for the entire hierarchy, and use the regular overwriteable methods
  # when you want to leave it up to each descendant to decide whether they want to call +super+ and trigger the inherited callbacks.
  #
  # *IMPORTANT:* In order for inheritance to work for the callback queues, you must specify the callbacks before specifying the
  # associations. Otherwise, you might trigger the loading of a child before the parent has registered the callbacks and they won't
  # be inherited.
  #
  # == Types of callbacks
  #
  # There are four types of callbacks accepted by the callback macros: Method references (symbol), callback objects,
  # inline methods (using a proc), and inline eval methods (using a string). Method references and callback objects are the
  # recommended approaches, inline methods using a proc are sometimes appropriate (such as for creating mix-ins), and inline
  # eval methods are deprecated.
  #
  # The method reference callbacks work by specifying a protected or private method available in the object, like this:
  #
  # class Topic < ActiveRecord::Base
  # before_destroy :delete_parents
  #
  # private
  # def delete_parents
  # self.class.delete_all "parent_id = #{id}"
  # end
  # end
  #
  # The callback objects have methods named after the callback called with the record as the only parameter, such as:
  #
  # class BankAccount < ActiveRecord::Base
  # before_save EncryptionWrapper.new
  # after_save EncryptionWrapper.new
  # after_initialize EncryptionWrapper.new
  # end
  #
  # class EncryptionWrapper
  # def before_save(record)
  # record.credit_card_number = encrypt(record.credit_card_number)
  # end
  #
  # def after_save(record)
  # record.credit_card_number = decrypt(record.credit_card_number)
  # end
  #
  # alias_method :after_find, :after_save
  #
  # private
  # def encrypt(value)
  # # Secrecy is committed
  # end
  #
  # def decrypt(value)
  # # Secrecy is unveiled
  # end
  # end
  #
  # So you specify the object you want messaged on a given callback. When that callback is triggered, the object has
  # a method by the name of the callback messaged. You can make these callbacks more flexible by passing in other
  # initialization data such as the name of the attribute to work with:
  #
  # class BankAccount < ActiveRecord::Base
  # before_save EncryptionWrapper.new("credit_card_number")
  # after_save EncryptionWrapper.new("credit_card_number")
  # after_initialize EncryptionWrapper.new("credit_card_number")
  # end
  #
  # class EncryptionWrapper
  # def initialize(attribute)
  # @attribute = attribute
  # end
  #
  # def before_save(record)
  # record.send("#{@attribute}=", encrypt(record.send("#{@attribute}")))
  # end
  #
  # def after_save(record)
  # record.send("#{@attribute}=", decrypt(record.send("#{@attribute}")))
  # end
  #
  # alias_method :after_find, :after_save
  #
  # private
  # def encrypt(value)
  # # Secrecy is committed
  # end
  #
  # def decrypt(value)
  # # Secrecy is unveiled
  # end
  # end
  #
  # The callback macros usually accept a symbol for the method they're supposed to run, but you can also pass a "method string",
  # which will then be evaluated within the binding of the callback. Example:
  #
  # class Topic < ActiveRecord::Base
  # before_destroy 'self.class.delete_all "parent_id = #{id}"'
  # end
  #
  # Notice that single quotes (') are used so the <tt>#{id}</tt> part isn't evaluated until the callback is triggered. Also note that these
  # inline callbacks can be stacked just like the regular ones:
  #
  # class Topic < ActiveRecord::Base
  # before_destroy 'self.class.delete_all "parent_id = #{id}"',
  # 'puts "Evaluated after parents are destroyed"'
  # end
  #
  # == The +after_find+ and +after_initialize+ exceptions
  #
  # Because +after_find+ and +after_initialize+ are called for each object found and instantiated by a finder, such as <tt>Base.find(:all)</tt>, we've had
  # to implement a simple performance constraint (50% more speed on a simple test case). Unlike all the other callbacks, +after_find+ and
  # +after_initialize+ will only be run if an explicit implementation is defined (<tt>def after_find</tt>). In that case, all of the
  # callback types will be called.
  #
  # == <tt>before_validation*</tt> returning statements
  #
  # If the returning value of a +before_validation+ callback can be evaluated to +false+, the process will be aborted and <tt>Base#save</tt> will return +false+.
  # If Base#save! is called it will raise a ActiveRecord::RecordInvalid exception.
  # Nothing will be appended to the errors object.
  #
  # == Canceling callbacks
  #
  # If a <tt>before_*</tt> callback returns +false+, all the later callbacks and the associated action are cancelled. If an <tt>after_*</tt> callback returns
  # +false+, all the later callbacks are cancelled. Callbacks are generally run in the order they are defined, with the exception of callbacks
  # defined as methods on the model, which are called last.
  #
  # == Transactions
  #
  # The entire callback chain of a +save+, <tt>save!</tt>, or +destroy+ call runs
  # within a transaction. That includes <tt>after_*</tt> hooks. If everything
  # goes fine a COMMIT is executed once the chain has been completed.
  #
  # If a <tt>before_*</tt> callback cancels the action a ROLLBACK is issued. You
  # can also trigger a ROLLBACK raising an exception in any of the callbacks,
  # including <tt>after_*</tt> hooks. Note, however, that in that case the client
  # needs to be aware of it because an ordinary +save+ will raise such exception
  # instead of quietly returning +false+.
  module Callbacks
    CALLBACKS = %w(
after_find after_initialize before_save after_save before_create after_create before_update after_update before_validation
after_validation before_validation_on_create after_validation_on_create before_validation_on_update
after_validation_on_update before_destroy after_destroy
)

    def self.included(base) #:nodoc:
      base.extend Observable

      [:create_or_update, :valid?, :create, :update, :destroy].each do |method|
        base.send :alias_method_chain, method, :callbacks
      end

      base.send :include, ActiveSupport::Callbacks
      base.define_callbacks *CALLBACKS
    end

    # Is called when the object was instantiated by one of the finders, like <tt>Base.find</tt>.
    #def after_find() end

    # Is called after the object has been instantiated by a call to <tt>Base.new</tt>.
    #def after_initialize() end

    # Is called _before_ <tt>Base.save</tt> (regardless of whether it's a +create+ or +update+ save).
    def before_save() end

    # Is called _after_ <tt>Base.save</tt> (regardless of whether it's a +create+ or +update+ save).
    # Note that this callback is still wrapped in the transaction around +save+. For example, if you
    # invoke an external indexer at this point it won't see the changes in the database.
    #
    # class Contact < ActiveRecord::Base
    # after_save { logger.info( 'New contact saved!' ) }
    # end
    def after_save() end
    def create_or_update_with_callbacks #:nodoc:
      return false if callback(:before_save) == false
      if result = create_or_update_without_callbacks
        callback(:after_save)
      end
      result
    end
    private :create_or_update_with_callbacks

    # Is called _before_ <tt>Base.save</tt> on new objects that haven't been saved yet (no record exists).
    def before_create() end

    # Is called _after_ <tt>Base.save</tt> on new objects that haven't been saved yet (no record exists).
    # Note that this callback is still wrapped in the transaction around +save+. For example, if you
    # invoke an external indexer at this point it won't see the changes in the database.
    def after_create() end
    def create_with_callbacks #:nodoc:
      return false if callback(:before_create) == false
      result = create_without_callbacks
      callback(:after_create)
      result
    end
    private :create_with_callbacks

    # Is called _before_ <tt>Base.save</tt> on existing objects that have a record.
    def before_update() end

    # Is called _after_ <tt>Base.save</tt> on existing objects that have a record.
    # Note that this callback is still wrapped in the transaction around +save+. For example, if you
    # invoke an external indexer at this point it won't see the changes in the database.
    def after_update() end

    def update_with_callbacks(*args) #:nodoc:
      return false if callback(:before_update) == false
      result = update_without_callbacks(*args)
      callback(:after_update)
      result
    end
    private :update_with_callbacks

    # Is called _before_ <tt>Validations.validate</tt> (which is part of the <tt>Base.save</tt> call).
    def before_validation() end

    # Is called _after_ <tt>Validations.validate</tt> (which is part of the <tt>Base.save</tt> call).
    def after_validation() end

    # Is called _before_ <tt>Validations.validate</tt> (which is part of the <tt>Base.save</tt> call) on new objects
    # that haven't been saved yet (no record exists).
    def before_validation_on_create() end

    # Is called _after_ <tt>Validations.validate</tt> (which is part of the <tt>Base.save</tt> call) on new objects
    # that haven't been saved yet (no record exists).
    def after_validation_on_create() end

    # Is called _before_ <tt>Validations.validate</tt> (which is part of the <tt>Base.save</tt> call) on
    # existing objects that have a record.
    def before_validation_on_update() end

    # Is called _after_ <tt>Validations.validate</tt> (which is part of the <tt>Base.save</tt> call) on
    # existing objects that have a record.
    def after_validation_on_update() end

    def valid_with_callbacks? #:nodoc:
      return false if callback(:before_validation) == false
      if new_record? then result = callback(:before_validation_on_create) else result = callback(:before_validation_on_update) end
      return false if false == result

      result = valid_without_callbacks?

      callback(:after_validation)
      if new_record? then callback(:after_validation_on_create) else callback(:after_validation_on_update) end

      return result
    end

    # Is called _before_ <tt>Base.destroy</tt>.
    #
    # Note: If you need to _destroy_ or _nullify_ associated records first,
    # use the <tt>:dependent</tt> option on your associations.
    def before_destroy() end

    # Is called _after_ <tt>Base.destroy</tt> (and all the attributes have been frozen).
    #
    # class Contact < ActiveRecord::Base
    # after_destroy { |record| logger.info( "Contact #{record.id} was destroyed." ) }
    # end
    def after_destroy() end
    def destroy_with_callbacks #:nodoc:
      return false if callback(:before_destroy) == false
      result = destroy_without_callbacks
      callback(:after_destroy)
      result
    end

    private
      def callback(method)
        result = run_callbacks(method) { |result, object| false == result }

        if result != false && respond_to_without_attributes?(method)
          result = send(method)
        end

        notify(method)

        return result
      end

      def notify(method) #:nodoc:
        self.class.changed
        self.class.notify_observers(method, self)
      end
  end
end
Something went wrong with that request. Please try again.