ch.awae.utils.statemachine

Class MachineCoreBuilder

java.lang.Object

ch.awae.utils.statemachine.MachineCoreBuilder

public final class MachineCoreBuilder
extends java.lang.Object

Builder for constructing state machine cores. Multiple of these builders can be combined in a StateMachineBuilder to construct a state machine.

A machine core describes a single state machine with exactly one active state at any time. Multiple cores can be combined into a StateMachine at which point they are combined into a state machine cluster with common event and command queues. The builder does perform some preliminary data validation on every mutation. A full data validation is performed by the StateMachineBuilder whenever a core is added.

Machine Core construction

A machine core is constructed by defining a list of transitions. From these transitions the states are extracted automatically. Transitions can be added by calling addTransition(String, String, String, String...). Every machine core requires an initial state to be defined. That is the state the machine core starts in and is reverted to whenever a state machine is reset using StateMachine.reset(). This initial state can be set through setInitialState(String).

Event Resolution

It is possible to create local events. These events are designed to be ignored by all other cores. They are prefixed with a fixed string. Local events are referred to by adding local: to the event name. That prefix will internally be replaced with the fixed string. Output events with the prefix c: are interpreted as commands and are added to the command queue (without the prefix). All others are handled as internal events.

Helper Methods

The method addSequence(String, String[], String, String...) allows for easy definition of a transition sequence, i.e. an ordered list of events that - if occurring in that sequence - result in a given transition. The intermediate states are generated internally and are expected to be unique (the state names are derived from random UUID's).

The method addArbitrarySequence(String, String[], String, String...) allows for easy definition of a set of transitions for a given unordered list of events. The resulting transitions represent a system where all events in the given list must occur in any order to result in a given transition. The resulting system grows very quickly with the number of events in the list. It is recommended to avoid exceeding 4-5 entries as otherwise many thousands of states may be created.

The method addFunnel(String[], String, String, String...) allows for easy definition of the same transition from multiple origins to a single target state. This is very useful if there are multiple states that should respond to a given event identically. If combined with the addSequence(String, String[], String, String...) method this can for example be used to create "reset" transitions for each intermediate state in the sequence.

Terminal State Checking

By default during creation each core validates that there are no terminal states (i.e. states that have no transitions leaving them). Often terminal states are not desired as most state machines should be able (by some sequence of events) to return to a prior well-defined state (e.g. a default "idle" state). In these scenarios terminal states are an indicator of a programming error and are therefore checked for. This checks can however be very expensive as the target states of all transitions must be checked. If terminal states are actually needed, the check strictness can be reduced by calling setAllowTerminalStates(true). This will still perform the check but only produce warnings for terminal states and not an exception. If the performance requirements require it the terminal state check can be disabled completely by calling setCheckForTerminalStates(false). It is recommended to keep the terminal state check enabled whenever possible but at least for testing. If all "legal" terminal states are known the check still allows for easy detection of unwanted terminal states.

Since:

awaeUtils 0.0.3

Version:

2.0 (0.0.6)

Author:

Andreas Wälchli

See Also:

StateMachine, StateMachineBuilder

Constructor Summary

Constructors

Constructor and Description
MachineCoreBuilder() creates a new empty builder with a random local id
MachineCoreBuilder(MachineCoreBuilder builder) copy constructor
MachineCoreBuilder(java.lang.String localID) creates a new empty builder with the provided local id

Method Summary

Modifier and Type	Method and Description
MachineCoreBuilder	addArbitrarySequence(java.lang.String from, java.lang.String[] sequence, java.lang.String to, java.lang.String... events) Creates a network of states and transitions covering all possible permutations of a given list of events.
MachineCoreBuilder	addFunnel(java.lang.String[] from, java.lang.String event, java.lang.String to, java.lang.String... events) Adds a new transition from all the origin states to a single target state essentially funnelling the state flow.
java.lang.String[]	addSequence(java.lang.String from, java.lang.String[] sequence, java.lang.String to, java.lang.String... events) Adds a sequence of state transitions with anonymous states for the intermediate steps.
MachineCoreBuilder	addTransition(java.lang.String from, java.lang.String event, java.lang.String to, java.lang.String... events) Adds a new transition between two states.
MachineCoreBuilder	copy() creates a copy of this builder instance.
java.lang.String	getLocalID() Provides the local id that is used to prefix local events
java.lang.String	getTarget(java.lang.String origin, java.lang.String event) Searches the target state for a given transition originating at a given node
MachineCoreBuilder	setAllowTerminalStates(boolean allow) define if terminal states are allowed.
MachineCoreBuilder	setCheckForTerminalStates(boolean check) Defines if the core should be checked for terminal states during creation.
MachineCoreBuilder	setInitialState(java.lang.String state) Sets the initial state of the state machine core.

Methods inherited from class java.lang.Object

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

Constructor Detail

MachineCoreBuilder

public MachineCoreBuilder()

creates a new empty builder with a random local id

MachineCoreBuilder

public MachineCoreBuilder(java.lang.String localID)

creates a new empty builder with the provided local id

Parameters:

localID - the local id

Throws:

java.lang.NullPointerException - localID is null

java.lang.IllegalArgumentException - localID is empty

MachineCoreBuilder

public MachineCoreBuilder(MachineCoreBuilder builder)

copy constructor

Parameters:

builder - the builder to copy

Throws:

java.lang.NullPointerException - builder is null

Since:

1.2

Method Detail

setCheckForTerminalStates

public MachineCoreBuilder setCheckForTerminalStates(boolean check)

Defines if the core should be checked for terminal states during creation. This check may be very expensive. By default it is enabled.

Parameters:

check - true if the check should be done.

Since:

1.4 (0.0.5)

getLocalID

public java.lang.String getLocalID()

Provides the local id that is used to prefix local events

Returns:

the local id

addTransition

public MachineCoreBuilder addTransition(java.lang.String from,
                                        java.lang.String event,
                                        java.lang.String to,
                                        java.lang.String... events)

Adds a new transition between two states.

Parameters:

from - the state the transition originates from. may not be null

event - the event that triggers the transition. may not be null

to - the state the transition leads to. may be identical to from. may not be null

events - an array of all events that shall be triggered by the transition. may be null. no element may be null

commands -

Returns:

the builder itself

Throws:

java.lang.NullPointerException - if any String parameter or any array element is null

addFunnel

public MachineCoreBuilder addFunnel(java.lang.String[] from,
                                    java.lang.String event,
                                    java.lang.String to,
                                    java.lang.String... events)

Adds a new transition from all the origin states to a single target state essentially funnelling the state flow.

Parameters:

from - the states the transitions originate from. may not be null or contain null elements

event - the event that triggers the transition. may not be null

to - the state the transition leads to. may be identical to from. may not be null

events - an array of all events that shall be triggered by the transition. may be null. no element may be null

commands - an array of all commands that shall be triggered by the transition. may be null. no element may be null

Returns:

the builder itself

Throws:

java.lang.NullPointerException - if any String parameter or any array element is null

Since:

1.4 (0.0.5)

setAllowTerminalStates

public MachineCoreBuilder setAllowTerminalStates(boolean allow)

define if terminal states are allowed. terminal states without any transitions leaving them. By default terminal states are not allowed.

Parameters:

allow - true if terminal states should be allowed

Returns:

the builder itself

Since:

1.4

addSequence

public java.lang.String[] addSequence(java.lang.String from,
                                      java.lang.String[] sequence,
                                      java.lang.String to,
                                      java.lang.String... events)

Adds a sequence of state transitions with anonymous states for the intermediate steps. The triggered events and commands will all be added to the last transition in the sequence.

Parameters:

from - the state the transition originates from. may not be null

sequence - the sequence of events that triggers the transitions. may not be null and must have at least one item.

to - the state the transition leads to. may be identical to from. may not be null

events - an array of all events that shall be triggered by the transition. may be null. no element may be null

commands - an array of all commands that shall be triggered by the transition. may be null. no element may be null

Returns:

an ordered list of all intermediate states or an empty array if no intermediate states exist

Throws:

java.lang.NullPointerException - if any String parameter or any array element is null

java.lang.IllegalArgumentException - the sequence is empty

Since:

1.3 (0.0.5)

setInitialState

public MachineCoreBuilder setInitialState(java.lang.String state)

Sets the initial state of the state machine core. The initial state is the state the state machine will start at and return to whenever it is reset.

Parameters:

state - the initial state. may not be null

Returns:

the builder itself

Throws:

java.lang.NullPointerException - state is null

addArbitrarySequence

public MachineCoreBuilder addArbitrarySequence(java.lang.String from,
                                               java.lang.String[] sequence,
                                               java.lang.String to,
                                               java.lang.String... events)

Creates a network of states and transitions covering all possible permutations of a given list of events. Essentially this represents a situation where every event must occur but the order is irrelevant. The resulting network will grow very quickly. For a sequence of length n there will be generated n! intermediate states. Currently there is no optimisation performed on the network.

Parameters:

from - the state the transition originates from. may not be null

sequence - the list of events that triggers the transitions. may not be null and must have at least one item.

to - the state the transition leads to. may be identical to from. may not be null

events - an array of all events that shall be triggered by the transition. may be null. no element may be null

commands - an array of all commands that shall be triggered by the transition. may be null. no element may be null

Returns:

the builder itself

Throws:

java.lang.NullPointerException - if any String parameter or any array element is null

java.lang.IllegalArgumentException - the sequence is empty

Since:

1.4 (0.0.5)

getTarget

public java.lang.String getTarget(java.lang.String origin,
                                  java.lang.String event)

Searches the target state for a given transition originating at a given node

Parameters:

origin - the state the transition originates at

event - the event triggering the transition

Returns:

the target state of the transition or null if no matching transition was found

Since:

1.4 (0.0.5)

copy

public MachineCoreBuilder copy()

creates a copy of this builder instance.

Returns:

a copy

Since:

1.2

See Also:

MachineCoreBuilder(MachineCoreBuilder)