state_machine 0.3.1 → 0.4.0

data/lib/state_machine/integrations/active_record.rb

@@ -0,0 +1,242 @@
+module StateMachine
+  module Integrations #:nodoc:
+    # Adds support for integrating state machines with ActiveRecord models.
+    # 
+    # == Examples
+    # 
+    # Below is an example of a simple state machine defined within an
+    # ActiveRecord model:
+    # 
+    #   class Vehicle < ActiveRecord::Base
+    #     state_machine :initial => 'parked' do
+    #       event :ignite do
+    #         transition :to => 'idling', :from => 'parked'
+    #       end
+    #     end
+    #   end
+    # 
+    # The examples in the sections below will use the above class as a
+    # reference.
+    # 
+    # == Actions
+    # 
+    # By default, the action that will be invoked when a state is transitioned
+    # is the +save+ action.  This will cause the record to save the changes
+    # made to the state machine's attribute.  *Note* that if any other changes
+    # were made to the record prior to transition, then those changes will
+    # be saved as well.
+    # 
+    # For example,
+    # 
+    #   vehicle = Vehicle.create          # => #<Vehicle id: 1, name: nil, state: nil>
+    #   vehicle.name = 'Ford Explorer'
+    #   vehicle.ignite                    # => true
+    #   vehicle.reload                    # => #<Vehicle id: 1, name: "Ford Explorer", state: "idling">
+    # 
+    # == Transactions
+    # 
+    # In order to ensure that any changes made during transition callbacks
+    # are rolled back during a failed attempt, every transition is wrapped
+    # within a transaction.
+    # 
+    # For example,
+    # 
+    #   class Message < ActiveRecord::Base
+    #   end
+    #   
+    #   Vehicle.state_machine do
+    #     before_transition do |vehicle, transition|
+    #       Message.create(:content => transition.inspect)
+    #       false
+    #     end
+    #   end
+    #   
+    #   vehicle = Vehicle.create      # => #<Vehicle id: 1, name: nil, state: nil>
+    #   vehicle.ignite                # => false
+    #   Message.count                 # => 0
+    # 
+    # *Note* that only before callbacks that halt the callback chain and
+    # failed attempts to save the record will result in the transaction being
+    # rolled back.  If an after callback halts the chain, the previous result
+    # still applies and the transaction is *not* rolled back.
+    # 
+    # == Scopes
+    # 
+    # To assist in filtering models with specific states, a series of named
+    # scopes are defined on the model for finding records with or without a
+    # particular set of states.
+    # 
+    # These named scopes are the functional equivalent of the following
+    # definitions:
+    # 
+    #   class Vehicle < ActiveRecord::Base
+    #     named_scope :with_states, lambda {|*values| {:conditions => {:state => values.flatten}}}
+    #     # with_states also aliased to with_state
+    #     
+    #     named_scope :without_states, lambda {|*values| {:conditions => ['state NOT IN (?)', values.flatten]}}
+    #     # without_states also aliased to without_state
+    #   end
+    # 
+    # Because of the way named scopes work in ActiveRecord, they can be
+    # chained like so:
+    # 
+    #   Vehicle.with_state('parked').all(:order => 'id DESC')
+    # 
+    # == Callbacks
+    # 
+    # All before/after transition callbacks defined for ActiveRecord models
+    # behave in the same way that other ActiveRecord callbacks behave.  The
+    # object involved in the transition is passed in as an argument.
+    # 
+    # For example,
+    # 
+    #   class Vehicle < ActiveRecord::Base
+    #     state_machine :initial => 'parked' do
+    #       before_transition :to => 'idling' do |vehicle|
+    #         vehicle.put_on_seatbelt
+    #       end
+    #       
+    #       before_transition do |vehicle, transition|
+    #         # log message
+    #       end
+    #       
+    #       event :ignite do
+    #         transition :to => 'idling', :from => 'parked'
+    #       end
+    #     end
+    #     
+    #     def put_on_seatbelt
+    #       ...
+    #     end
+    #   end
+    # 
+    # Note, also, that the transition can be accessed by simply defining
+    # additional arguments in the callback block.
+    # 
+    # == Observers
+    # 
+    # In addition to support for ActiveRecord-like hooks, there is additional
+    # support for ActiveRecord observers.  Because of the way ActiveRecord
+    # observers are designed, there is less flexibility around the specific
+    # transitions that can be hooked in.  As a result, observers can only
+    # hook into before/after callbacks for events and generic transitions
+    # like so:
+    # 
+    #   class VehicleObserver < ActiveRecord::Observer
+    #     def before_save(vehicle)
+    #       # log message
+    #     end
+    #     
+    #     # Callback for :ignite event *before* the transition is performed
+    #     def before_ignite(vehicle, transition)
+    #       # log message
+    #     end
+    #     
+    #     # Callback for :ignite event *after* the transition has been performed
+    #     def after_ignite(vehicle, transition)
+    #       # put on seatbelt
+    #     end
+    #     
+    #     # Generic transition callback *before* the transition is performed
+    #     def after_transition(vehicle, transition)
+    #       Audit.log(vehicle, transition)
+    #     end
+    #   end
+    # 
+    # More flexible transition callbacks can be defined directly within the
+    # model as described in StateMachine::Machine#before_transition
+    # and StateMachine::Machine#after_transition.
+    # 
+    # To define a single observer for multiple state machines:
+    # 
+    #   class StateMachineObserver < ActiveRecord::Observer
+    #     observe Vehicle, Switch, Project
+    #     
+    #     def after_transition(record, transition)
+    #       Audit.log(record, transition)
+    #     end
+    #   end
+    module ActiveRecord
+      # Should this integration be used for state machines in the given class?
+      # Classes that inherit from ActiveRecord::Base will automatically use
+      # the ActiveRecord integration.
+      def self.matches?(klass)
+        defined?(::ActiveRecord::Base) && klass <= ::ActiveRecord::Base
+      end
+      
+      # Runs a new database transaction, rolling back any changes by raising
+      # an ActiveRecord::Rollback exception if the yielded block fails
+      # (i.e. returns false).
+      def within_transaction(object)
+        object.class.transaction {raise ::ActiveRecord::Rollback unless yield}
+      end
+      
+      protected
+        # Adds the default callbacks for notifying ActiveRecord observers
+        # before/after a transition has been performed.
+        def after_initialize
+          # Observer callbacks never halt the chain; result is ignored
+          callbacks[:before] << Callback.new {|object, transition| notify(:before, object, transition)}
+          callbacks[:after] << Callback.new {|object, transition, result| notify(:after, object, transition)}
+        end
+        
+        # Sets the default action for all ActiveRecord state machines to +save+
+        def default_action
+          :save
+        end
+        
+        # Forces all attribute methods to be generated for the model so that
+        # the reader/writer methods for the attribute are available
+        def define_attribute_accessor
+          owner_class.define_attribute_methods if owner_class.table_exists?
+          super
+        end
+        
+        # Defines a scope for finding records *with* a particular value or
+        # values for the attribute
+        def define_with_scope(name)
+          attribute = self.attribute
+          owner_class.named_scope name.to_sym, lambda {|*values| {:conditions => {attribute => values.flatten}}}
+        end
+        
+        # Defines a scope for finding records *without* a particular value or
+        # values for the attribute
+        def define_without_scope(name)
+          attribute = self.attribute
+          owner_class.named_scope name.to_sym, lambda {|*values| {:conditions => ["#{attribute} NOT IN (?)", values.flatten]}}
+        end
+        
+        # Creates a new callback in the callback chain, always inserting it
+        # before the default Observer callbacks that were created after
+        # initialization.
+        def add_callback(type, options, &block)
+          options[:terminator] = @terminator ||= lambda {|result| result == false}
+          @callbacks[type].insert(-2, callback = Callback.new(options, &block))
+          add_states(callback.known_states)
+          
+          callback
+        end
+        
+      private
+        # Notifies observers on the given object that a callback occurred
+        # involving the given transition.  This will attempt to call the
+        # following methods on observers:
+        # * #{type}_#{event}
+        # * #{type}_transition
+        # 
+        # This will always return true regardless of the results of the
+        # callbacks.
+        def notify(type, object, transition)
+          ["#{type}_#{transition.event}", "#{type}_transition"].each do |method|
+            object.class.class_eval do
+              @observer_peers.dup.each do |observer|
+                observer.send(method, object, transition) if observer.respond_to?(method)
+              end if defined?(@observer_peers)
+            end
+          end
+          
+          true
+        end
+    end
+  end
+end

