fr.lri.swingstates.sm
Class StateMachine

java.lang.Object
  fr.lri.swingstates.sm.StateMachine

All Implemented Interfaces:

StateMachineListener, java.awt.event.ActionListener, java.util.EventListener

Direct Known Subclasses:

BasicInputStateMachine

public abstract class StateMachine
extends java.lang.Object
implements java.awt.event.ActionListener, StateMachineListener

A state machine consists of a set of states and a set of transitions. Each transition goes from an input state to an output state (which can be the same), and is labeled by an event, an optional guard and an optional action. At any one time, the machine is one of its states, called the current state. When the state machine receives an event, it looks for the first outgoing transition of the current state that matches the event and whose guard method returns True. If it finds such a transition, it fires it, i.e. it calls the current state's leave() method, then the transition's action() method, finally sets the current state to the transition's output state and calls the output state's enter() method. If no transition matches, the event is simply ignored.

The declaration of a state machine uses Java's anonymous class as follows:

• the state machine is the instance of an anonymous subclass of StateMachine, whose body contains one field per state;
• each state is an instance of an anonymous subclass of State, whose body contains one field per outgoing transition of this state;
• each transition is an instance of an anonymous subclass of Transition, whose body contain the optional guard and action methods;

Since we are using anonymous classes, each state machine, state and transition can contain its own fields and methods, if needed. Note also that since we are using the nesting of anonymous classes, transitions have access to the fields and methods of the enclosing state and state machine, and states have access to the fields and methods of the enclosing state machine.

In summary, the structure of a state machine is as follows:

        StateMachine sm = new StateMachine () {
                // local fields and methods if needed
                ...
                public State s1 = new State () {
                        // local fields and methods if needed
                        ...
                        public void enter () { ... do something when entering this state ... } // optional
                        public void leave () { ... do something when leaving this state ...} // optional
                        
                        // declare a transition to state s2 when receiving an event "anEvent"..
                        // (see class StateMachine.State.Transition for details).
                        Transition t1 = new Event ("anEvent", ">> s2") {
                                public boolean guard () { ... return True or False ... }
                                public void action () { ... do something ... }
                        }
                        Transition t2 = ...
                }
                
                public State s2 = new State () {
                        ...
                }
        }
 

Author:

Caroline Appert and Michel Beaudouin-Lafon

Field Summary

static java.lang.String

TIME_OUT The key string of events that triggered AnimationStopped transitions.

Constructor Summary

StateMachine()
Builds a state machine.

Method Summary

void	actionPerformed(java.awt.event.ActionEvent arg0)
void	addStateMachineListener(StateMachineEventListener l) Adds the specified state machine event listener to receive state machine events from this state machine.
void	addStateMachineListener(StateMachineListener listener) Adds the specified state machine listener to receive events fired by this state machine.
void	armTimer(int d, boolean repeat) Arms the default timer.
void	armTimer(java.lang.String tag, int d, boolean repeat) Arms a tagged timer.
StateMachine	consumes(boolean c) Makes this state machine consume an event.
void	disarmTimer() Disarms the timer.
void	disarmTimer(java.lang.String tag) Disarms a tagged timer.
void	doReset() Method called when this state machine is reset.
void	doResume() Method called when this state machine is resumed.
void	doSuspend() Method called when this state machine is suspended.
void	eventOccured(java.util.EventObject eventObject) Invoked when the state machine has fired an event.
void	fireEvent(java.util.EventObject event) Makes this state machine fire an event that will be heard by all its StateMachineListener.
void	fireEvent(java.lang.String nameEvent) Makes this state machine fire a virtual event having a given name that will be heard by all its StateMachineListener.
java.util.Vector<State>	getAllStates() Returns the vector containing all this state machine's states.
State	getCurrentState() Returns this state machine's current state.
State	getInitialState() Returns this state machine's initial state.
State	getState(java.lang.String s) Look up a state by its name.
boolean	hasConsumed() Tests if this state machine has consumed the last event it processed.
void	init() This method is called by the constructor of a state machine.
void	initStatesAndTransitions() Internal initialization of the state machine: resolve the state names into their corresponding objects.
boolean	isActive() Returns the active state of this state machine.
void	processEvent(java.util.EventObject event) Processes in the state machine the virtual event received.
void	processEvent(java.lang.String event) Processes in the state machine a virtual event having a given name.
void	removeStateMachineListener(StateMachineEventListener l) Removes the specified state machine event listener so that it no longer receives state machine events from this state machine.
void	removeStateMachineListener(StateMachineListener listener) Removes the specified state machine listener.
StateMachine	reset() Sets the state of this state machine to the initial state.
void	resume() Makes this state machine active.
void	setActive(boolean active) Makes this state machine be active or inactive (calls resume or suspend).
void	suspend() Makes this state machine inactive.

Methods inherited from class java.lang.Object

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

Field Detail

TIME_OUT

public static java.lang.String TIME_OUT

The key string of events that triggered AnimationStopped transitions.

Constructor Detail

StateMachine

public StateMachine()

Builds a state machine.

Method Detail

consumes

public StateMachine consumes(boolean c)

Makes this state machine consume an event. Any state machine having a lower priority than this state machines will not receive the event that this state machine is being processing.

Parameters:

c - True if this state machine must consume this event, false otherwise.

Returns:

this state machine.

hasConsumed

public boolean hasConsumed()

Tests if this state machine has consumed the last event it processed.

Returns:

true if this state machine has consumed the last event it processed, false otherwise.

