com.robopupu.api.fsm

Class StateEngine<T_State extends StateEngine>

java.lang.Object

com.robopupu.api.fsm.StateEngine<T_State>

Type Parameters:

T_State -

public abstract class StateEngine<T_State extends StateEngine>
extends java.lang.Object

StateEngine is an abstract class that is used in code generation by annotation processor for creating concrete StateEngine implementations for StateMachines. All concrete state classes are derived from the code generated implemetation of StateEngine.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	StateEngine.Error Error defines error types and messages for StateEngine.

Field Summary

Fields

Modifier and Type	Field and Description
protected T_State	currentState The current state among the substates of this state.
protected java.lang.Class<? extends T_State>	initialStateClass A Class specifying the initial state among the substates of this state.
protected java.util.HashMap<java.lang.Class<?>,T_State>	stateCache A HashMap used for caching state instances.
protected T_State	stateEngine The reference to an instance of StateEngine that represents a state machine.
protected java.util.HashSet<T_State>	subStates A HashMap containing either 1) the substates of a state if this instance of StateEngine represents a state or 2) the top-level states if this instance of StateEngine represents a state machine.
protected T_State	superState The super state of the state represented by this instance of StateEngine.
protected java.lang.Class<? extends T_State>	superStateClass The class of the super state of the state represented by this instance of StateEngine.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	StateEngine(java.lang.Class<? extends T_State> initialStateClass) This constructor is to be used by a concrete implementation of StateEngine.
protected	StateEngine(java.lang.Class<? extends T_State> superStateClass, java.lang.Class<? extends T_State> initialStateClass) This constructor is to be used by all actual state classes which are extended from the concrete implementation of this StateEngine.

Method Summary

