Class StateMachine::Transition
In: lib/state_machine/transition.rb
Parent: Object

A transition represents a state change for a specific attribute.

Transitions consist of:

  • An event
  • A starting state
  • An ending state

Methods

Attributes

args  [RW]  The arguments passed in to the event that triggered the transition (does not include the run_action boolean argument if specified)
event  [R]  The event that triggered the transition
from  [R]  The original state value before the transition
from_name  [R]  The original state name before the transition
machine  [R]  The state machine for which this transition is defined
object  [R]  The object being transitioned
qualified_event  [R]  The fully-qualified name of the event that triggered the transition
qualified_from_name  [R]  The original fully-qualified state name before transition
qualified_to_name  [R]  The new fully-qualified state name after the transition
result  [R]  The result of invoking the action associated with the machine
to  [R]  The new state value after the transition
to_name  [R]  The new state name after the transition

Public Class methods

Runs one or more transitions in parallel. All transitions will run through the following steps:

  1. Before callbacks
  2. Persist state
  3. Invoke action
  4. After callbacks (if configured)
  5. Rollback (if action is unsuccessful)

Configuration options:

If a block is passed to this method, that block will be called instead of invoking each transition‘s action.

Runs one or more transitions within a transaction. See StateMachine::Transition.perform for more information.

Public Instance methods

The action that will be run when this transition is performed

Runs the machine‘s after callbacks for this transition. Only callbacks that are configured to match the event, from state, and to state will be invoked.

The result can be used to indicate whether the associated machine action was executed successfully.

Once the callbacks are run, they cannot be run again until this transition is reset.

Halting

If any callback throws a :halt exception, it will be caught and the callback chain will be automatically stopped. However, this exception will not bubble up to the caller since after callbacks should never halt the execution of a perform.

Example

  class Vehicle
    state_machine do
      after_transition :on => :ignite, :do => lambda {|vehicle| ...}

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

  vehicle = Vehicle.new
  transition = StateMachine::Transition.new(vehicle, Vehicle.state_machine, :ignite, :parked, :idling)
  transition.after(true)

The attribute which this transition‘s machine is defined for

A hash of all the core attributes defined for this transition with their names as keys and values of the attributes as values.

Example

  machine = StateMachine.new(Vehicle)
  transition = StateMachine::Transition.new(Vehicle.new, machine, :ignite, :parked, :idling)
  transition.attributes   # => {:object => #<Vehicle:0xb7d60ea4>, :attribute => :state, :event => :ignite, :from => 'parked', :to => 'idling'}

Runs the machine‘s before callbacks for this transition. Only callbacks that are configured to match the event, from state, and to state will be invoked.

Once the callbacks are run, they cannot be run again until this transition is reset.

Example

  class Vehicle
    state_machine do
      before_transition :on => :ignite, :do => lambda {|vehicle| ...}
    end
  end

  vehicle = Vehicle.new
  transition = StateMachine::Transition.new(vehicle, machine, :ignite, :parked, :idling)
  transition.before

Generates a nicely formatted description of this transitions‘s contents.

For example,

  transition = StateMachine::Transition.new(object, machine, :ignite, :parked, :idling)
  transition   # => #<StateMachine::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>

Does this transition represent a loopback (i.e. the from and to state are the same)

Example

  machine = StateMachine.new(Vehicle)
  StateMachine::Transition.new(Vehicle.new, machine, :park, :parked, :parked).loopback?   # => true
  StateMachine::Transition.new(Vehicle.new, machine, :park, :idling, :parked).loopback?   # => false

Runs the actual transition and any before/after callbacks associated with the transition. The action associated with the transition/machine can be skipped by passing in false.

Examples

  class Vehicle
    state_machine :action => :save do
      ...
    end
  end

  vehicle = Vehicle.new
  transition = StateMachine::Transition.new(vehicle, machine, :ignite, :parked, :idling)
  transition.perform          # => Runs the +save+ action after setting the state attribute
  transition.perform(false)   # => Only sets the state attribute

Transitions the current value of the state to that specified by the transition. Once the state is persisted, it cannot be persisted again until this transition is reset.

Example

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

  vehicle = Vehicle.new
  transition = StateMachine::Transition.new(vehicle, Vehicle.state_machine, :ignite, :parked, :idling)
  transition.persist

  vehicle.state   # => 'idling'

Resets any tracking of which callbacks have already been run and whether the state has already been persisted

Rolls back changes made to the object‘s state via this transition. This will revert the state back to the from value.

Example

  class Vehicle
    state_machine :initial => :parked do
      event :ignite do
        transition :parked => :idling
      end
    end
  end

  vehicle = Vehicle.new     # => #<Vehicle:0xb7b7f568 @state="parked">
  transition = StateMachine::Transition.new(vehicle, Vehicle.state_machine, :ignite, :parked, :idling)

  # Persist the new state
  vehicle.state             # => "parked"
  transition.persist
  vehicle.state             # => "idling"

  # Roll back to the original state
  transition.rollback
  vehicle.state             # => "parked"

Runs a block within a transaction for the object being transitioned. By default, transactions are a no-op unless otherwise defined by the machine‘s integration.

Protected Instance methods

Runs the callbacks of the given type for this transition. This will only invoke callbacks that exactly match the event, from state, and to state that describe this transition.

Additional callback parameters can be specified. By default, this transition is also passed into callbacks.

Gets a hash of the context defining this unique transition (including event, from state, and to state).

Example

  machine = StateMachine.new(Vehicle)
  transition = StateMachine::Transition.new(Vehicle.new, machine, :ignite, :parked, :idling)
  transition.context    # => {:on => :ignite, :from => :parked, :to => :idling}

[Validate]