getCurrentState

public State getCurrentState()

Returns this state machine's current state.

Returns:

the current state.

getInitialState

public State getInitialState()

Returns this state machine's initial state.

Returns:

the initial state.

getAllStates

public java.util.Vector<State> getAllStates()

Returns the vector containing all this state machine's states.

Returns:

the vector containing all the states.

addStateMachineListener

public void addStateMachineListener(StateMachineEventListener l)

Adds the specified state machine event listener to receive state machine events from this state machine. State machine events occur when a this state machine is attached, detached, resumed, reset, suspended, goes to another state or loops on the current state. If l is null, no exception is thrown and no action is performed.

Parameters:

l - The state machine event listener to add.

removeStateMachineListener

public void removeStateMachineListener(StateMachineEventListener l)

Removes the specified state machine event listener so that it no longer receives state machine events from this state machine. State machine events occur when a this state machine is attached, detached, resumed, reset, suspended, goes to another state or loops on the current state. If l is null, no exception is thrown and no action is performed.

Parameters:

l - The state machine event listener to remove.

doReset

public void doReset()

Method called when this state machine is reset. This method does nothing. It can be redefined in derived classes.

See Also:

reset()

reset

public StateMachine reset()

Sets the state of this state machine to the initial state. The initial state is the first state in the order of the declarations.

Returns:

this state machine.

isActive

public boolean isActive()

Returns the active state of this state machine. The machine is active unless suspend() has been called.

Returns:

the active state of this state machine.

doSuspend

public void doSuspend()

Method called when this state machine is suspended. This method does nothing. It can be redefined in derived classes.

See Also:

suspend()

suspend

public void suspend()

Makes this state machine inactive. When a state machine is inactive, it does not process events.

setActive

public void setActive(boolean active)

Makes this state machine be active or inactive (calls resume or suspend).

Parameters:

active - True to makes this state machine be active, false to makes this state machine be inactive.

See Also:

resume(), suspend()

doResume

public void doResume()

Method called when this state machine is resumed. This method does nothing. It can be redefined in derived classes.

See Also:

resume()

resume

public void resume()

Makes this state machine active. When a state machine is active, it processes events.

init

public void init()

This method is called by the constructor of a state machine. By default, it does nothing. Override it to specify required variables initializations for a specific machine.

initStatesAndTransitions

public void initStatesAndTransitions()

Internal initialization of the state machine: resolve the state names into their corresponding objects. If not called explicitly, this is called automatically the first time a transition is fired. The only reason to call it explicitly is to avoid a delay when it is called automatically.

actionPerformed

public void actionPerformed(java.awt.event.ActionEvent arg0)

Specified by:

actionPerformed in interface java.awt.event.ActionListener

armTimer

public void armTimer(int d,
                     boolean repeat)

Arms the default timer. When the timer expires, a TimeOut event is sent to the state machine. Each state machine has a single timer. Calling armTimer before it has expired effectively rearms it.

Parameters:

d - the delay of the timer.

repeat - If false, only one TimeOut event is fired. If true, a TimeOut event is fired every d milliseconds.

armTimer

public void armTimer(java.lang.String tag,
                     int d,
                     boolean repeat)

Arms a tagged timer. When the timer expires, a TimeOut event is sent to the state machine. Calling armTimer before it has expired effectively rearms it.

Parameters:

tag - the tag.

d - the delay of the timer.

repeat - If false, only one TimeOut event is fired. If true, a TimeOut event is fired every d milliseconds.

disarmTimer

public void disarmTimer()

Disarms the timer.

disarmTimer

public void disarmTimer(java.lang.String tag)

Disarms a tagged timer.

Parameters:

tag - the tag.

addStateMachineListener

public void addStateMachineListener(StateMachineListener listener)

Adds the specified state machine listener to receive events fired by this state machine. Use the method sendEvent to make a state machine fire an event.

Parameters:

listener - The state machine listener to add.

See Also:

fireEvent(EventObject), removeStateMachineListener(StateMachineEventListener)

removeStateMachineListener

public void removeStateMachineListener(StateMachineListener listener)

Removes the specified state machine listener.

Parameters:

listener - The state machine listener to remove.

fireEvent

public void fireEvent(java.lang.String nameEvent)

Makes this state machine fire a virtual event having a given name that will be heard by all its StateMachineListener.

Parameters:

nameEvent - The name of the VirtualEvent to fire.

fireEvent

public void fireEvent(java.util.EventObject event)

Makes this state machine fire an event that will be heard by all its StateMachineListener.

Parameters:

event - The event to fire.

See Also:

addStateMachineListener(StateMachineEventListener)

eventOccured

public void eventOccured(java.util.EventObject eventObject)

Invoked when the state machine has fired an event.

Specified by:

eventOccured in interface StateMachineListener

Parameters:

eventObject - the event.

processEvent

public void processEvent(java.lang.String event)

Processes in the state machine a virtual event having a given name.

Parameters:

event - The name of the virtual event to process

processEvent

public void processEvent(java.util.EventObject event)

Processes in the state machine the virtual event received.

Parameters:

event - The virtual event to process

getState

public State getState(java.lang.String s)
               throws StateNotFoundException

Look up a state by its name. The state's name can be set explicitly when creating it (new State("myState")), otherwise the state name is the name of the field where it is stored in the state machine (public State myState = new State()). Note that for this to work, the field must be declared public.

Parameters:

s - the name of the state to look up

Returns:

the state object

Throws:

StateNotFoundException - if the state is not found in this machine.