de.fhg.igd.jhsm
Class HSMInterpreter

java.lang.Object
  de.fhg.igd.jhsm.HSMInterpreter

All Implemented Interfaces:

EventListener, Interpreter, Runnable, Serializable

Direct Known Subclasses:

AMoAInterpreter

public class HSMInterpreter

extends Object

implements Interpreter, Serializable

An Interpreter for generic hsm data structures. This implementation was designed to run a generic hierarchical state machine in a multi threaded environment. One thread is responsible for processing the state machine. It runs the main loop of this class until the processing is finished or interrupted externally. An arbitrary number of other threads may call the event handling method of this class. Events will be held in a queue until the main thread is ready to handle them.

Note that only one thread may run the main loop of this class or else the flow of control might be corrupted.

This implementation is intended to be used only once for a given state machine. The hsm that should be interpreted is passed to the constructor and cannot be changed later. So if the interpratation is completed the interpereter can be thrown away.

Version:

"$Id: HSMInterpreter.java 1913 2007-08-08 02:41:53Z jpeters $"

Author:

Jan Haevecker

See Also:

Serialized Form

Field Summary

private Context	context_ This corresponds to the context as defined in the Interpreter design pattern.
private State	current_ The currently active state.
private List	eventQueue_ A queue for incoming events.
private boolean	firedInternal_ A flag indicating if recently an internal transition did fire.
private static Logger	LOG
private CompositeState	root_ A referece to the root state of the state machine that is processed by this class.
private boolean	running_ A flag that indicates if this interpreter is running.
private boolean	suspended_ A flag that indicates if this interpreter is suspended.
private BooleanLock	waiting_ This tool is used to manage the wait/notify behavior of the control flow.

Constructor Summary

HSMInterpreter(CompositeState root)
Sole Constructor.

Method Summary

private void	callEntry(State current, State target, State source) Recursively calls State.entry(Context) on all states that are on a path between the current state and the target state.
private void	callExit(State current, State target, State source) Recursively calls exit() on all states that are on a path between the target state and the source state.
void	eventReceived(Event event)
private void	fireTransition(InternalTransition trans)
protected void	fireTransition(Transition trans)
Context	getContext() Returns the context that is associated with the interpreted state machine.
private State	getCurrentState() Returns the state that is currently processed.
CompositeState	getRoot() Returns the root state of the state machine that is being processed.
private boolean	processQueuedEvents(State state) Processes pending events.
private void	processState(CompositeState state)
private void	processState(FinalState state)
protected void	processState(State state)
private boolean	processTransitions(State state) Fires a triggerless transition of the current state if the guard condition is satisfied.
private boolean	processTriggeredTransitions(State state, Event event) Processes triggered transitions.
private void	queueEvent(Event event)
void	run() Runs the interpretation of the state machine.
void	setContext(Context context) Initializes the context that will be associated with all actions of the interpreted state machine.
private void	setCurrentState(State current)
private void	setTriggerEvent(Event trigger)
void	shutdown() Signals the interpreter that it should stop the interpretation as soon as possible.
void	suspend() Signals the interpreter that it should suspend the interpretation as soon as possible.
String	toString() Overwritten for debugging purposes.

Methods inherited from class java.lang.Object

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

Field Detail

LOG

private static final Logger LOG

eventQueue_

private final List eventQueue_

A queue for incoming events.

waiting_

private final BooleanLock waiting_

This tool is used to manage the wait/notify behavior of the control flow.

root_

private CompositeState root_

A referece to the root state of the state machine that is processed by this class. This composite state works as a container for the rest of the state machine.

current_

private State current_

The currently active state.

running_

private volatile boolean running_

A flag that indicates if this interpreter is running. If it becomes false the processing of the state machine will stop. This is volatile because it may be set/read by the main thread and several other (event dispatching) threads.

suspended_

private volatile boolean suspended_

A flag that indicates if this interpreter is suspended. A suspended interpreter can be resumed by calling the run() method again. This is volatile because it may be set/read by the main thread and several other (external) threads.

