Class: StateMachine::Machine

Represents a state machine for a particular attribute. State machines consist of states, events and a set of transitions that define how the state changes after a particular event is fired.

A state machine will not know all of the possible states for an object unless they are referenced somewhere in the state machine definition. As a result, any unused states should be defined with the other_states or state helper.

Actions

When an action is configured for a state machine, it is invoked when an object transitions via an event. The success of the event becomes dependent on the success of the action. If the action is successful, then the transitioned state remains persisted. However, if the action fails (by returning false), the transitioned state will be rolled back.

For example,

  class Vehicle
    attr_accessor :fail, :saving_state

    state_machine :initial => :parked, :action => :save do
      event :ignite do
        transition :parked => :idling
      end

      event :park do
        transition :idling => :parked
      end
    end

    def save
      @saving_state = state
      fail != true
    end
  end

  vehicle = Vehicle.new     # => #<Vehicle:0xb7c27024 @state="parked">
  vehicle.save              # => true
  vehicle.saving_state      # => "parked" # The state was "parked" was save was called

  # Successful event
  vehicle.ignite            # => true
  vehicle.saving_state      # => "idling" # The state was "idling" when save was called
  vehicle.state             # => "idling"

  # Failed event
  vehicle.fail = true
  vehicle.park              # => false
  vehicle.saving_state      # => "parked"
  vehicle.state             # => "idling"

As shown, even though the state is set prior to calling the save action on the object, it will be rolled back to the original state if the action fails. Note that this will also be the case if an exception is raised while calling the action.

Indirect transitions

In addition to the action being run as the result of an event, the action can also be used to run events itself. For example, using the above as an example:

  vehicle = Vehicle.new           # => #<Vehicle:0xb7c27024 @state="parked">

  vehicle.state_event = 'ignite'
  vehicle.save                    # => true
  vehicle.state                   # => "idling"
  vehicle.state_event             # => nil

As can be seen, the save action automatically invokes the event stored in the state_event attribute (:ignite in this case).

One important note about using this technique for running transitions is that if the class in which the state machine is defined also defines the action being invoked (and not a superclass), then it must manually run the StateMachine hook that checks for event attributes.

For example, in ActiveRecord, DataMapper, and Sequel, the default action (save) is already defined in a base class. As a result, when a state machine is defined in a model / resource, StateMachine can automatically hook into the save action.

On the other hand, the Vehicle class from above defined its own save method (and there is no save method in its superclass). As a result, it must be modified like so:

    def save
      self.class.state_machines.fire_event_attributes(self, :save) do
        @saving_state = state
        fail != true
      end
    end

This will add in the functionality for firing the event stored in the state_event attribute.

Callbacks

Callbacks are supported for hooking before and after every possible transition in the machine. Each callback is invoked in the order in which it was defined. See StateMachine::Machine#before_transition and StateMachine::Machine#after_transition for documentation on how to define new callbacks.

Note that callbacks only get executed within the context of an event. As a result, if a class has an initial state when it‘s created, any callbacks that would normally get executed when the object enters that state will not get triggered.

For example,

  class Vehicle
    state_machine :initial => :parked do
      after_transition all => :parked do
        raise ArgumentError
      end
      ...
    end
  end

  vehicle = Vehicle.new   # => #<Vehicle id: 1, state: "parked">
  vehicle.save            # => true (no exception raised)

If you need callbacks to get triggered when an object is created, this should be done by either:

Use a before :save or equivalent hook, or
Set an initial state of nil and use the correct event to create the object with the proper state, resulting in callbacks being triggered and the object getting persisted

Canceling callbacks

Callbacks can be canceled by throwing :halt at any point during the callback. For example,

  ...
  throw :halt
  ...

If a before callback halts the chain, the associated transition and all later callbacks are canceled. If an after callback halts the chain, the later callbacks are canceled, but the transition is still successful.

Note that if a before callback fails and the bang version of an event was invoked, an exception will be raised instead of returning false. For example,

  class Vehicle
    state_machine :initial => :parked do
      before_transition any => :idling, :do => lambda {|vehicle| throw :halt}
      ...
    end
  end

  vehicle = Vehicle.new
  vehicle.park        # => false
  vehicle.park!       # => StateMachine::InvalidTransition: Cannot transition state via :park from "idling"

Observers

Observers, in the sense of external classes and not Ruby‘s Observable mechanism, can hook into state machines as well. Such observers use the same callback api that‘s used internally.

Below are examples of defining observers for the following state machine:

  class Vehicle
    state_machine do
      event :park do
        transition :idling => :parked
      end
      ...
    end
    ...
  end

