Usage

This page describes the construction and use of a Tron Finite State Machine

---

FsmExecutor interface

The FsmExecutor interface provides convenient access to the current FSM within the implementation. Simply extend this interface on your transitions interface, and then one can call fsm(), rather than Fsm.thisFsm() and context(), rather than Fsm.thisContext().

Construction

The construction of an Fsm is done via a static factory method on the Fsm class:

 /**
 * Construct a new instance of a finite state machine.
 * 
 * @param fsmContext
 *            - the object used as the action context for this FSM
 * @param transitions
 *            - the interface class used to define the transitions for this
 *            FSM
 * @param initialState
 *            - the initial state of the FSM
 * @param sync
 *            - true if this FSM is to synchronize state transitions. This
 *            is required for multi-threaded use of the FSM
 * @return the Fsm instance
 */
public static <Context, Transitions> Fsm<Context, Transitions> construct(Context fsmContext,
                                                                         Class<Transitions> transitions,
                                                                         Enum<?> initialState,
                                                                         boolean sync)

For example:

MyContext context = ....
Fsm<MyContext, MyFsm> fsm = Fsm.construct(context, MyFsm.class, Protocol.Initial, true);

In this example, the fsm is constructed using the context instance, MyFsm as the transitions interface definition, using the Protocol.Initial as the initial state of the FSM, and will synchronize state transitions of the FSM.

FSM API

The Fsm class defines the following public methods:

public void enterStartState()
public Context getContext()
public Transitions getCurrentState()
public Logger getLog()
public Transitions getPreviousState()
public String getTransition()
public Transitions getTransitions()
public Transitions pop()
public void push(Transitions state)
public void setLog(Logger log)

The enterStartState() method executes the entry action of the initial state of the FSM. When the Fsm is constructed, the current state of the Fsm is set to the initial state you passed into construction method. However, the @Entry of this action - if defined - is not evaluated. This is done to allow you to control this during your own initialization, as you won't have the constructed Fsm until the construction is finished and you may well need this when the @Entry action of the initial state is evaluated.

The getContext() method returns the context object you passed in during construction.

The getCurrentState() method returns the current state of the Fsm. Note that this is not thread safe.

The getLog() method returns the log used by this Fsm instance.

The getPreviousState() method returns the previous state of the Fsm, or null if there was none (for example, right after construction. Note that this method is not thread safe.

The getTransition() method returns the String representation of the transition fired on the previous state that resulted in the current state of the Fsm. Note that this method is not thread safe.

The getTransitions() method returns the Fsm transitions proxy that implements Transitions interface. This is the object you use to fire transitions on the Fsm.

The pop() method pops the state stack of the Fsm, and returns a transitions proxy that may be used to send a transition to the return state of the Fsm. This is used in Pop Transitions. Note that the actual pop does not occur after this method returns - i.e. the Fsm is still in the same current state as before this method is executed. Rather, the pop occurs after the current transition has fired. You may only pop once per transition firing.

The push(Transitions state) method pushes the current state of the Fsm onto the state stack, and the supplied state becomes the current state of the Fsm. This is used in Push Transitions. Note that the actual push does not occur after this method returns - i.e. the Fsm is still in the same current state as before this method is executed. Rather, the push occurs after the current transition has fired. You may only push once per transition firing.

Note that push() and pop() are mutually exclusive. You cannot push() and pop() in the same transition.

The setLog(Logger log) sets the logger for this Fsm instance. Log messages within the Fsm implementation will appear on this log. If no log is set, the default logger for the Fsm class is used.