Files

Class Index [+]

Quicksearch

ActiveRecord::AutosaveAssociation

Active Record Autosave Association

AutosaveAssociation is a module that takes care of automatically saving associated records when their parent is saved. In addition to saving, it also destroys any associated records that were marked for destruction. (See mark_for_destruction and marked_for_destruction?).

Saving of the parent, its associations, and the destruction of marked associations, all happen inside a transaction. This should never leave the database in an inconsistent state.

If validations for any of the associations fail, their error messages will be applied to the parent.

Note that it also means that associations marked for destruction won’t be destroyed directly. They will however still be marked for destruction.

Note that :autosave => false is not same as not declaring :autosave. When the :autosave option is not present new associations are saved.

Validation

Children records are validated unless :validate is false.

Callbacks

Association with autosave option defines several callbacks on your model (before_save, after_create, after_update). Please note that callbacks are executed in the order they were defined in model. You should avoid modyfing the association content, before autosave callbacks are executed. Placing your callbacks after associations is usually a good practice.

Examples

One-to-one Example

  class Post
    has_one :author, :autosave => true
  end

Saving changes to the parent and its associated model can now be performed automatically and atomically:

  post = Post.find(1)
  post.title       # => "The current global position of migrating ducks"
  post.author.name # => "alloy"

  post.title = "On the migration of ducks"
  post.author.name = "Eloy Duran"

  post.save
  post.reload
  post.title       # => "On the migration of ducks"
  post.author.name # => "Eloy Duran"

Destroying an associated model, as part of the parent’s save action, is as simple as marking it for destruction:

  post.author.mark_for_destruction
  post.author.marked_for_destruction? # => true

Note that the model is not yet removed from the database:

  id = post.author.id
  Author.find_by_id(id).nil? # => false

  post.save
  post.reload.author # => nil

Now it is removed from the database:

  Author.find_by_id(id).nil? # => true

One-to-many Example

When :autosave is not declared new children are saved when their parent is saved:

  class Post
    has_many :comments # :autosave option is no declared
  end

  post = Post.new(:title => 'ruby rocks')
  post.comments.build(:body => 'hello world')
  post.save # => saves both post and comment

  post = Post.create(:title => 'ruby rocks')
  post.comments.build(:body => 'hello world')
  post.save # => saves both post and comment

  post = Post.create(:title => 'ruby rocks')
  post.comments.create(:body => 'hello world')
  post.save # => saves both post and comment

When :autosave is true all children is saved, no matter whether they are new records:

  class Post
    has_many :comments, :autosave => true
  end

  post = Post.create(:title => 'ruby rocks')
  post.comments.create(:body => 'hello world')
  post.comments[0].body = 'hi everyone'
  post.save # => saves both post and comment, with 'hi everyone' as body

Destroying one of the associated models as part of the parent’s save action is as simple as marking it for destruction:

  post.comments.last.mark_for_destruction
  post.comments.last.marked_for_destruction? # => true
  post.comments.length # => 2

Note that the model is not yet removed from the database:

  id = post.comments.last.id
  Comment.find_by_id(id).nil? # => false

  post.save
  post.reload.comments.length # => 1

Now it is removed from the database:

  Comment.find_by_id(id).nil? # => true

Constants

ASSOCIATION_TYPES

Public Instance Methods

changed_for_autosave?() click to toggle source

Returns whether or not this record has been changed in any way (including whether any of its nested autosave associations are likewise changed)

     # File lib/active_record/autosave_association.rb, line 247
247:     def changed_for_autosave?
248:       new_record? || changed? || marked_for_destruction? || nested_records_changed_for_autosave?
249:     end
mark_for_destruction() click to toggle source

Marks this record to be destroyed as part of the parents save transaction. This does not actually destroy the record instantly, rather child record will be destroyed when parent.save is called.

Only useful if the :autosave option on the parent is enabled for this associated model.

     # File lib/active_record/autosave_association.rb, line 234
234:     def mark_for_destruction
235:       @marked_for_destruction = true
236:     end
marked_for_destruction?() click to toggle source

Returns whether or not this record will be destroyed as part of the parents save transaction.

Only useful if the :autosave option on the parent is enabled for this associated model.

     # File lib/active_record/autosave_association.rb, line 241
241:     def marked_for_destruction?
242:       @marked_for_destruction
243:     end
reload(options = nil) click to toggle source

Reloads the attributes of the object as usual and clears marked_for_destruction flag.

     # File lib/active_record/autosave_association.rb, line 224
224:     def reload(options = nil)
225:       @marked_for_destruction = false
226:       super
227:     end

Private Instance Methods

associated_records_to_validate_or_save(association, new_record, autosave) click to toggle source

Returns the record for an association collection that should be validated or saved. If autosave is false only new records will be returned, unless the parent is/was a new record itself.

     # File lib/active_record/autosave_association.rb, line 256
256:     def associated_records_to_validate_or_save(association, new_record, autosave)
257:       if new_record
258:         association && association.target
259:       elsif autosave
260:         association.target.find_all { |record| record.changed_for_autosave? }
261:       else
262:         association.target.find_all { |record| record.new_record? }
263:       end
264:     end
association_valid?(reflection, record) click to toggle source

Returns whether or not the association is valid and applies any errors to the parent, self, if it wasn’t. Skips any :autosave enabled records if they’re marked_for_destruction? or destroyed.

     # File lib/active_record/autosave_association.rb, line 297
