sm
Class StateMachine

java.lang.Object
  sm.StateMachine

All Implemented Interfaces:

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

Direct Known Subclasses:

GestureStateMachine

public abstract class StateMachine

extends java.lang.Object

implements java.awt.event.ActionListener

A state machine to control the interaction with an SMCanvas.

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 labelled 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 ("sm") {
 		// 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 pressing mouse button 1..
			// (see class StateMachine.State.Transition for details).
 			Transition t1 = new Press (BUTTON1, "=> s2") {
 				public boolean guard () { ... return True or False ... }
 				public void action () { ... do something ... }
 			}
 			Transition t2 = ...
 		}
 		
 		public State s2 = new State () {
 			...
 		}
 	}
 

Author:

Caroline Appert

Nested Class Summary

class

StateMachine.State A state of a state machine.

Constructor Summary

StateMachine(java.lang.String n)
Builds a state machine.

StateMachine(java.lang.String n, InteractiveObject io)
Builds a state machine and attach it to an interactive object.

Method Summary

void	actionPerformed(java.awt.event.ActionEvent arg0)
void	addSMListener(SMStateMachineEventListener l) Adds the specified state machine event listener to receive state machine events from this state machine.
void	armTimer(int d) Arms the timer.
void	attachTo(InteractiveObject io) Attaches a state machine to a given interactive object and resets it.
void	attachTo(InteractiveObject io, boolean reset) Attaches a state machine to a given canvas.
StateMachine	consumes(boolean c) Makes this state machine consume an event.
void	detach(InteractiveObject io) Detaches a state machine from an interactive object.
void	disarmTimer() Disarms the 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.
java.util.Vector	getAllStates() Returns the vector containing all this state machine's states.
StateMachine.State	getCurrentState() Returns the this state machine's current state.
java.lang.String	getName() Returns the name of this state machine.
java.util.LinkedList	getObjects() Returns the linked list of interactive objects to which this state machine is attached, or null is the machine is not attached.
StateMachine	greaterPriorityThan(StateMachine sm) Makes this state machine have a greater priority than another state machine.
StateMachine	greatestPriority() Makes this state machine have the greatest priority.
boolean	hasConsumed() Tests if this state machine has consumed the last event it processed.
void	init() Internal initialization of the state machine: resolve the state names into their corresponding objects.
boolean	isActive() Returns the active state of this state machine.
boolean	isAttached(InteractiveObject io) Returns true if this state machine is attached to a given interactive object.
boolean	isAttachedTo(InteractiveObject io) Tests if this state machine is attached to a given interactive object.
StateMachine	lowerPriorityThan(StateMachine sm) Makes this state machine have a lower priority than another state machine.
StateMachine	lowestPriority() Makes this state machine have the lowest priority.
void	processEvent(SMVirtualEvent event) Processes in the state machine the virtual event received.
void	processEvent(SMVirtualEvent event, int modifier) Processes in the state machine the virtual event received.
void	processEvent(SMVirtualEvent event, int modifier, java.awt.geom.Point2D point) Processes in the state machine the virtual event received.
void	processEvent(SMVirtualEvent event, java.awt.geom.Point2D point) Processes in the state machine the virtual event received.
void	removeSMListener(SMStateMachineEventListener l) Removes the specified state machine event listener so that it no longer receives state machine events from this state machine.
void	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

Constructor Detail

StateMachine

public StateMachine(java.lang.String n)

Builds a state machine. The name of the machine must be unique among all state machines.

Parameters:

n - the name of the state machine.

StateMachine

public StateMachine(java.lang.String n,
                    InteractiveObject io)

Builds a state machine and attach it to an interactive object. The name of the machine must be unique among all state machines.

Parameters:

n - the name of the state machine.

io - the interactive object (SMCanvas, SMTag, SMShape) to link to this state machine.

Method Detail

lowerPriorityThan

public StateMachine lowerPriorityThan(StateMachine sm)

