com.tomgibara.pronto.state
Interface StateEngine<S,L,P>

Type Parameters:

S - the type of states in the engine's state graph

L - the type of labels on the engine's state graph

P - the type of transition parameterisation of the state activator

All Known Implementing Classes:

StateEngineImpl

public interface StateEngine<S,L,P>

State Engines manage transitions across a pre-defined graph of allowed states and state transitions. Work that is to be done as part of a transition is performed by a StateActivator assigned to the engine. When an engine is first created (or after the failure of a transition due to a unchecked exception being thrown by the engine's associated activator), the engine is in an indeterminate state and the setState method must be called before any transmissions may be made. Instances of this class are entirely safe for concurrent access.

Author:

Tom Gibara

Method Summary

boolean	addStateListener(StateListener<S,L> listener) Adds a state listener to this engine.
StateGraph<S,L>	getGraph() The graph of an engine constrains the states which it may enter and the transitions it may make.
StateEnginePolicy	getPolicy() The policy under which the engine is operating.
java.util.Set<S>	getPossibleStates() Returns a set of the states which are currently permitted in a call to setState.
S	getState() The state that this engine is currently in.
void	pathTransition(S state, L label, PathType type, StateTransitionParameters<S,L,P> parameters) This method is called to instruct the engine to make a sequence of state transitions.
boolean	removeStateListener(StateListener<S,L> listener) Removes a previously added state listener from this engine.
void	setPolicy(StateEnginePolicy policy) Sets the policy under which the state engine will operate.
void	setState(S state) Puts the engine into a specified state.
void	transition(S state, L label, P parameter) This method is called to instruct the engine to make one (or possibly more) state transitions.

Method Detail

setPolicy

void setPolicy(StateEnginePolicy policy)

Sets the policy under which the state engine will operate. Supplying a null value causes an instance of DefaultStatePolicy to be used.

Parameters:

policy - the engine's policy, may be null

getPolicy

StateEnginePolicy getPolicy()

The policy under which the engine is operating.

Returns:

the engine's policy, never null

getGraph

StateGraph<S,L> getGraph()

The graph of an engine constrains the states which it may enter and the transitions it may make.

Returns:

the state graph which this engine operates over, never null

getPossibleStates

java.util.Set<S> getPossibleStates()

Returns a set of the states which are currently permitted in a call to setState. Initially, this will be every state in the engine's state graph. After a state has been set, only the current state will be returned unless a transition failure has occured due to an unchecked exception in which case the possible states are the initial and final states of the transition which failed.

Returns:

an immutable set of states which may be empty, never null

getState

S getState()

The state that this engine is currently in. If the engine is in an indeterminate state (due to the failure of a transition, or because no state has yet been set), this method returns null.

Returns:

the current state or null

setState

void setState(S state)
              throws ProntoStateException

Puts the engine into a specified state. This method does not trigger any transitions but attempts to set the state of the engine directly. This method may fail with a ProntoStateException if the state is impossible, or if the state change is vetoed, or if an unexpected exception occured during the state change. Setting the state to the current state has no effect. Depending on the engine's current policy, exceptions raised by listeners in response to the transitioning may be thrown from this method.

Parameters:

state - the state into which the engine should be put

Throws:

ProntoStateException - if the state change is impossible, vetoed or failed

transition

void transition(S state,
                L label,
                P parameter)
                throws ProntoStateException,
                       java.lang.IllegalArgumentException

This method is called to instruct the engine to make one (or possibly more) state transitions. Before this method is called, the engine must be in a determinate state. The target state and transition label supplied to this method are combined with the current engine state in an attempt to identify a uniquely matching transition. If no such transition exists (or is not unique) an exception is raised, otherwise a transition is attempted. Either one or both of the specified label and state may be null. Naturally, if both are null then there must be a single exit transition from the current state or an exception is raised. In the event that a transition fails due to an unchecked exception being thrown by the engine's state activator, the engine enters an indeterminate state in which getState() will return null. Depending on the engine's current policy, exceptions raised by listeners in response to the transitioning may be thrown from this method. Such exceptions will not cause the engine to enter an indeterminate state.

Parameters:

state - the state to transition to, may be null

label - a constraint on the transition, may be null

parameter - passed through to the activator on transition, may be null if the activator permits it

Throws:

ProntoStateException - if the transition fails for any reason including: the engine being in an indetermintate state, the activator vetoing the transition, the activator failing with a unchecked exception, the lack of a matching transition, the presence of more than one matching transition

java.lang.IllegalArgumentException - if the method is called with null state and null label

pathTransition

void pathTransition(S state,
                    L label,
                    PathType type,
                    StateTransitionParameters<S,L,P> parameters)
                    throws ProntoStateException,
                           java.lang.IllegalArgumentException

This method is called to instruct the engine to make a sequence of state transitions. Before this method is called, the engine must be in a determinate state. This method may be used in several ways depending on the combination of parameters supplied. If the method is called with a non-null state, a single sequence of transitions from the current state into the specified state is sought. Otherwise the method will attempt to identify a unique terminal state (given the engine's current state and any specified label) and transition into that state. If the method is called with a label then only transitions with matching labels will be traversed to attain the specified state. The type parameter constrains the sequences of transitions that this method is permitted to consider for transition into the target state. If there is more than one possible sequence of transitions between the initial and target states and exception is raised. In the event that a transition fails due to an unchecked exception being thrown by the engine's state activator, the engine enters an indeterminate state in which getState() will return null. Depending on the engine's current policy, exceptions raised by listeners in response to the transitioning may be thrown from this method. Such exceptions will not cause the engine to enter an indeterminate state.

Parameters:

state - the state to transition to, may be null

label - a constraint on each transition, may be null

type - a constraint on the sequence of transitions

parameters - may supply a parameter for each transition, may be null in which case a null parameter will be supplied for every transition

Throws:

ProntoStateException - if the transition fails for any reason including: the engine being in an indetermintate state, the activator vetoing the transition, the activator failing with a unchecked exception, the lack of a matching sequence of transition, the presence of more than one matching sequence of transitions.

java.lang.IllegalArgumentException - if the method is called with null state and null label

addStateListener

boolean addStateListener(StateListener<S,L> listener)

Adds a state listener to this engine. A given state listener instance can only be added once. The state listener will be notified after each successful change of state. Event dispatch is currently done on the state-changing thread but this is currently subject to change. Unchecked exceptions raised by listeners will not invalidate the engine state.

Parameters:

listener - the state listener to be added

Returns:

true if the listener was added, false if it is already registered as a listener

removeStateListener

boolean removeStateListener(StateListener<S,L> listener)

Removes a previously added state listener from this engine.

Parameters:

listener - the listener to be removed

Returns:

true if the listener was removed, false if the object was not a registered listener