com.prosyst.util.asm
Class StateMachine

java.lang.Object
  com.prosyst.util.asm.StateMachine

Direct Known Subclasses:

XMLStateMachine

public class StateMachine
extends java.lang.Object

The StateMachine is NFA (non-deterministic Finite State Machine) implementation. The difference, compared to the DFA, is that the state transitions depends not only on the current input event, but also on an arbitrary number of subsequent input events. Until these subsequent events occur it is not possible to determine which state the machine is in. Without theory, here are some important definitions:

• State - a state machine features many states but at one time, it might be in only ONE of that states.
• Transitions - are rules that describe how the state is changed.
• Guard Condition - is a special condition that must be fulfilled in order to start the transition to which it is attached
• Trigger - an action or event, that may start a transition. The transition is started only if there is a corresponding trigger and the guard condition allows the execution.

With this particular implementation, the non-deterministism is represented by set of properties. These properties are used in guard conditions to prevent or allow transition. The guard conditions and the event triggers are specified by OSGi LDAP Filter object. Those filters are matched to the state machine properties. In addition, it is allowed, to attach a listener to the state machine and receive notification when:

• Leaving State
• Executing Transition
• Entering State
• Property is Changed

These notifications, lets the developer to implement a complex simulation engines.

Author:

Valentin Valchev

Field Summary

static int	COMMAND_TRIGGER
static int	EVENT_TRIGGER

Constructor Summary

StateMachine()

Method Summary

void	addState(java.lang.String name) Informs the state machine of availability of state
void	addTriggerCommand(java.lang.String command, Transition transition) Adds a new command with associated transition.
void	addTriggerEvent(org.osgi.framework.Filter rule, Transition transition) This method is used to add internal state transition forced by change of some of the state machine parameters.
void	call(java.lang.String command) Calls a command, that was previously added with addCommand() method.
void	clean() Restores the state machine to it's initial *unfilled* state.
boolean	getBooleanProperty(java.lang.String name) This is an utility method to obtain a property of boolean type
java.lang.String	getCurrentState() Returns the current state of the machine.
double	getDoubleProperty(java.lang.String name, double defaultValue) This is an utility method to obtain fixed point double values.
long	getLongProperty(java.lang.String name, long defaultValue) This is an utility method to obtain a property that is of long, int, short or byte value.
java.util.Dictionary	getProperties() Returns a dictionary of custom properties.
java.lang.Object	getProperty(java.lang.String name) Gets a single property of the state machine
void	removeState(java.lang.String name) Removes a state of the state machine if it was added by mistake.
void	reset() Resets the state machine to it's initial state.
void	setCurrentState(java.lang.String name) Manually sets the current state.
protected void	setCurrentState(java.lang.String newState, java.lang.String transition) This method would change the current state while notifying the listener that transition is executed.
void	setInitialState(java.lang.String name) Sets the initial state of the state machine.
void	setProperty(java.lang.String name, java.lang.Object value) Sets a custom, user defined property.
void	setStateListener(StateMachineListener stateListener) Assigns a new state listener.
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

COMMAND_TRIGGER

public static final int COMMAND_TRIGGER

See Also:

Constant Field Values

EVENT_TRIGGER

public static final int EVENT_TRIGGER

See Also:

Constant Field Values

Constructor Detail

StateMachine

public StateMachine()

Method Detail

addTriggerEvent

public void addTriggerEvent(org.osgi.framework.Filter rule,
                            Transition transition)

This method is used to add internal state transition forced by change of some of the state machine parameters. The rule, identifying the expected values is given as OSGi filter.

Parameters:

rule - the filter describing the expected properties value

transition - the transition that is forced if the rule is satisfied.

addTriggerCommand

public void addTriggerCommand(java.lang.String command,
                              Transition transition)

Adds a new command with associated transition. You can add many transitions to a command calling this method with different transition. You cannot add same transition twice.

Parameters:

command - the command that triggers the transition