Makes this state machine have a lower priority than another state machine. Assume two machines m1 and m2 have priorities p1 and p2. If p1 < p2, m1 receives the event after m2 has received it.

Parameters:

sm - The state machine that must have a greater priority than this state machine.

Returns:

Returns this state machine.

lowestPriority

public StateMachine lowestPriority()

Makes this state machine have the lowest priority. This state machines will receive events after every state machine has received it.

Returns:

Returns this state machine.

greaterPriorityThan

public StateMachine greaterPriorityThan(StateMachine sm)

Makes this state machine have a greater priority than another state machine. Assume two machines m1 and m2 have priorities p1 and p2. If p1 < p2, m1 receives the event after m2 has received it.

Parameters:

sm - The state machine that must have a lower priority than this state machine.

Returns:

Returns this state machine.

greatestPriority

public StateMachine greatestPriority()

Makes this state machine have the greatest priority. This state machines will receive events before every state machine has received it.

Returns:

Returns this state machine.

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:

Returns this state machine.

hasConsumed

public boolean hasConsumed()

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

Returns:

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

getCurrentState

public StateMachine.State getCurrentState()

Returns the this state machine's current state.

Returns:

Returns the current state.

getAllStates

public java.util.Vector getAllStates()

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

Returns:

Returns the vector containing all the states.

addSMListener

public void addSMListener(SMStateMachineEventListener 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.

removeSMListener

public void removeSMListener(SMStateMachineEventListener 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.

attachTo

public void attachTo(InteractiveObject io,
                     boolean reset)

Attaches a state machine to a given canvas.

Parameters:

io - The interactive object to which this state machine must be linked

reset - Whether to reset the state machine once attached

attachTo

public void attachTo(InteractiveObject io)

Attaches a state machine to a given interactive object and resets it.

Parameters:

io - The interactive object to which this state machine must be linked

detach

public void detach(InteractiveObject io)

Detaches a state machine from an interactive object. Does nothing if it was not attached.

Parameters:

io - The interactive object to which this state machine must be detached

isAttachedTo

public boolean isAttachedTo(InteractiveObject io)

Tests if this state machine is attached to a given interactive object.

Parameters:

io - The interactive object to test

Returns:

Returns true if this state machine is attached to io.

getName

public java.lang.String getName()

Returns the name of this state machine.

Returns:

Returns the name of this state machine.

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 final void 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.

isActive

public boolean isActive()

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

Returns:

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 final void suspend()

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

setActive

public final 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.

isAttached

public boolean isAttached(InteractiveObject io)

Returns true if this state machine is attached to a given interactive object.

Parameters:

io - The interactive object to test.

Returns:

Returns true if this state machine is attached to a canvas.

getObjects

public java.util.LinkedList getObjects()

Returns the linked list of interactive objects to which this state machine is attached, or null is the machine is not attached.

Returns:

Returns the linked list of interactive objects to which this state machine is attached.

init

public void init()

Internal initialization of the state machine: resolve the state names into their corresponding objects. If not called explicitely, this is called automatically the first time a transition is fired. The only reason to call it explicitely 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)

Arms the 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.

disarmTimer

public void disarmTimer()

Disarms the timer.

processEvent

public final void processEvent(SMVirtualEvent event,
                               java.awt.geom.Point2D point)

Processes in the state machine the virtual event received.

Parameters:

event - The virtual event to process

point - The location where occured the received event

processEvent

public final void processEvent(SMVirtualEvent event,
                               int modifier,
                               java.awt.geom.Point2D point)

Processes in the state machine the virtual event received.

Parameters:

event - The virtual event to process

modifier - The modifier of the event

point - The location where occured the received event

processEvent

public final void processEvent(SMVirtualEvent event,
                               int modifier)

Processes in the state machine the virtual event received.

Parameters:

event - The virtual event to process

modifier - The modifier of the event

processEvent

public final void processEvent(SMVirtualEvent event)

Processes in the state machine the virtual event received.

Parameters:

event - The virtual event to process