org.sfj

Class SimpleFSM<E extends Enum<E>>

java.lang.Object

org.sfj.SimpleFSM<E>

Type Parameters:

E - Event enum

public class SimpleFSM<E extends Enum<E>>
extends Object

So, this is a simple single threaded Finite State Machine driver class.

Classically, State S and Event E yield some action, then a transition to State S'.

In this impl, the Events are defined in terms of an enum, and the States are created by name via the state(String) call; they are managed singletons. For each state you define transition handling for any interesting event types via the State.transition(). You do not have to define every transition; invalid transitions will through SimpleFSM.TransitionException.

Instead of defining the outcome state when you define the transition, the transition callback is responsible for returning the next state, or null for no change.

begin(State) sets the intitial state and primes the SM for execution. Then fire(Enum, Object...) is called as events are received. Beware, you cannot call fire() from inside a callback; the lock is not reentrant.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SimpleFSM.State<EE extends Enum<EE>> State class.
static interface	SimpleFSM.Transition<EE extends Enum<EE>> Callback interface for consumption of a event in a state, with payload.
static class	SimpleFSM.TransitionException Any exception which occurs in transition processing.

Constructor Summary

Constructors

Constructor and Description
SimpleFSM(String name, Class<E> eventClass) Create simple finite state machine driver.

Method Summary

Modifier and Type	Method and Description
void	begin(SimpleFSM.State<E> s) Prime this FSM for processing; after this, no more transitions can be specified.
String	dumpFSM() Useful dump of FSM definitions.
SimpleFSM.State<E>	fire(E event, Object... args) Fire an event.
void	fireAsynchronously(E event, Object... args) This is useful in that you can queue an event for later delivery from inside the state machine, as this will deliver the event/args from a seperate thread.
SimpleFSM.State<E>	getCurrentState() Get the current state.
Class<E>	getEventClass() Event class.
String	getName() Name of this FSM
long	getTransitionAttemptCount() Number of times a transition was attempted.
long	getTransitionFailureCount() Number of times a transition resulted in an exception
long	getTransitionNoopCount() Number of times a transition occurred without changing state.
boolean	isFrozen() Is this FSM frozen and accepting events?
SimpleFSM<E>	onException(E failEvent, SimpleFSM.Transition<E> onException) Event/transition to call on transition exception.
void	shutdown() Shutdown this FSM.
SimpleFSM.State<E>	state(String name) Define a new SimpleFSM.State by name, or retrieve the state if it exists.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SimpleFSM

public SimpleFSM(String name,
                 Class<E> eventClass)

Create simple finite state machine driver.

Parameters:

name - name

eventClass - events

Method Detail

getName

public String getName()

Name of this FSM

Returns:

name

getEventClass

public Class<E> getEventClass()

Event class.

Returns:

event class

fireAsynchronously

public void fireAsynchronously(E event,
                               Object... args)

This is useful in that you can queue an event for later delivery from inside the state machine, as this will deliver the event/args from a seperate thread.

Parameters:

event - event

args - payload

fire

public SimpleFSM.State<E> fire(E event,
                               Object... args)
                        throws SimpleFSM.TransitionException

Fire an event. Call the transition callback for the current state, for the given event, with the specified args.

Parameters:

event - event

args - payload

Returns:

resultant state

Throws:

SimpleFSM.TransitionException - on any error

onException

public SimpleFSM<E> onException(E failEvent,
                                SimpleFSM.Transition<E> onException)

Event/transition to call on transition exception. On failure processing a special transition step is called, but no stats are kept. If the exc eption transition throws an exception, it will be thrown to the user as well.

Parameters:

failEvent - event to deliver on transition exception

onException - transition to call

Returns:

this fsm

begin

public void begin(SimpleFSM.State<E> s)

Prime this FSM for processing; after this, no more transitions can be specified.

Parameters:

s - start state

getCurrentState

public SimpleFSM.State<E> getCurrentState()

Get the current state.

Returns:

current state.

state

public SimpleFSM.State<E> state(String name)

Define a new SimpleFSM.State by name, or retrieve the state if it exists.

Parameters:

name - name

Returns:

state

isFrozen

public boolean isFrozen()

Is this FSM frozen and accepting events?

Returns:

true if frozen

dumpFSM

public String dumpFSM()

Useful dump of FSM definitions.

Returns:

multiline string

shutdown

public void shutdown()

Shutdown this FSM. Does not take lock; clears all records states, sets currentState to null.

getTransitionNoopCount

public long getTransitionNoopCount()

Number of times a transition occurred without changing state.

Returns:

count

getTransitionAttemptCount

public long getTransitionAttemptCount()

Number of times a transition was attempted.

Returns:

count

getTransitionFailureCount

public long getTransitionFailureCount()

Number of times a transition resulted in an exception

Returns:

count