README.rdoc

Graph Mediator¶ ↑

GraphMediator is used to help coordinate state between a graph of ActiveRecord objects related to a single root node. Its role is assisting in cases where you are representing a complex concept as a graph of related objects with potentially circular interdependencies. Changing attributes in one object might require adding or removing of dependent objects. Adding these objects might necessitate a recalculation of memberships in a join table. Any such changes might require that cached calculations be redone. Touching any object in the graph might require a version bump for the concept of the graph as a whole.

We want changes to be made once, in a single transaction, with a single overall version change. The version change should be guarded by an optimistic lock check to avoid conflicts between two processes updates to the same graph.

To make interdependent state changes manageable, GraphMediator wraps an additional layer of callbacks around the ActiveRecord save cycle to ensure that a save occurs within a GraphMediator.mediated_transaction.

• :before_mediation

• • save *

• :after_mediation

The after_mediation callback is itself broken down into three phases:

• :reconciliation - in this phase, any methods which bring the overall state of the graph into balance should be run to adjust for changes made during the save.

• :cacheing - any calculations which rely on the state of a reconciled graph but which do not themselves alter the graph (in that they are reproducible from existing state) should be made in the cacheing phase.

• :bumping - if the class has a lock_column set (ActiveRecord::Locking::Optimistic) and has on updated_at/on timestamp then the instance will be touched, bumping the lock_column and checking for stale data.

During a mediated_transaction, the lock_column will only update during the bumping phase of the after_mediation callback.

But if there is no update_at/on timestamp, then lock_column cannot be incremented when dependent objects are updated. This is because there is nothing to touch on the root record to trigger the lock_column update.

GraphMediator ensures that after_mediation is run only once within the context of a mediated transaction. If the block being mediated returns false, the after_mediation is skipped; this allows for validations.

Usage¶ ↑

# * :pen_number
# * :dingo_count
# * :biscuit_count
# * :feed_rate 
# * :total_biscuit_weight
# * :lock_version, :default => 0 # required for versioning
# * :updated_at                  # required for versioning
class DingoPen < ActiveRecord::Base

  has_many :dingos
  has_many :biscuits

  include GraphMediator
  mediate :purchase_biscuits,
    :dependencies => [Dingo, Biscuit],
    :when_reconciling => [:adjust_biscuit_supply, :feed_dingos],
    :when_cacheing => :calculate_total_biscuit_weight

  or

  mediate :purchase_biscuits,
    :dependencies => [Dingo, Biscuit], # ensures a mediated_transaction on Dingo#save or Biscuit#save
  mediate_reconciles :adjust_biscuit_supply, :feed_dingos
  mediate_caches do |instance|
    instance.calculate_total_biscuit_weight
  end

  ...

  def purchase_biscuits; ... end
  def adjust_biscuit_supply; ... end
  def feed_dingos; ... end
  def calculate_total_biscuit_weight; ... end
end

See spec/examples for real, dingo-free examples.

Caveats¶ ↑

A lock_column and timestamp are not required, but without both columns in your schema there will be no versioning.

A lock_column by itself without a timestamp will not increment and will not provide any optimistic locking in a class including GraphMediator!

Using a lock_column along with a counter_cache in a dependent child will raise a StaleObject error during a mediated_transaction if you touch the dependent.

The cache_counters do not play well with optimistic locking because they are updated with a direct SQL call to the database, so ActiveRecord instance remain unaware of the lock_version change and assume it came from another transaction.

You should not need to declare lock_version for any children that are declared as a dependency of the root node, since updates will also update the root nodes lock_version. So if another transaction updates a child, root.lock_version should increment, and the first transaction should raise a StaleObject error when it too tries to update the child.

If you override save in the model hierarchy you are mediating, you must pass your override as a block to super or it will occur outside of mediation:

def save
  super do
    my_local_changes
  end
end

You are probably better off hooking to before_save or after_save if they suffice.

Threads¶ ↑

GraphMediator uses thread local variables to keep track of open mediators. It should be thread safe but this needs testing.

Advice¶ ↑

Build a simple system first, rather than building a system to use GraphMediator.

But if you have a web of observers/callbacks struggling to maintain state, repeated, redundant update calls from observed changes in collection members, or are running into lock_column issues within your own updates, then GraphMediator may help.

Copyright¶ ↑

Copyright © 2010 Josh Partlow. See LICENSE for details.