com.kangirigungi.jstatemachine

Class SubStateMachineBuilder<StateId,Event>

java.lang.Object

com.kangirigungi.jstatemachine.SubStateMachineBuilder<StateId,Event>

public class SubStateMachineBuilder<StateId,Event>
extends java.lang.Object

A builder used to create a certain level of a state machine. Instances of this class are acquired via StateMachineBuilder.get() (for top level state machines) or CompositeStateBuilder.getStateMachineBuilder() (for composite states).

The following kind of transitions are supported:

• Normal transition: Added with addTransition with the event parameter not null. These transitions are explicitly triggered with processEvent and change the state (or exit then enter the same state if the source and target state are the same).
• Internal transition: Added with addInternalTransition. The event parameter cannot be null. These transitions trigger an action without exiting the current state.
• Completion transition: Added with addTransition with the event parameter null. These transitions are automatically triggered after each successful transition. If guarded and the guard value changes to true, it is cannot be checked automatically, only when the next (internal or external) transition happens. It can also be triggered explicitly with processEvent(null).

Method Summary

Methods

Modifier and Type	Method and Description
CompositeStateBuilder<StateId,Event>	addCompositeState(StateId id) Add a new composite state.
SubStateMachineBuilder<StateId,Event>	addInternalTransition(StateId state, Event event, ITransitionAction<StateId,Event> action) Same as addInternalTransition(state, event, action, null).
SubStateMachineBuilder<StateId,Event>	addInternalTransition(StateId state, Event event, ITransitionAction<StateId,Event> action, IGuard<StateId,Event> guard) Add a new internal transition.
StateBuilder<StateId,Event>	addState(StateId id) Add a new state.
SubStateMachineBuilder<StateId,Event>	addTransition(StateId fromState, Event event, ITransitionAction<StateId,Event> action, StateId toState) Same as addTransition(fromState, event, action, toState, null).
SubStateMachineBuilder<StateId,Event>	addTransition(StateId fromState, Event event, ITransitionAction<StateId,Event> action, StateId toState, IGuard<StateId,Event> guard) Add a new transition.
SubStateMachineBuilder<StateId,Event>	setInitialState(StateId initialState) Set the initial state of the state machine.

Methods inherited from class java.lang.Object

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

Method Detail

setInitialState

public SubStateMachineBuilder<StateId,Event> setInitialState(StateId initialState)

Set the initial state of the state machine.

Parameters:

initialState - The initial state of the state machine.

Returns:

this.

addState

public StateBuilder<StateId,Event> addState(StateId id)

Add a new state.

Only one state with one ID is allowed. If another one with the same ID is attempted to be added, an exception is thrown.

Parameters:

id - The identifier of the new state.

Returns:

The instance of the new state.

Throws:

DuplicateStateException - If the state id already exists.

addCompositeState

public CompositeStateBuilder<StateId,Event> addCompositeState(StateId id)

Add a new composite state.

Only one state with one id is allowed. If another one with the same ID is attempted to be added, an exception is thrown.

Parameters:

id - The identifier of the new state.

Returns:

The instance of the new state.

Throws:

DuplicateStateException - If the state id already exists.

addTransition

public SubStateMachineBuilder<StateId,Event> addTransition(StateId fromState,
                                                  Event event,
                                                  ITransitionAction<StateId,Event> action,
                                                  StateId toState,
                                                  IGuard<StateId,Event> guard)

Add a new transition. The action and guard parameters are optional. The fromState parameter is mandatory and cannot be null. If event is null, that means it is a completion transition. Otherwise, it is a normal transition.

For each state and event, only one transition is allowed, except if all transitions for that state and event are guarded. Warning: There is no guarantee that all guard checks are executed. The first transition where the guard returns true is executed.

Warning: There is no check that completion transitions won't cause an infinite loop.

Parameters:

fromState - The initial state of the transition.

event - The event that triggers the transition. If null, it is a completion transition.

action - The action to be executed.

toState - The final state of the transition.

Returns:

this.

Throws:

DuplicateTransitionException - If there is an ambiguous transition.

{@link - NoStateException} If either fromState of toState does not exist.

addTransition

public SubStateMachineBuilder<StateId,Event> addTransition(StateId fromState,
                                                  Event event,
                                                  ITransitionAction<StateId,Event> action,
                                                  StateId toState)

Same as addTransition(fromState, event, action, toState, null).

addInternalTransition

public SubStateMachineBuilder<StateId,Event> addInternalTransition(StateId state,
                                                          Event event,
                                                          ITransitionAction<StateId,Event> action,
                                                          IGuard<StateId,Event> guard)

Add a new internal transition. Internal transitions do not leave the state when performing an action. The action and guard parameters are optional (though it would not make sense omitting it). The state and event parameters is mandatory and cannot be null.

Parameters:

state - The initial state of the transition.

event - The event that triggers the transition.

action - The action to be executed.

Returns:

this.

Throws:

DuplicateTransitionException - If there is already a transition from the same state with the same event.

{@link - NoStateException} If either fromState of toState does not exist.

addInternalTransition

public SubStateMachineBuilder<StateId,Event> addInternalTransition(StateId state,
                                                          Event event,
                                                          ITransitionAction<StateId,Event> action)

Same as addInternalTransition(state, event, action, null).