graph_mediator 0.2.1

data/lib/graph_mediator/locking.rb

@@ -0,0 +1,50 @@
+module GraphMediator
+  # Overrides to ActiveRecord::Optimistic::Locking to ensure that lock_column is updated
+  # during the +versioning+ phase of a mediated transaction.
+  module Locking
+
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.send(:alias_method, :locking_enabled_without_mediation?, :locking_enabled?)
+      base.send(:include, InstanceMethods)
+    end
+
+    module ClassMethods
+      # Overrides ActiveRecord::Base.update_counters to skip locking if currently mediating
+      # the passed id.
+      def update_counters(ids, counters)
+        # id may be an array of ids...
+        unless currently_mediating?(ids)
+          # if none are being mediated can proceed as normal
+          super
+        else
+          # we have to go one by one unfortunately
+          Array(ids).each do |id|
+            currently_mediating?(id) ?
+              update_counters_without_lock(id, counters) :
+              super
+          end
+        end
+      end
+    end
+
+    module InstanceMethods
+      # Overrides ActiveRecord::Locking::Optimistic#locking_enabled?
+      #
+      # * True if we are not in a mediated_transaction and lock_enabled? is true
+      # per ActiveRecord (lock_column exists and lock_optimistically? true)
+      # * True if we are in a mediated_transaction and lock_enabled? is true per
+      # ActiveRecord and we are in the midst of the version bumping phase of the transaction.
+      # 
+      # Effectively this ensures that an optimistic lock check and version bump
+      # occurs as usual outside of mediation but only at the end of the
+      # transaction within mediation.
+      def locking_enabled?
+        locking_enabled = locking_enabled_without_mediation?
+        locking_enabled &&= current_mediation_phase == :versioning if mediation_enabled? && currently_mediating?
+        return locking_enabled
+      end
+    end
+
+  end
+end

data/lib/graph_mediator/mediator.rb