transition - a transition triggered by the command

Throws:

java.lang.IllegalArgumentException - in case that the transition is already added for that command, fromState is set but is not added to the state machine or toState is not added to the state machine.

See Also:

addState(String)

addState

public void addState(java.lang.String name)

Informs the state machine of availability of state

Parameters:

name - the name of the state to add

call

public void call(java.lang.String command)

Calls a command, that was previously added with addCommand() method.

Parameters:

command - the name of the command to call

Throws:

java.lang.IllegalArgumentException - if the command is not defined

java.lang.IllegalStateException - if the command may not be executed within the current state

See Also:

addTriggerCommand(String, Transition)

clean

public void clean()

Restores the state machine to it's initial *unfilled* state. This method will clear all initialized states, properties and commands.

getCurrentState

public java.lang.String getCurrentState()

Returns the current state of the machine. This method is usually used for monitoring and debugging.

Returns:

the current state

getProperties

public java.util.Dictionary getProperties()

Returns a dictionary of custom properties.

Returns:

a the properties of the state machine. Notice, that the returned dictionary is "read only". To set a property use the setProperty method

See Also:

setProperty(String,Object)

getProperty

public java.lang.Object getProperty(java.lang.String name)

Gets a single property of the state machine

Parameters:

name - the name of the property

Returns:

it's value

getLongProperty

public long getLongProperty(java.lang.String name,
                            long defaultValue)

This is an utility method to obtain a property that is of long, int, short or byte value.

Parameters:

name - the name of the property

defaultValue - is returned in case that the property is not set. This value will not be returned if the value is set, but is not of the expected type.

Returns:

the value of the property.

getBooleanProperty

public boolean getBooleanProperty(java.lang.String name)

This is an utility method to obtain a property of boolean type

Parameters:

name - the name of the property

Returns:

the value of the property if it is set and is Boolean type, otherwise false is returned.

getDoubleProperty

public double getDoubleProperty(java.lang.String name,
                                double defaultValue)

This is an utility method to obtain fixed point double values. It also works with floats.

Parameters:

name - the name of the property

defaultValue - is returned in case that the property is not set. This value will not be returned if the value is set, but is not of the expected type.

Returns:

the double value of the property

removeState

public void removeState(java.lang.String name)

Removes a state of the state machine if it was added by mistake. Notice that calling this method of already running state machine will not validate again the commands transitions assigned to them.

Parameters:

name - the name of the state

See Also:

addState(String)

reset

public void reset()

Resets the state machine to it's initial state. This will also inform the listeners of the change.

setCurrentState

protected void setCurrentState(java.lang.String newState,
                               java.lang.String transition)

This method would change the current state while notifying the listener that transition is executed. If the transition name is null then the listener is not notified about execution of transition, but is still notified for leaving the old and entering the new state.

Parameters:

newState - the name of the new state

transition - the name of the transition that is executed or null

setCurrentState

public void setCurrentState(java.lang.String name)

Manually sets the current state. This method will also inform the listeners of the change.

Parameters:

name - the new state

Throws:

java.lang.IllegalArgumentException - if the state is not added

See Also:

addState(String)

setInitialState

public void setInitialState(java.lang.String name)

Sets the initial state of the state machine. This method MUST be called in order to make the state machine fully operational.

Parameters:

name - the name of the initial state

Throws:

java.lang.IllegalArgumentException - if state is not understood

See Also:

addState(String)

setProperty

public void setProperty(java.lang.String name,
                        java.lang.Object value)

Sets a custom, user defined property.
Setting a property might also trigger a state change. The transitions forced by property change are available at any time and will throw an IllegalStateException, compared to the action call, that might throw it.

Parameters:

name - the name of the property

value - and it's value

setStateListener

public void setStateListener(StateMachineListener stateListener)

Assigns a new state listener. This will override any previously set listeners.

Parameters:

stateListener - The stateListener to set.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

See Also:

Object.toString()