297:     def association_valid?(reflection, record)
298:       return true if record.destroyed? || record.marked_for_destruction?
299: 
300:       unless valid = record.valid?
301:         if reflection.options[:autosave]
302:           record.errors.each do |attribute, message|
303:             attribute = "#{reflection.name}.#{attribute}"
304:             errors[attribute] << message
305:             errors[attribute].uniq!
306:           end
307:         else
308:           errors.add(reflection.name)
309:         end
310:       end
311:       valid
312:     end
before_save_collection_association() click to toggle source

Is used as a before_save callback to check while saving a collection association whether or not the parent was a new record before saving.

     # File lib/active_record/autosave_association.rb, line 316
316:     def before_save_collection_association
317:       @new_record_before_save = new_record?
318:       true
319:     end
nested_records_changed_for_autosave?() click to toggle source

go through nested autosave associations that are loaded in memory (without loading any new ones), and return true if is changed for autosave

     # File lib/active_record/autosave_association.rb, line 268
268:     def nested_records_changed_for_autosave?
269:       self.class.reflect_on_all_autosave_associations.any? do |reflection|
270:         association = association_instance_get(reflection.name)
271:         association && Array.wrap(association.target).any? { |a| a.changed_for_autosave? }
272:       end
273:     end
save_belongs_to_association(reflection) click to toggle source

Saves the associated record if it’s new or :autosave is enabled.

In addition, it will destroy the association if it was marked for destruction.

     # File lib/active_record/autosave_association.rb, line 406
406:     def save_belongs_to_association(reflection)
407:       association = association_instance_get(reflection.name)
408:       record      = association && association.load_target
409:       if record && !record.destroyed?
410:         autosave = reflection.options[:autosave]
411: 
412:         if autosave && record.marked_for_destruction?
413:           record.destroy
414:         elsif autosave != false
415:           saved = record.save(:validate => !autosave) if record.new_record? || (autosave && record.changed_for_autosave?)
416: 
417:           if association.updated?
418:             association_id = record.send(reflection.options[:primary_key] || :id)
419:             self[reflection.foreign_key] = association_id
420:             association.loaded!
421:           end
422: 
423:           saved if autosave
424:         end
425:       end
426:     end
save_collection_association(reflection) click to toggle source

Saves any new associated records, or all loaded autosave associations if :autosave is enabled on the association.

In addition, it destroys all children that were marked for destruction with mark_for_destruction.

This all happens inside a transaction, if the Transactions module is included into ActiveRecord::Base after the AutosaveAssociation module, which it does by default.

     # File lib/active_record/autosave_association.rb, line 329
329:     def save_collection_association(reflection)
330:       if association = association_instance_get(reflection.name)
331:         autosave = reflection.options[:autosave]
332: 
333:         if records = associated_records_to_validate_or_save(association, @new_record_before_save, autosave)
334:           begin
335:             records_to_destroy = []
336: 
337:             records.each do |record|
338:               next if record.destroyed?
339: 
340:               saved = true
341: 
342:               if autosave && record.marked_for_destruction?
343:                 records_to_destroy << record
344:               elsif autosave != false && (@new_record_before_save || record.new_record?)
345:                 if autosave
346:                   saved = association.insert_record(record, false)
347:                 else
348:                   association.insert_record(record) unless reflection.nested?
349:                 end
350:               elsif autosave
351:                 saved = record.save(:validate => false)
352:               end
353: 
354:               raise ActiveRecord::Rollback unless saved
355:             end
356: 
357:             records_to_destroy.each do |record|
358:               association.proxy.destroy(record)
359:             end
360:           rescue
361:             records.each {|x| IdentityMap.remove(x) } if IdentityMap.enabled?
362:             raise
363:           end
364: 
365:         end
366: 
367:         # reconstruct the scope now that we know the owner's id
368:         association.send(:reset_scope) if association.respond_to?(:reset_scope)
369:       end
370:     end
save_has_one_association(reflection) click to toggle source

Saves the associated record if it’s new or :autosave is enabled on the association.

In addition, it will destroy the association if it was marked for destruction with mark_for_destruction.

This all happens inside a transaction, if the Transactions module is included into ActiveRecord::Base after the AutosaveAssociation module, which it does by default.

     # File lib/active_record/autosave_association.rb, line 380
380:     def save_has_one_association(reflection)
381:       association = association_instance_get(reflection.name)
382:       record      = association && association.load_target
383:       if record && !record.destroyed?
384:         autosave = reflection.options[:autosave]
385: 
386:         if autosave && record.marked_for_destruction?
387:           record.destroy
388:         else
389:           key = reflection.options[:primary_key] ? send(reflection.options[:primary_key]) : id
390:           if autosave != false && (new_record? || record.new_record? || record[reflection.foreign_key] != key || autosave)
391:             unless reflection.through_reflection
392:               record[reflection.foreign_key] = key
393:             end
394: 
395:             saved = record.save(:validate => !autosave)
396:             raise ActiveRecord::Rollback if !saved && autosave
397:             saved
398:           end
399:         end
400:       end
401:     end
validate_collection_association(reflection) click to toggle source

Validate the associated records if :validate or :autosave is turned on for the association specified by reflection.

     # File lib/active_record/autosave_association.rb, line 286
286:     def validate_collection_association(reflection)
287:       if association = association_instance_get(reflection.name)
288:         if records = associated_records_to_validate_or_save(association, new_record?, reflection.options[:autosave])
289:           records.each { |record| association_valid?(reflection, record) }
290:         end
291:       end
292:     end
validate_single_association(reflection) click to toggle source

Validate the association if :validate or :autosave is turned on for the association.

     # File lib/active_record/autosave_association.rb, line 277
277:     def validate_single_association(reflection)
278:       association = association_instance_get(reflection.name)
279:       record      = association && association.reader
280:       association_valid?(reflection, record) if record
281:     end

Disabled; run with --debug to generate this.

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.