@@ -0,0 +1,260 @@
+require 'aasm'
+
+module GraphMediator
+  # Instances of this class perform the actual mediation work on behalf of a
+  # Proxy#mediated_transaction.
+  class Mediator
+    include AASM
+
+    class IndexedHash < Hash
+      attr_reader :index
+      attr_reader :klass
+
+      def initialize(*args, &block)
+        @index = {}
+        super
+      end
+
+      def <<(ar_instance, klass, changes)
+        add_to_index(changes)
+        case
+          when ar_instance.new_record? then
+            created_array = self[:_created] ||= []
+            created_array << changes
+          when ar_instance.destroyed? then
+            destroyed_array = self[:_destroyed] ||= []
+            destroyed_array << ar_instance.id
+          else self[ar_instance.id] = changes
+        end 
+      end
+
+      def add_to_index(changes)
+        index.merge!(changes)
+      end
+    end
+ 
+    class ChangesHash < IndexedHash
+    
+      def <<(ar_instance)
+        raise(ArgumentError, "Expected an ActiveRecord::Dirty instance: #{ar_instance}") unless ar_instance.respond_to?(:changed?)
+        klass = ar_instance.class.base_class
+        changes = ar_instance.changes
+        add_to_index(changes)
+        klass_hash = self[klass] ||= IndexedHash.new
+        klass_hash.<<(ar_instance, klass, changes)
+        return self
+      end
+
+      # True if the given attribute was changed in root or a dependent.
+      #
+      # * attribute - symbol or string for attribute to lookup
+      # * klass - optionally, restrict lookup to changes for a particular class.
+      #
+      # Shortcut:
+      # changed_#{attribute}?
+      # #{my_class}_changed_#{attribute}?
+      #
+      def attribute_changed?(attribute, klass = nil)
+        (klass ? _class_hash(klass) : self).index.key?(attribute.to_s)
+      end
+
+      # True if all the passed attributes were changed in root or a dependent.
+      def all_changed?(*attributes)
+        attributes.all? { |a| attribute_changed?(a) }
+      end
+
+      # True if any of the passed attributes were changed in root or a dependent.
+      def any_changed?(*attributes)
+        attributes.any? { |a| attribute_changed?(a) }
+      end
+
+      # True if a dependent of the given class was added.
+      def added_dependent?(klass)
+        _class_hash(klass).key?(:_created)
+      end
+
+      # True if a dependent of the given class was destroyed.
+      def destroyed_dependent?(klass)
+        _class_hash(klass).key?(:_destroyed)
+      end
+
+      # True if an existing dependent of the given class was updated.
+      def altered_dependent?(klass)
+        !_class_hash(klass).reject { |k,v| k == :_created || k == :_destroyed }.empty?
+      end
+
+      # True only if a dependent of the given class was added or destroyed. 
+      def added_or_destroyed_dependent?(klass)
+        added_dependent?(klass) || destroyed_dependent?(klass)
+      end
+
+# TODO this and altered_dependent may give false positive for empty change hashes (if a record is saved with no changes, there will be a +record_id+ => {} entry)
+      # True if a dependent of the given class as added, destroyed or updated.
+      def touched_any_dependent?(klass)
+        !_class_hash(klass).empty?
+      end
+
+# TODO raise an error if class does not respond to method?  but what about general changed_foo? calls?  The point is that this syntax can give you false negatives, because changed_foo? will be false even foo isn't even an attribute -- misspelling an attribute can lead to difficult bugs.  This helper may not be a good idea...
+      def method_missing(method)
+        case method.to_s
+          when /(?:(.*)_)?changed_(.*)\?/
+          then
+            klass = $1
+            klass = klass.classify.constantize if klass
+            attribute = $2
+# XXX Don't define a method here, or you run into issues with Rails class reloading.
+# After the first call, you hold a reference to an old Class which will no longer work as
+# a key in a new changes hash.
+#            self.class.__send__(:define_method, method) do
+              return attribute_changed?(attribute, klass) 
+#            end
+#            return send(method)
+          else super       
+        end
+      end
+      
+      private
+
+      def _class_hash(klass)
+        self.fetch(klass.base_class, nil) || IndexedHash.new
+      end 
+    end
+
+    # An instance of the root ActiveRecord object currently under mediation.
+    attr_accessor :mediated_instance
+
+    # Changes made to mediated_instance or dependents during a transaction.
+    attr_accessor :changes
+
+    # Tracks nested transactions
+    attr_accessor :stack
+
+    aasm_initial_state :idle
+    aasm_state :idle
+    aasm_state :mediating
+    aasm_state :versioning
+    aasm_state :disabled
+
+    aasm_event :start do
+      transitions :from => :idle, :to => :mediating
+    end
+    aasm_event :bump do
+      transitions :from => :mediating, :to => :versioning
+    end
+    aasm_event :disable do
+      transitions :from => :idle, :to => :disabled
+    end
+    aasm_event :done do
+      transitions :from => [:idle, :mediating, :versioning, :disabled], :to => :idle
+    end
+
+    def initialize(instance)
+      raise(ArgumentError, "Given instance has not been initialized for mediation: #{instance}") unless instance.kind_of?(GraphMediator)
+      self.mediated_instance = instance
+      self.changes = ChangesHash.new
+      self.stack = []
+    end
+
+    # Mediation may be disabled at either the Class or instance level.
+    # TODO - global module setting?
+    def mediation_enabled?
+      mediated_instance.mediation_enabled?
+    end
+
+    # The id of the instance we are mediating.  
+    def mediated_id
+      mediated_instance.try(:id)
+    end
+
+    # Record the ActiveRecord changes state of the current object.  This allows
+    # us to make decisions in after_mediation callbacks based on changed state.
+    def track_changes_for(ar_instance)
+      changes << ar_instance
+    end
+
+    # True if we are currently in a nested mediated transaction call.
+    def nested?
+      stack.size > 1
+    end
+
+    def mediate(&block)
+      debug("mediate called")
+      stack.push(self)
+      result = if idle?
+        begin_transaction &block
+      else
+        debug("nested transaction; mediate yielding instead")
+        yield self
+      end
+      debug("mediate finished successfully")
+      return result
+
+    ensure
+      done! unless nested? # very important, so that calling methods can ensure cleanup
+      stack.pop
+    end
+
+    [:debug, :info, :warn, :error, :fatal].each do |level|
+      define_method(level) do |message| 
+        mediated_instance.send("m_#{level}", "\e[4;32;1m#{self} - #{aasm_current_state} :\e[0m #{message}")
+      end
+    end
+
+    # Reload them mediated instance.  Throws an ActiveRecord::StaleObjectError
+    # if lock_column has been updated outside of transaction.
+    def refresh_mediated_instance
+      debug "refresh_mediated_instance called"
+      unless mediated_instance.new_record?
+        if mediated_instance.locking_enabled_without_mediation?
+          locking_column = mediated_instance.class.locking_column
+          current_lock_version = mediated_instance.send(locking_column) if locking_column
+        end
+        debug("reloading")
+        mediated_instance.reload 
+        raise(ActiveRecord::StaleObjectError) if current_lock_version && current_lock_version != mediated_instance.send(locking_column)
+      end
+    end
+
+    private
+
+    def begin_transaction(&block)
+      debug("begin_transaction called")
+      result = if mediation_enabled?
+        start!
+        _wrap_in_callbacks &block 
+      else
+        disable!
+        debug("mediation disabled; begin_transaction yielding instead")
+        yield self
+      end
+      debug("begin_transaction finished successfully")
+      return result
+    end
+
+    def _wrap_in_callbacks
+      debug("_wrap_in_callbacks called")
+      debug("_wrap_in_callbacks before_mediation")
+      mediated_instance.run_callbacks(:before_mediation)
+      debug("_wrap_in_callbacks before_mediation completed")
+      debug("_wrap_in_callbacks yielding")
+      result = yield self
+      # skip after_mediation if failed validation
+      unless !result.nil? && result == false
+        debug("_wrap_in_callbacks yielding completed")
+        debug("_wrap_in_callbacks mediate_reconciles")
+        mediated_instance.run_callbacks(:mediate_reconciles)
+        refresh_mediated_instance # after having reconciled
+        debug("_wrap_in_callbacks mediate_reconciles completed")
+        debug("_wrap_in_callbacks mediate_caches")
+        mediated_instance.run_callbacks(:mediate_caches)
+        debug("_wrap_in_callbacks mediate_caches completed")
+        debug("_wrap_in_callbacks bumping")
+        bump!
+        mediated_instance.touch if mediated_instance.class.locking_enabled?
+        debug("_wrap_in_callbacks bumping done")
+        refresh_mediated_instance # after having cached and versioned 
+      end
+      return result
+    end
+  end
+end