data/lib/state_machine/integrations/data_mapper.rb

@@ -0,0 +1,198 @@
+module StateMachine
+  module Integrations #:nodoc:
+    # Adds support for integrating state machines with DataMapper resources.
+    # 
+    # == Examples
+    # 
+    # Below is an example of a simple state machine defined within a
+    # DataMapper resource:
+    # 
+    #   class Vehicle
+    #     include DataMapper::Resource
+    #     
+    #     property :id, Serial
+    #     property :name, String
+    #     property :state, String
+    #     
+    #     state_machine :initial => 'parked' do
+    #       event :ignite do
+    #         transition :to => 'idling', :from => 'parked'
+    #       end
+    #     end
+    #   end
+    # 
+    # The examples in the sections below will use the above class as a
+    # reference.
+    # 
+    # == Actions
+    # 
+    # By default, the action that will be invoked when a state is transitioned
+    # is the +save+ action.  This will cause the resource to save the changes
+    # made to the state machine's attribute.  *Note* that if any other changes
+    # were made to the resource prior to transition, then those changes will
+    # be saved as well.
+    # 
+    # For example,
+    # 
+    #   vehicle = Vehicle.create          # => #<Vehicle id=1 name=nil state=nil>
+    #   vehicle.name = 'Ford Explorer'
+    #   vehicle.ignite                    # => true
+    #   vehicle.reload                    # => #<Vehicle id=1 name="Ford Explorer" state="idling">
+    # 
+    # == Transactions
+    # 
+    # In order to ensure that any changes made during transition callbacks
+    # are rolled back during a failed attempt, every transition is wrapped
+    # within a transaction.
+    # 
+    # For example,
+    # 
+    #   class Message
+    #     include DataMapper::Resource
+    #     
+    #     property :id, Serial
+    #     property :content, String
+    #   end
+    #   
+    #   Vehicle.state_machine do
+    #     before_transition do |transition|
+    #       Message.create(:content => transition.inspect)
+    #       throw :halt
+    #     end
+    #   end
+    #   
+    #   vehicle = Vehicle.create      # => #<Vehicle id=1 name=nil state=nil>
+    #   vehicle.ignite                # => false
+    #   Message.all.count             # => 0
+    # 
+    # *Note* that only before callbacks that halt the callback chain and
+    # failed attempts to save the record will result in the transaction being
+    # rolled back.  If an after callback halts the chain, the previous result
+    # still applies and the transaction is *not* rolled back.
+    # 
+    # == Scopes
+    # 
+    # To assist in filtering models with specific states, a series of class
+    # methods are defined on the model for finding records with or without a
+    # particular set of states.
+    # 
+    # These named scopes are the functional equivalent of the following
+    # definitions:
+    # 
+    #   class Vehicle
+    #     include DataMapper::Resource
+    #     
+    #     property :id, Serial
+    #     property :state, String
+    #     
+    #     class << self
+    #       def with_states(*values)
+    #         all(:state => values.flatten)
+    #       end
+    #       alias_method :with_state, :with_states
+    #       
+    #       def without_states(*values)
+    #         all(:state.not => values.flatten)
+    #       end
+    #       alias_method :without_state, :without_states
+    #     end
+    #   end
+    # 
+    # Because of the way scopes work in DataMapper, they can be chained like
+    # so:
+    # 
+    #   Vehicle.with_state('parked').all(:order => [:id.desc])
+    # 
+    # == Callbacks / Observers
+    # 
+    # All before/after transition callbacks defined for DataMapper resources
+    # behave in the same way that other DataMapper hooks behave.  Rather than
+    # passing in the record as an argument to the callback, the callback is
+    # instead bound to the object and evaluated within its context.
+    # 
+    # For example,
+    # 
+    #   class Vehicle
+    #     include DataMapper::Resource
+    #     
+    #     property :id, Serial
+    #     property :state, String
+    #     
+    #     state_machine :initial => 'parked' do
+    #       before_transition :to => 'idling' do
+    #         put_on_seatbelt
+    #       end
+    #       
+    #       before_transition do |transition|
+    #         # log message
+    #       end
+    #       
+    #       event :ignite do
+    #         transition :to => 'idling', :from => 'parked'
+    #       end
+    #     end
+    #     
+    #     def put_on_seatbelt
+    #       ...
+    #     end
+    #   end
+    # 
+    # Note, also, that the transition can be accessed by simply defining
+    # additional arguments in the callback block.
+    # 
+    # In addition to support for DataMapper-like hooks, there is additional
+    # support for DataMapper observers.  See StateMachine::Integrations::DataMapper::Observer
+    # for more information.
+    module DataMapper
+      # Should this integration be used for state machines in the given class?
+      # Classes that include DataMapper::Resource will automatically use the
+      # DataMapper integration.
+      def self.matches?(klass)
+        defined?(::DataMapper::Resource) && klass <= ::DataMapper::Resource
+      end
+      
+      # Loads additional files specific to DataMapper
+      def self.extended(base) #:nodoc:
+        require 'state_machine/integrations/data_mapper/observer'
+      end
+      
+      # Runs a new database transaction, rolling back any changes if the
+      # yielded block fails (i.e. returns false).
+      def within_transaction(object)
+        object.class.transaction {|t| t.rollback unless yield}
+      end
+      
+      protected
+        # Sets the default action for all DataMapper state machines to +save+
+        def default_action
+          :save
+        end
+        
+        # Defines a scope for finding records *with* a particular value or
+        # values for the attribute
+        def define_with_scope(name)
+          attribute = self.attribute
+          (class << owner_class; self; end).class_eval do
+            define_method(name) {|*values| all(attribute => values.flatten)}
+          end
+        end
+        
+        # Defines a scope for finding records *without* a particular value or
+        # values for the attribute
+        def define_without_scope(name)
+          attribute = self.attribute
+          (class << owner_class; self; end).class_eval do
+            define_method(name) {|*values| all(attribute.to_sym.not => values.flatten)}
+          end
+        end
+        
+        # Creates a new callback in the callback chain, always ensuring that
+        # it's configured to bind to the object as this is the convention for
+        # DataMapper/Extlib callbacks
+        def add_callback(type, options, &block)
+          options[:bind_to_object] = true
+          super
+        end
+    end
+  end
+end

