org.discotools.fsm
Class Fsm

java.lang.Object
  extended by org.discotools.fsm.Fsm

public class Fsm
extends Object

Light-weight Finite State Machine (FSM) implementation.

This FSM use commands, which on successful execution, invoke a transition attempt from current state to next state.

If the FsmAction command returns true, the FSM evaluates the leave guard of current state. The transition is aborted otherwise.

If the leave guard returns true, the FSM changes getCurrentState() to next state, and the previous state is pushed to the stack of previous states.

The transition is only completed if the enter guard of next state returns true.

It the enter guard returns true, the transition returns true. Otherwise, the previous state is rolled back.

NOTE: Since current state is not updated until all guards have approved the transition, any attempt to invoke a new transition from an command, state leave or enter guard, will produce an recursive state trajectory starting at the next state of the transition invoked first.

If the last recursive transition is successful, the FSM recursively changes current state back to the previous state on the recursive state trajectory, until the next state of first transition is reached. If the last transition is unsuccessful (violated guard or FsmException was thrown), a rollback along the rescursive state trajectory is attempted. If this fails, an FsmException is thrown.

Recursive transitions can produce an infinite recursive loop if any transition along the trajectory is invoked twice. This FSM does not implement any guards against infinite recursive loops.

Author:
kengu

Constructor Summary
Fsm()
           
Fsm(FsmState current)
           
 
Method Summary
 boolean addListener(FsmListener listener)
           
 FsmTransition addTransitions(FsmState state, FsmTransition... transitions)
           
 boolean execute(String command, Object... params)
          Attempt to execute an action handling given command.
 FsmState getCurrentState()
           
 FsmState getPreviousState()
           
 List<FsmState> getPreviousStates()
           
 FsmState getState(String name)
           
 List<FsmState> getStates(String... names)
           
 FsmTransition getTransition(FsmState current, String action)
           
 Collection<FsmTransition> getTransitions(FsmState state)
           
 List<FsmTransition> getTransitions(String command)
           
 boolean removeListener(FsmListener listener)
           
 FsmState rollback(Object... params)
          Rollback FSM to previous state.
 FsmState setCurrentState(FsmState current)
           
 FsmTransition setTransitions(FsmState state, FsmTransition... transitions)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Fsm

public Fsm()

Fsm

public Fsm(FsmState current)
Method Detail

getStates

public List<FsmState> getStates(String... names)

getState

public FsmState getState(String name)

getCurrentState

public FsmState getCurrentState()

setCurrentState

public FsmState setCurrentState(FsmState current)
                         throws FsmException
Throws:
FsmException

getPreviousState

public FsmState getPreviousState()

getPreviousStates

public List<FsmState> getPreviousStates()

execute

public boolean execute(String command,
                       Object... params)
                throws FsmException
Attempt to execute an action handling given command.

If command is successfully executed, the FSM transitions to the FsmTransition.getNextState().

Parameters:
command -
params -
Returns:
true if successful.
Throws:
FsmException

rollback

public FsmState rollback(Object... params)
                  throws FsmException
Rollback FSM to previous state.

On rollback, FsmState.enter(Object...) guard is invoked on previous state. Rollback is only completed if the guard returns true. It the guard depends on specific parameters, which can not be assumed to be passed at every transition attempt, the state must cache these specific parameters internally each time the state is successfully entered. Cached parameters should only replace missing parameters.

Parameters:
params - - rollback parameters. Passed to FsmState.enter(Object...).
Returns:
Previous FsmState
Throws:
FsmException - If rollback was not allowed by FsmState.enter(Object...) guard.

getTransition

public FsmTransition getTransition(FsmState current,
                                   String action)

getTransitions

public List<FsmTransition> getTransitions(String command)
                                   throws FsmException
Throws:
FsmException

getTransitions

public Collection<FsmTransition> getTransitions(FsmState state)

addTransitions

public FsmTransition addTransitions(FsmState state,
                                    FsmTransition... transitions)

setTransitions

public FsmTransition setTransitions(FsmState state,
                                    FsmTransition... transitions)

addListener

public boolean addListener(FsmListener listener)

removeListener

public boolean removeListener(FsmListener listener)


Copyright © 2012 DISCO Foundation. All Rights Reserved.