data/lib/graph_mediator/version.rb

@@ -0,0 +1,3 @@
+module GraphMediator
+  VERSION = "0.2.1"
+end

data/spec/database.rb

@@ -0,0 +1,12 @@
+require 'rubygems'
+
+gem 'activerecord', '>=2.3.5'
+require 'active_record'
+
+ActiveRecord::Base.establish_connection({'adapter' => 'sqlite3', 'database' => ':memory:'})
+ActiveRecord::Base.logger = Logger.new("#{File.dirname(__FILE__)}/active_record.log")
+
+def create_schema(&block)
+  connection = ActiveRecord::Base.connection
+  yield connection if block_given?
+end

data/spec/examples/course_example_spec.rb

@@ -0,0 +1,91 @@
+require File.expand_path(File.join(File.dirname(__FILE__), '..', 'spec_helper'))
+
+create_schema do |conn|
+  conn.create_table(:people, :force => true) do |t|
+    t.string :name
+    t.string :type
+  end
+
+  conn.create_table(:rooms, :force => true) do |t|
+    t.string :building
+    t.string :number
+  end
+
+  conn.create_table(:courses, :force => true) do |t|
+    t.string :name
+    t.string :term
+    t.integer :year
+    t.belongs_to :people
+    t.belongs_to :room
+    t.integer :session_max
+    t.integer :course_version
+  end
+
+  conn.create_table(:schedules, :force => true) do |t|
+    t.belongs_to :room
+    t.belongs_to :course
+    t.belongs_to :session
+    t.string :day_of_the_week
+    t.time :start_time
+    t.time :end_time
+  end
+  
+  conn.create_table(:assistants, :force => true) do |t|
+    t.belongs_to :course
+    t.belongs_to :people
+  end
+
+  conn.create_table(:sessions, :force => true) do |t|
+    t.belongs_to :assistant
+    t.belongs_to :room
+  end
+
+  conn.create_table(:students, :force => true) do |t|
+    t.belongs_to :people
+    t.belongs_to :course
+    t.string :grade
+  end
+
+  conn.create_table(:session_students, :force => true) do |t|
+    t.belongs_to :session
+    t.belongs_to :student
+  end
+end
+
+class Person < ActiveRecord::Base; end
+class Lecturer < Person; end
+class Student < Person; end
+class GraduateStudent < Student; end
+
+class Room < ActiveRecord::Base; end
+
+class Course < ActiveRecord::Base
+
+  belongs_to :lecturer 
+  belongs_to :room
+  has_many :schedules
+  has_many :assistants
+  has_many :sessions, :through => :assistants
+  has_many :students
+
+#  mediate :reconciliation => :adjust_bars, :bumping => :meeting_version
+
+end
+
+class Schedule < ActiveRecord::Base
+  belongs_to :course
+  belongs_to :room  
+end
+
+class Assistant < ActiveRecord::Base
+  belongs_to :course
+  belongs_to :grad_student
+  has_many :sessions
+  has_many :schedule, :through => :session
+end
+
+class Session < ActiveRecord::Base
+  belongs_to :assistant
+  belongs_to :room
+#  has_many :schedule, :foreign_key => 
+end