data/lib/state_machine/integrations/data_mapper/observer.rb

@@ -0,0 +1,153 @@
+module StateMachine
+  module Integrations #:nodoc:
+    module DataMapper
+      # Adds support for creating before/after transition callbacks within a
+      # DataMapper observer.  These callbacks behave very similarly to
+      # before/after hooks during save/update/destroy/etc., but with the
+      # following modifications:
+      # * Each callback can define a set of transition conditions (i.e. guards)
+      # that must be met in order for the callback to get invoked.
+      # * An additional transition parameter is available that provides
+      # contextual information about the event (see StateMachine::Transition
+      # for more information)
+      # 
+      # To define a single observer for multiple state machines:
+      # 
+      #   class StateMachineObserver
+      #     include DataMapper::Observer
+      #     
+      #     observe Vehicle, Switch, Project
+      #     
+      #     after_transition do |transition, saved|
+      #       Audit.log(self, transition) if saved
+      #     end
+      #   end
+      module Observer
+        # Creates a callback that will be invoked *before* a transition is
+        # performed, so long as the given configuration options match the
+        # transition.  Each part of the transition (event, to state, from state)
+        # must match in order for the callback to get invoked.
+        # 
+        # See StateMachine::Machine#before_transition for more
+        # information about the various configuration options available.
+        # 
+        # == Examples
+        # 
+        #   class Vehicle
+        #     include DataMapper::Resource
+        #     
+        #     property :id, Serial
+        #     property :state, :String
+        #     
+        #     state_machine :initial => 'parked' do
+        #       event :ignite do
+        #         transition :to => 'idling', :from => 'parked'
+        #       end
+        #     end
+        #   end
+        #   
+        #   class VehicleObserver
+        #     include DataMapper::Observer
+        #     
+        #     observe Vehicle
+        #     
+        #     before :save do
+        #       # log message
+        #     end
+        #     
+        #     before_transition :to => 'idling', :from => 'parked', :on => 'ignite' do
+        #       # put on seatbelt
+        #     end
+        #     
+        #     before_transition do |transition|
+        #       # log message
+        #     end
+        #   end
+        # 
+        # *Note* that in each of the above +before_transition+ callbacks, the
+        # callback is executed within the context of the object (i.e. the
+        # Vehicle instance being transition).  This means that +self+ refers
+        # to the vehicle record within each callback block.
+        def before_transition(*args, &block)
+          add_transition_callback(:before, *args, &block)
+        end
+        
+        # Creates a callback that will be invoked *after* a transition is
+        # performed, so long as the given configuration options match the
+        # transition.  Each part of the transition (event, to state, from state)
+        # must match in order for the callback to get invoked.
+        # 
+        # See StateMachine::Machine#after_transition for more
+        # information about the various configuration options available.
+        # 
+        # == Examples
+        # 
+        #   class Vehicle
+        #     include DataMapper::Resource
+        #     
+        #     property :id, Serial
+        #     property :state, :String
+        #     
+        #     state_machine :initial => 'parked' do
+        #       event :ignite do
+        #         transition :to => 'idling', :from => 'parked'
+        #       end
+        #     end
+        #   end
+        #   
+        #   class VehicleObserver
+        #     include DataMapper::Observer
+        #     
+        #     observe Vehicle
+        #     
+        #     after :save do |saved|
+        #       # log message
+        #     end
+        #     
+        #     after_transition :to => 'idling', :from => 'parked', :on => 'ignite' do
+        #       # put on seatbelt
+        #     end
+        #     
+        #     after_transition do |transition, saved|
+        #       if saved
+        #         # log message
+        #       end
+        #     end
+        #   end
+        # 
+        # *Note* that in each of the above +before_transition+ callbacks, the
+        # callback is executed within the context of the object (i.e. the
+        # Vehicle instance being transition).  This means that +self+ refers
+        # to the vehicle record within each callback block.
+        def after_transition(*args, &block)
+          add_transition_callback(:after, *args, &block)
+        end
+        
+        private
+          # Adds the transition callback to a specific machine or all of the
+          # state machines for each observed class.
+          def add_transition_callback(type, *args, &block)
+            if args.first && !args.first.is_a?(Hash)
+              # Specific attribute is being targeted
+              attribute = args.first.to_s
+              transition_args = args[1..-1]
+            else
+              # Target all state machines
+              attribute = nil
+              transition_args = args
+            end
+            
+            # Add the transition callback to each class being observed
+            observing.each do |klass|
+              state_machines = attribute ? [klass.state_machines[attribute]] : klass.state_machines.values
+              state_machines.each {|machine| machine.send("#{type}_transition", *transition_args, &block)}
+            end if observing
+          end
+      end
+    end
+  end
+end
+
+DataMapper::Observer::ClassMethods.class_eval do
+  include StateMachine::Integrations::DataMapper::Observer
+end