ch.awae.utils.statemachine

Interface StateMachine

public interface StateMachine

Base representation of a state machine or a cluster of state machines.

A state machine consists of a set of states and transition rules between those states. Transitions are triggered by events. Events can be issued through event(String) A transition always has a target state (i.e. the state the state machine should switch to during the transition) and a set of side effects. These can be further events to be triggered or commands that should be issued. Events (both external and internal) are collected in an event queue and processed asynchronously by the state machine. Commands triggered by transitions are collected in a command queue that is accessible from outside the state machine. This allows user code to collect these commands and to process them. A cluster of state machines is handled similarly to a single state machine but with multiple active states at once (i.e. one active state per state machine) and all events are applied to all internal state machines. Commands issued by any of the internal state machines are all collected in a common command queue.

State machines must be started to be able to process events. Use start() and stop() to start or stop the state machine. A stopped state machine can be restarted at any time. Restarting a state machine simply resumes operation. A state machine can also be reset to the initial state by calling reset(). A reset will clear the event queue and revert and reinitialise the state machine to its initial state. The command queue remains unaffected as it is not considered as integral a part to the state machine as the event queue is.

State machines have built in logging support using java.util.logging.Logger. All logging is done using the logger ch.awae.utils.statemachine.StateMachine. For the logging the following levels are used:

• SEVERE - a machine core failed to instantiate
• WARNING - a machine core that allows terminal states has a terminal state (which is discouraged)
• CONFIG - machine configuration summary on state machine creation
• FINE - major events in the lifecycle of the state machine (e.g. worker thread started/stopped, a state change in a core)
• FINER/FINEST - detailed data for every action taken on a state machine or core

Note: state machines cannot be combined into a cluster as all machines in a cluster share a common event queue. Clusters must be constructed directly.

Since:

awaeUtils 0.0.3

Version:

1.2 (0.0.5)

Author:

Andreas Wälchli

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	StateMachine.SavedState root interface for saved state of state machines.

Method Summary

Modifier and Type	Method and Description
void	event(java.lang.String event) Adds a new event to the internal event queue
java.lang.String	extractDiagram() Creates a graphviz (dot) compatible graph from the state machine.
java.util.concurrent.BlockingQueue<java.lang.String>	getCommandQueue() Provides the command queue associated with the state machine.
StateMachine.SavedState	getCurrentState() Creates a SavedState instance representing the current state of the state machine.
java.lang.String	getUUID() provides the UUID of the state machine
void	loadState(StateMachine.SavedState state, boolean clear) Loads the state represented by a given SavedState instance and sets the state machine to that state.
void	reset() Resets the state machine to its initial state and clears the event queue.
void	start() Starts processing of the state machine event queue.
void	stop() Stops processing of the state machine event queue.

Method Detail

event

void event(java.lang.String event)

Adds a new event to the internal event queue

Parameters:

event - the event to issue. may not be null

Throws:

java.lang.NullPointerException - event is null

getCommandQueue

java.util.concurrent.BlockingQueue<java.lang.String> getCommandQueue()

Provides the command queue associated with the state machine. Use BlockingQueue.take() on the queue to access the commands.

Returns:

the command queue

start

void start()

Starts processing of the state machine event queue.

Throws:

java.lang.IllegalStateException - the state machine is already running

stop

void stop()

Stops processing of the state machine event queue. This method blocks until the processing thread has terminated.

Throws:

java.lang.IllegalStateException - the state machine is not running

reset

void reset()

Resets the state machine to its initial state and clears the event queue. Unprocessed events are discarded. Note that this method will not block any calls to event(String) while the reset is in progress.

extractDiagram

java.lang.String extractDiagram()

Creates a graphviz (dot) compatible graph from the state machine.

Returns:

a dot graph string

Since:

1.2 (0.0.5)

getUUID

java.lang.String getUUID()

provides the UUID of the state machine

Returns:

the uuid

Since:

1.2 (0.0.5)

getCurrentState

StateMachine.SavedState getCurrentState()

Creates a SavedState instance representing the current state of the state machine. The saving process may temporarily block the state machine.

Returns:

the saved state

Since:

1.2 (0.0.5)

loadState

void loadState(StateMachine.SavedState state,
               boolean clear)

Loads the state represented by a given SavedState instance and sets the state machine to that state. It can also be chosen if the state machine should be reset (i.e. the event queue cleared) during the load.

Parameters:

state - the saved state

clear - true if the event queue should be cleared.

Throws:

java.lang.NullPointerException - the state is null

java.lang.IllegalArgumentException - the state is not compatible with this state machine instance.

Since:

1.2 (0.0.5)