data/spec/examples/dingo_pen_example_spec.rb

@@ -0,0 +1,288 @@
+require File.expand_path(File.join(File.dirname(__FILE__), '..', 'spec_helper'))
+require 'aasm'
+
+# Okay I lied.  This example has dingos.
+
+create_schema do |conn|
+  
+  conn.create_table(:dingo_pens, :force => true) do |t|
+    t.integer :pen_number
+    t.integer :dingos_count
+    t.integer :feed_rate
+    t.integer :biscuit_minimum
+    t.integer :biscuit_maximum
+    t.float :total_biscuits
+    t.float :total_biscuit_weight
+    t.integer :lock_version, :default => 0
+    t.timestamps
+  end
+ 
+  conn.create_table(:dingos, :force => true) do |t|
+    t.belongs_to :dingo_pen
+    t.string :name
+    t.string :breed
+    t.integer :voracity
+    t.integer :belly
+    t.string :aasm_state
+    t.integer :lock_version, :default => 0
+    t.timestamps
+  end
+
+  conn.create_table(:biscuits, :force => true) do |t|
+    t.belongs_to :dingo_pen
+    t.string :type
+    t.float :weight
+    t.integer :amount
+    t.integer :lock_version, :default => 0
+    t.timestamps
+  end
+
+end
+
+# A dingo.
+class Dingo < ActiveRecord::Base
+  belongs_to :dingo_pen, :counter_cache => true
+  include AASM
+  aasm_initial_state :hungry
+  aasm_state :hungry, :exit => :eat_biscuits!
+  aasm_state :satiated, :exit => :burn_biscuits!
+  aasm_event :eat do
+    transitions :from => :hungry, :to => :satiated, :guard => :full?
+  end
+  aasm_event :run do
+    transitions :from => :satiated, :to => :hungry
+  end
+
+  def eat_biscuits!
+#    puts "#{self}.eat_biscuits"
+    update_attributes(:belly => (belly || 0) + dingo_pen.eat_biscuits(voracity))
+  end
+
+  def burn_biscuits!
+#    puts "#{self}.burn_biscuits"
+    update_attributes(:belly => 0)
+  end
+
+  def full?
+#    puts "#{self}.full? #{belly}, #{voracity}"
+    belly >= voracity
+  end
+end
+
+# A bunch of biscuits.
+class Biscuit < ActiveRecord::Base
+  belongs_to :dingo_pen
+
+  def consume_weight!(weight_to_consume)
+    amount_to_consume = (weight_to_consume/weight).round
+    amount_consumed = nil
+    if amount >= amount_to_consume
+      self.amount -= amount_to_consume
+      amount_consumed = amount_to_consume
+    else
+      amount_consumed = amount    
+      self.amount = 0
+    end
+    save!
+    return amount_consumed * weight
+  end
+end
+
+class BigBiscuit < Biscuit; end
+class LittleBiscuit < Biscuit; end
+
+class DingoPen < ActiveRecord::Base
+  has_many :dingos
+  has_many :biscuits
+
+  include GraphMediator
+
+  def purchase_biscuits
+    puts :purchase_biscuits
+  end
+
+  mediate :purchase_biscuits,
+    :dependencies => [Dingo, Biscuit],
+    :when_reconciling => [:adjust_biscuit_supply, :feed_dingos],
+    :when_cacheing => :calculate_biscuit_totals
+  
+  def adjust_biscuit_supply
+#puts "\n* adjusting_biscuit_supply"
+    biscuits.each do |b|
+      b.update_attributes(:amount => DingoPen.shovel_biscuits((biscuit_minimum + biscuit_maximum)/2)) if b.amount < biscuit_minimum
+    end
+  end
+
+  def feed_dingos
+#puts "** feed_dingos #{dingos.inspect}"
+    dingos.each { |d| d.eat! if d.hungry? }
+  end
+
+  def eat_biscuits(weight_desired)
+#puts "** eat_biscuits #{weight_desired}"
+    total_weight_consumed = 0
+    weight_left_to_consume = weight_desired
+    biscuits.each do |b|
+      weight_consumed_from_bin = b.consume_weight!(weight_left_to_consume)
+#puts "weight_consumed_from_bin #{b.inspect}: #{weight_consumed_from_bin}"
+      total_weight_consumed += weight_consumed_from_bin
+      weight_left_to_consume -= weight_consumed_from_bin
+      break if weight_left_to_consume <= 0
+    end 
+#puts "total_weight_consumed: #{total_weight_consumed}"
+    return total_weight_consumed
+  end
+
+  def calculate_biscuit_totals
+#puts "** calculate_biscuit_totals #{biscuits.inspect}"
+    update_attributes(
+      :total_biscuits => biscuits.sum('amount'),
+      :total_biscuit_weight => biscuits.sum('weight * amount')
+    )
+  end
+
+  # Class methods
+  class << self
+    # simulates the shoveling of biscuits into DingoPen feeders from the
+    # theoretically BiscuitStore
+    def shovel_biscuits(amount)
+      return amount
+    end
+  end
+end
+
+describe "DingoPen" do
+
+  before(:each) do
+    @dingo_pen_attributes = {
+      :pen_number => 42,
+      :feed_rate => 10,
+      :biscuit_minimum => 50,
+      :biscuit_maximum => 100,
+    }
+  end
+
+  it "should initialize" do
+    dp = DingoPen.new
+  end
+
+  it "should create" do
+    dp = DingoPen.create!(@dingo_pen_attributes)
+    dp.lock_version.should == 1
+  end
+
+  it "should create with dingos and biscuits" do
+    dp = DingoPen.new(@dingo_pen_attributes)
+    dp.dingos << Dingo.new(:name => "Spot", :breed => "Patagonian Leopard Dingo", :voracity => 10)
+    dp.dingos << Dingo.new(:name => "Foo", :breed => "Theoretical Testing Dingo", :voracity => 5)
+    dp.biscuits << BigBiscuit.new(:amount => 35, :weight => 2.0)
+    dp.biscuits << LittleBiscuit.new(:amount => 75, :weight => 0.5)
+    dp.save!
+    dp.lock_version.should == 1
+  end
+
+  context "on create" do
+
+    it "should succeed" do
+      dp = DingoPen.new(@dingo_pen_attributes)
+      dp.dingos << Dingo.new(:name => "Spot", :breed => "Patagonian Leopard Dingo", :voracity => 10)
+      dp.dingos << Dingo.new(:name => "Foo", :breed => "Theoretical Testing Dingo", :voracity => 5)
+      dp.biscuits << BigBiscuit.new(:amount => 35, :weight => 2.0)
+      dp.biscuits << LittleBiscuit.new(:amount => 75, :weight => 0.5)
+      dp.save!
+      dp.reload
+      dp.dingos_count.should == 2
+      dp.dingos[0].belly.should == 10
+      dp.dingos[1].belly.should == 6
+      # biscuit amounts adjusted and dingos ate
+      dp.total_biscuits.should == 142
+      dp.total_biscuit_weight.should == 67 * 2 + 75 * 0.5
+      dp.lock_version.should == 1
+    end
+
+    it "should succed without mediation" do
+      begin
+        DingoPen.disable_all_mediation!
+        dp = DingoPen.new(@dingo_pen_attributes)
+        dp.dingos << Dingo.new(:name => "Spot", :breed => "Patagonian Leopard Dingo", :voracity => 10)
+        dp.dingos << Dingo.new(:name => "Foo", :breed => "Theoretical Testing Dingo", :voracity => 5)
+        dp.biscuits << BigBiscuit.new(:amount => 35, :weight => 2.0)
+        dp.biscuits << LittleBiscuit.new(:amount => 75, :weight => 0.5)
+        dp.save!
+        dp.reload
+        dp.dingos_count.should == 2
+        dp.total_biscuits.should be_nil
+        dp.total_biscuit_weight.should be_nil
+        dp.lock_version.should == 0
+      ensure
+        DingoPen.enable_all_mediation!
+      end
+    end
+
+  end
+
+  context "on update" do
+    it "should update_calculations after every child" do
+      dp = DingoPen.create!(@dingo_pen_attributes)
+      dp.dingos << Dingo.new(:name => "Spot", :breed => "Patagonian Leopard Dingo", :voracity => 10)
+      dp.dingos << Dingo.new(:name => "Foo", :breed => "Theoretical Testing Dingo", :voracity => 5)
+      dp.biscuits << BigBiscuit.new(:amount => 35, :weight => 2.0)
+      dp.biscuits << LittleBiscuit.new(:amount => 75, :weight => 0.5)
+      dp.reload
+      dp.dingos_count.should == 2
+      dp.dingos[0].belly.should == 10
+      dp.dingos[1].belly.should == 6
+      # biscuit amounts adjusted and dingos ate
+      dp.total_biscuits.should == 142
+      dp.total_biscuit_weight.should == 67 * 2 + 75 * 0.5
+      dp.lock_version.should == 5
+    end
+
+    it "should have updated calculations only once within a mediated transaction" do
+      dp = DingoPen.create!(@dingo_pen_attributes)
+      dp.mediated_transaction do
+        dp.dingos << Dingo.new(:name => "Spot", :breed => "Patagonian Leopard Dingo", :voracity => 10)
+        dp.dingos << Dingo.new(:name => "Foo", :breed => "Theoretical Testing Dingo", :voracity => 5)
+        dp.biscuits << BigBiscuit.new(:amount => 35, :weight => 2.0)
+        dp.biscuits << LittleBiscuit.new(:amount => 75, :weight => 0.5)
+        dp.save!
+      end
+      dp.reload
+      dp.dingos_count.should == 2
+      dp.dingos[0].belly.should == 10
+      dp.dingos[1].belly.should == 6
+      # biscuit amounts adjusted, and dingos ate
+      dp.total_biscuits.should == 142
+      dp.total_biscuit_weight.should == 67 * 2 + 75 * 0.5
+      dp.lock_version.should == 2
+    end
+  end
+
+  context "on delete" do
+    before(:each) do
+      @dp = DingoPen.new(@dingo_pen_attributes)
+      @dp.dingos << @spot = Dingo.new(:name => "Spot", :breed => "Patagonian Leopard Dingo", :voracity => 10)
+      @dp.dingos << Dingo.new(:name => "Foo", :breed => "Theoretical Testing Dingo", :voracity => 5)
+      @dp.biscuits << @big = BigBiscuit.new(:amount => 35, :weight => 2.0)
+      @dp.biscuits << LittleBiscuit.new(:amount => 75, :weight => 0.5)
+      @dp.save!
+      @spot.reload
+      @big.reload
+    end
+
+    it "should increment graph version after deletion of a child" do
+      lambda {
+        @spot.destroy
+        @dp.reload
+      }.should change(@dp, :lock_version).by(1)
+    end
+
+    it "should update_calculations after deletion of a child" do
+      @big.destroy
+      @dp.reload
+      @dp.total_biscuits.should == 75 
+      @dp.total_biscuit_weight.should == 75 * 0.5
+    end
+
+  end
+end