Modifier and Type	Method and Description
protected T_State	dispatch() Selects a state that should receive the trigger event.
protected void	dispose() Disposes this StateEngine and the all state objects contained by it.
protected T_State	enter(int entryPoint) Enters the represented by this instance of StateEngine.
protected T_State	enterDeepHistory() Enters a deep history point.
protected T_State	enterEntryPoint(int entryPoint) Enters the specified entry point.
protected T_State	enterShallowHistory() Enters a shallow history point.
protected void	exit(T_State newState) Invoked to exit the state represented by this instance of StateEngine.
<T extends StateEngine> T	getCurrentState() Gets the current state of this StateEngine or state.
StateEngineObserver	getObserver() Gets the StateEngineObserver assigned for this StateEngine.
protected T_State	getState(java.lang.Class<? extends T_State> stateClass) Gets an instance of the specified state.
protected T_State	getStateEngine() Gets the reference to a StateEngine.
protected <T extends T_State> T	getSuperState() Gets the super state of this state.
boolean	hasSuperState() Tests if this the state represented by this instance of StateEngine has a super state that is not StateEngine.
boolean	hasSuperState(java.lang.Class<? extends StateEngine<?>> stateClass) Tests if this state is the same state or a direct or an indirect substate state of the specified state.
protected boolean	isStateEngine() Tests if this instance of StateEngine represents a state machine and not a state that belongs into it.
boolean	isSuperState(T_State state) Tests if the given state object is a direct or an indirect super state of the state represented by this instance of StateEngine.
protected boolean	isSuperStateFor(T_State state) Tests if the state object represented by this instance of StateEngine is a direct or an indirect super state of the given state.
protected void	onDisposeState() Invoked by dispose() for an instance of StateEngine that represents a state of a state machine.
protected void	onDisposeStateEngine() Invoked by dispose() for an instance of StateEngine that represents a state machine.
protected void	onEnter() Invoked by enter(int).
protected void	onError(T_State state, StateEngine.Error error) Invoked when the specified error has occurred while in the given state.
protected void	onError(T_State state, StateEngine.Error error, java.lang.String eventName) /** Invoked when the specified error has occurred while in the named event has been received in the given state.
protected void	onExit() Invoked by exit(StateEngine).
protected void	onUnhandledEvent(java.lang.String eventName)
void	reset() Resets this StateEngine.
protected void	setCurrentState(T_State state) Sets the current state of this StateEngine or state.
void	setObserver(StateEngineObserver observer) Sets the StateEngineObserver assigned for this StateEngine.
void	start() Starts this StateEngine.
void	stop() Stops this StateEngine.
protected T_State	toHistoryState(java.lang.Class<? extends T_State> stateClass, boolean deepHistory) Causes transition from the current state to the specified history state via a deep or shallow history point.
java.lang.String	toString() A String representation of this StateEngine is simply the name of the class implementing abstract class StateEngine.
protected T_State	transitTo(java.lang.Class<? extends T_State> stateClass) Causes transition from the current state to the specified state.
protected T_State	transitTo(java.lang.Class<? extends T_State> stateClass, int entryPoint) Causes transition from the current state to the specified state optionally via an entry point

Methods inherited from class java.lang.Object

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

Field Detail

subStates

protected final java.util.HashSet<T_State extends StateEngine> subStates

A HashMap containing either 1) the substates of a state if this instance of StateEngine represents a state or 2) the top-level states if this instance of StateEngine represents a state machine.

currentState

protected T_State extends StateEngine currentState

The current state among the substates of this state.

initialStateClass

protected java.lang.Class<? extends T_State extends StateEngine> initialStateClass

A Class specifying the initial state among the substates of this state.

stateCache

protected java.util.HashMap<java.lang.Class<?>,T_State extends StateEngine> stateCache

A HashMap used for caching state instances. The Classes of states can be used as keys to the HashMap, because each state object has its own Class.

stateEngine

protected T_State extends StateEngine stateEngine

The reference to an instance of StateEngine that represents a state machine. All instances of concrete implementations of StateEngine that represent individual states have a reference to the state machine.

superStateClass

protected java.lang.Class<? extends T_State extends StateEngine> superStateClass

The class of the super state of the state represented by this instance of StateEngine. If this instance of StateEngine is a state machine, then this field has null value.

superState

protected T_State extends StateEngine superState

The super state of the state represented by this instance of StateEngine. If this instance of StateEngine is a state machine, then this field has null value.

Constructor Detail

StateEngine

protected StateEngine(java.lang.Class<? extends T_State> initialStateClass)

This constructor is to be used by a concrete implementation of StateEngine.

Parameters:

initialStateClass - The Class of a state that is the initial state to be entered at top-level when the represented state machine is started.

StateEngine

protected StateEngine(java.lang.Class<? extends T_State> superStateClass,
                      java.lang.Class<? extends T_State> initialStateClass)

This constructor is to be used by all actual state classes which are extended from the concrete implementation of this StateEngine.

Parameters:

superStateClass - The Class of a state that is the super state of the state using this constructor.

initialStateClass - The Class of a state that is the initial state to be entered at top-level when the represented state machine is started.

Method Detail

getObserver

public StateEngineObserver getObserver()

Gets the StateEngineObserver assigned for this StateEngine.

Returns:

A StateEngineObserver.

setObserver

public final void setObserver(StateEngineObserver observer)

Sets the StateEngineObserver assigned for this StateEngine.

Parameters:

observer - A StateEngineObserver.

getSuperState

protected final <T extends T_State> T getSuperState()

Gets the super state of this state.

Type Parameters:

T - A type parameter for the state type.

Returns:

The state object.

getCurrentState

public final <T extends StateEngine> T getCurrentState()

Gets the current state of this StateEngine or state.

Type Parameters:

T - A type parameter for the state type.

Returns:

A state object.

setCurrentState

protected final void setCurrentState(T_State state)

Sets the current state of this StateEngine or state.

Parameters:

state - A state object representing the new current state.

getStateEngine

protected final T_State getStateEngine()

Gets the reference to a StateEngine.

Returns:

A StateEngine.

isStateEngine

protected final boolean isStateEngine()

Tests if this instance of StateEngine represents a state machine and not a state that belongs into it.

Returns:

A boolean value.

getState

protected final T_State getState(java.lang.Class<? extends T_State> stateClass)

Gets an instance of the specified state.

Parameters:

stateClass - A state object Class.

Returns:

A state object. May not return null.

dispatch

protected T_State dispatch()

Selects a state that should receive the trigger event.

Returns:

A state as T_State.

transitTo

protected final T_State transitTo(java.lang.Class<? extends T_State> stateClass)

Causes transition from the current state to the specified state.

Parameters:

stateClass - A Class specifying the target state for the state transition.

Returns:

The current state as T_State.

transitTo

protected final T_State transitTo(java.lang.Class<? extends T_State> stateClass,
                                  int entryPoint)

Causes transition from the current state to the specified state optionally via an entry point

Parameters:

stateClass - A Class specifying the target state for the state transition.

entryPoint - A int value specifying if the optional entry point. Value zero represents a non entry point.

Returns:

The current state.

toHistoryState

protected final T_State toHistoryState(java.lang.Class<? extends T_State> stateClass,
                                       boolean deepHistory)

Causes transition from the current state to the specified history state via a deep or shallow history point.

Parameters:

stateClass - A Class specifying the target state for the state transition.

deepHistory - A boolean value specifying if the state is entered via a deep history point instead of shallow history point.

Returns:

The current state.

enter

protected final T_State enter(int entryPoint)

Enters the represented by this instance of StateEngine. If the state is entered via an entry point the index of the entry point has to be given and it has to be greater than zero.

Parameters:

entryPoint - The index of the entry point to be entered. Value zero represents a non entry point.

Returns:

The current state.

onExit

protected void onExit()

Invoked by exit(StateEngine).

onEnter

protected void onEnter()

Invoked by enter(int).

enterEntryPoint

protected T_State enterEntryPoint(int entryPoint)

Enters the specified entry point. If a state implementation has one or more entry points, it has to override this method.

Parameters:

entryPoint - The index of the entry point to be entered.

Returns:

The current state after entering the deep history point.

enterDeepHistory

protected final T_State enterDeepHistory()

Enters a deep history point.

Returns:

The current state after entering the deep history point.

enterShallowHistory

protected final T_State enterShallowHistory()

Enters a shallow history point.

Returns:

The current state after entering the shallow history point.

exit

protected final void exit(T_State newState)

Invoked to exit the state represented by this instance of StateEngine. The state machine will enter the given new target state.

Parameters:

newState - A new target state.

onError

protected final void onError(T_State state,
                             StateEngine.Error error)

Invoked when the specified error has occurred while in the given state.

Parameters:

state - A state object.

error - An StateEngine.Error value specifying the occurred error.

onError

protected final void onError(T_State state,
                             StateEngine.Error error,
                             java.lang.String eventName)

/** Invoked when the specified error has occurred while in the named event has been received in the given state.

Parameters:

state - A state object.

error - An StateEngine.Error value specifying the occurred error.

eventName - The name of an event.

onUnhandledEvent

protected void onUnhandledEvent(java.lang.String eventName)

onDisposeStateEngine

protected void onDisposeStateEngine()

Invoked by dispose() for an instance of StateEngine that represents a state machine.

onDisposeState

protected void onDisposeState()

Invoked by dispose() for an instance of StateEngine that represents a state of a state machine.

dispose

protected final void dispose()

Disposes this StateEngine and the all state objects contained by it. The method is recursively invoked to all substates of a each state.

start

public final void start()

Starts this StateEngine. When started, the top-level initial state is entered.

reset

public final void reset()

Resets this StateEngine. Resetting clear the cache of state machines. A state machine has to be started again after resetting.

stop

public final void stop()

Stops this StateEngine. Stopping causes the state machine and all of its state to be disposed.

hasSuperState

public boolean hasSuperState()

Tests if this the state represented by this instance of StateEngine has a super state that is not StateEngine.

Returns:

A boolean value.

hasSuperState

public boolean hasSuperState(java.lang.Class<? extends StateEngine<?>> stateClass)

Tests if this state is the same state or a direct or an indirect substate state of the specified state.

Parameters:

stateClass - A Class specifying the state.

Returns:

A boolean value.

isSuperState

public final boolean isSuperState(T_State state)

Tests if the given state object is a direct or an indirect super state of the state represented by this instance of StateEngine.

Parameters:

state - A state object to be tested.

Returns:

A boolean value.

isSuperStateFor

protected final boolean isSuperStateFor(T_State state)

Tests if the state object represented by this instance of StateEngine is a direct or an indirect super state of the given state.

Parameters:

state - A state object to be tested.

Returns:

A boolean value.

toString

public java.lang.String toString()

A String representation of this StateEngine is simply the name of the class implementing abstract class StateEngine.

Overrides:

toString in class java.lang.Object

Returns:

A String