com.tomgibara.pronto.state.impl
Class StateEngineImpl<S,L,P>

java.lang.Object
  com.tomgibara.pronto.state.impl.StateEngineImpl<S,L,P>

All Implemented Interfaces:

StateEngine<S,L,P>

public class StateEngineImpl<S,L,P>
extends java.lang.Object
implements StateEngine<S,L,P>

Constructor Summary

StateEngineImpl(StateGraph<S,L> graph, StateActivator<S,L,P> activator)

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.

Methods inherited from class java.lang.Object

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

Constructor Detail

StateEngineImpl

public StateEngineImpl(StateGraph<S,L> graph,
                       StateActivator<S,L,P> activator)

Method Detail

setPolicy

public void setPolicy(StateEnginePolicy policy)

Description copied from interface: StateEngine

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

Specified by:

setPolicy in interface StateEngine<S,L,P>

Parameters:

policy - the engine's policy, may be null

getPolicy

public StateEnginePolicy getPolicy()

Description copied from interface: StateEngine

The policy under which the engine is operating.

Specified by:

getPolicy in interface StateEngine<S,L,P>

Returns:

the engine's policy, never null

getGraph

public StateGraph<S,L> getGraph()

Description copied from interface: StateEngine

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

Specified by:

getGraph in interface StateEngine<S,L,P>

Returns:

the state graph which this engine operates over, never null

getPossibleStates

public java.util.Set<S> getPossibleStates()

Description copied from interface: StateEngine

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.

Specified by:

getPossibleStates in interface StateEngine<S,L,P>

Returns:

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

getState

public S getState()

Description copied from interface: StateEngine

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.

Specified by:

getState in interface StateEngine<S,L,P>

Returns:

the current state or null

setState

public void setState(S state)
              throws ProntoStateException

Description copied from interface: StateEngine

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.

Specified by:

setState in interface StateEngine<S,L,P>

Parameters:

state - the state into which the engine should be put

Throws:

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

transition

public void transition(S state,
                       L label,
                       P parameter)
                throws ProntoStateException

Description copied from interface: StateEngine

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.

Specified by:

transition in interface StateEngine<S,L,P>

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

pathTransition

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

Description copied from interface: StateEngine

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.

Specified by:

pathTransition in interface StateEngine<S,L,P>

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

public boolean addStateListener(StateListener<S,L> listener)

Description copied from interface: StateEngine

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.

Specified by:

addStateListener in interface StateEngine<S,L,P>

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

public boolean removeStateListener(StateListener<S,L> listener)

Description copied from interface: StateEngine

Removes a previously added state listener from this engine.

Specified by:

removeStateListener in interface StateEngine<S,L,P>

Parameters:

listener - the listener to be removed

Returns:

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