context_

private Context context_

This corresponds to the context as defined in the Interpreter design pattern. It may be null since a context is not needed always.

firedInternal_

private boolean firedInternal_

A flag indicating if recently an internal transition did fire.

Constructor Detail

HSMInterpreter

public HSMInterpreter(CompositeState root)

Sole Constructor. The currently active state is set to root.

Parameters:

root - The root state of the state machine that is to be processed by this class.

Method Detail

eventReceived

public void eventReceived(Event event)

Specified by:

eventReceived in interface EventListener

getRoot

public CompositeState getRoot()

Description copied from interface: Interpreter

Returns the root state of the state machine that is being processed.

Specified by:

getRoot in interface Interpreter

Returns:

The root state of the state machine. This can be regarded as a simple container for the state machine. It is not a state in it's original definition.

run

public void run()

Description copied from interface: Interpreter

Runs the interpretation of the state machine. This is also called to start the interpretation.

Specified by:

run in interface Interpreter

suspend

public void suspend()

Description copied from interface: Interpreter

Signals the interpreter that it should suspend the interpretation as soon as possible.

Specified by:

suspend in interface Interpreter

shutdown

public void shutdown()

Description copied from interface: Interpreter

Signals the interpreter that it should stop the interpretation as soon as possible.

Specified by:

shutdown in interface Interpreter

toString

public String toString()

Overwritten for debugging purposes.

callEntry

private void callEntry(State current,
                       State target,
                       State source)

Recursively calls State.entry(Context) on all states that are on a path between the current state and the target state. The path is a sequence of states that lie between current and target in an inorder traversal of the state hierarchy.

Parameters:

current - The state that is currently processed by this method. This is replaced during recursion.

target - Terminates the sequence of states (and the recursion).

source - The beginning of the sequence of states.

callExit

private void callExit(State current,
                      State target,
                      State source)

Recursively calls exit() on all states that are on a path between the target state and the source state. The path is a sequence of states that lie between current and target in an inorder traversal of the state hierarchy.

Parameters:

current - The state that is currently processed by this method. This is replaced during recursion.

target - Terminates the sequence of states (and the recursion).

source - The beginning of the sequence of states.

getCurrentState

private State getCurrentState()

Returns the state that is currently processed.

fireTransition

private void fireTransition(InternalTransition trans)

fireTransition

protected void fireTransition(Transition trans)

processState

protected void processState(State state)

processState

private void processState(CompositeState state)

processState

private void processState(FinalState state)

processTransitions

private boolean processTransitions(State state)

Fires a triggerless transition of the current state if the guard condition is satisfied.

processQueuedEvents

private boolean processQueuedEvents(State state)

Processes pending events. It is checked wether a queued event is a trigger event for one of the transitions of the current state.

Note: Access to the event queue is not synchronized here! This must be done externally.

Parameters:

state - The state whose transitions will be checked.

Returns:

true if an event did trigger a transition, false else.

processTriggeredTransitions

private boolean processTriggeredTransitions(State state,
                                            Event event)

Processes triggered transitions. It is checked wether the given event is a trigger event for one of the transitions of the current state. If no transition fires from the current state, all inherited transitions are checked.

Parameters:

event - The event that might be a trigger for a transition.

state - The state whose transitions will be checked.

Returns:

true if the event did trigger a transition, false else.

queueEvent

private void queueEvent(Event event)

setCurrentState

private void setCurrentState(State current)

setContext

public void setContext(Context context)

Description copied from interface: Interpreter

Initializes the context that will be associated with all actions of the interpreted state machine.

The context does not necessarily have to be set. There are cases in which a global context is not needed. However, if the context is set, it must remain fixed!

Specified by:

setContext in interface Interpreter

Parameters:

context - The context that will be associated with all actions.

getContext

public Context getContext()

Description copied from interface: Interpreter

Returns the context that is associated with the interpreted state machine.

Specified by:

getContext in interface Interpreter

Returns:

The context that is associated with all actions.

setTriggerEvent

private void setTriggerEvent(Event trigger)