Event/Transition behaviors:

  class VehicleObserver
    def self.before_park(vehicle, transition)
      logger.info "#{vehicle} instructed to park... state is: #{transition.from}, state will be: #{transition.to}"
    end

    def self.after_park(vehicle, transition, result)
      logger.info "#{vehicle} instructed to park... state was: #{transition.from}, state is: #{transition.to}"
    end

    def self.before_transition(vehicle, transition)
      logger.info "#{vehicle} instructed to #{transition.event}... #{transition.attribute} is: #{transition.from}, #{transition.attribute} will be: #{transition.to}"
    end

    def self.after_transition(vehicle, transition)
      logger.info "#{vehicle} instructed to #{transition.event}... #{transition.attribute} was: #{transition.from}, #{transition.attribute} is: #{transition.to}"
    end
  end

  Vehicle.state_machine do
    before_transition :on => :park, :do => VehicleObserver.method(:before_park)
    before_transition VehicleObserver.method(:before_transition)

    after_transition :on => :park, :do => VehicleObserver.method(:after_park)
    after_transition VehicleObserver.method(:after_transition)
  end

One common callback is to record transitions for all models in the system for auditing/debugging purposes. Below is an example of an observer that can easily automate this process for all models:

  class StateMachineObserver
    def self.before_transition(object, transition)
      Audit.log_transition(object.attributes)
    end
  end

  [Vehicle, Switch, Project].each do |klass|
    klass.state_machines.each do |attribute, machine|
      machine.before_transition StateMachineObserver.method(:before_transition)
    end
  end

Additional observer-like behavior may be exposed by the various integrations available. See below for more information on integrations.

Overriding instance / class methods

Hooking in behavior to the generated instance / class methods from the state machine, events, and states is very simple because of the way these methods are generated on the class. Using the class‘s ancestors, the original generated method can be referred to via super. For example,

  class Vehicle
    state_machine do
      event :park do
        ...
      end
    end

    def park(*args)
      logger.info "..."
      super
    end
  end

In the above example, the park instance method that‘s generated on the Vehicle class (by the associated event) is overridden with custom behavior. Once this behavior is complete, the original method from the state machine is invoked by simply calling super.

The same technique can be used for state, state_name, and all other instance and class methods on the Vehicle class.

Integrations

By default, state machines are library-agnostic, meaning that they work on any Ruby class and have no external dependencies. However, there are certain libraries which expose additional behavior that can be taken advantage of by state machines.

This library is built to work out of the box with a few popular Ruby libraries that allow for additional behavior to provide a cleaner and smoother experience. This is especially the case for objects backed by a database that may allow for transactions, persistent storage, search/filters, callbacks, etc.

When a state machine is defined for classes using any of the above libraries, it will try to automatically determine the integration to use (Agnostic, ActiveRecord, DataMapper, or Sequel) based on the class definition. To see how each integration affects the machine‘s behavior, refer to all constants defined under the StateMachine::Integrations namespace.

Methods

add_callback
add_states
after_initialize
after_transition
attribute
before_transition
create_with_scope
create_without_scope
define_action_helpers
define_class_method
define_event_helpers
define_helpers
define_instance_method
define_scopes
define_state_accessor
define_state_initializer
define_state_predicate
draw
draw
dynamic_initial_state?
event
find_or_create
generate_message
initial_state
initial_state=
invalidate
new
on
other_states
owner_class=
read
reset
state
transaction
within_transaction
write

Included Modules

Attributes

[R]	action	The action to invoke when an object transitions
[R]	callbacks	The callbacks to invoke before/after a transition is performed Maps :before => callbacks and :after => callbacks
[RW]	default_messages
[R]	events	The events that trigger transitions. These are sorted, by default, in the order in which they were defined.
[R]	instance_helper_module
[R]	name	The name of the machine, used for scoping methods generated for the machine as a whole (not states or events)
[R]	namespace	An identifier that forces all methods (including state predicates and event methods) to be generated with the value prefixed or suffixed, depending on the context.
[RW]	owner_class	The class that the machine is defined in
[R]	states	A list of all of the states known to this state machine. This will pull states from the following sources: Initial state State behaviors Event transitions (:to, :from, and :except_from options) Transition callbacks (:to, :from, :except_to, and :except_from options) Unreferenced states (using `other_states` helper) These are sorted, by default, in the order in which they were referenced.
[R]	use_transactions	Whether the machine will use transactions when firing events

Public Class methods

draw(class_names, options = {})

Draws the state machines defined in the given classes using GraphViz. The given classes must be a comma-delimited string of class names.

Configuration options:

:file - A comma-delimited string of files to load that contain the state machine definitions to draw
:path - The path to write the graph file to
:format - The image format to generate the graph in
:font - The name of the font to draw state names in

Actions

Indirect transitions

Callbacks

Canceling callbacks

Observers

Overriding instance / class methods

Integrations

The callback

State requirements

Event requirements

Result requirements

Verbose Requirements

Conditions

Accessing the transition

Examples

Instance methods

Defining transitions

Defining additional arguments

Example

Examples

Customizing the stored value

Dynamic values

Behaviors

Invalid behaviors

State-aware class methods