org.vishia.states

Class StateMachine

java.lang.Object

org.vishia.states.StateMachine

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable, EventConsumer, InfoAppend

public class StateMachine
extends java.lang.Object
implements EventConsumer, InfoAppend, java.io.Closeable

To build a state machine you should build a maybe inner class derived from StateMachine. This class builds the frame for all states. Any state should be defined as inner class derived from either ...or

• StateSimple: A simple state with transitions, an optional entry- and an exit-action.
• StateComposite: It contains more as one sub states.
• StateParallel: It contains more as one StateComposite for parallel behavior: Any StateComposite contains a sub statemachine which works parallel if this state is active.

See example pattern org.vishia.states.example.StateExampleSimple.

Any state can contain an entry- and an exit action which can be build either ... or with:

• Overriding the method StateSimple.entry(EventObject) respectively StateSimple.exit().
• Set the association StateSimple.entry respectively StateSimple.exit with an Implementation of StateAction which can be located in any other class, usual as inner anonymous class. In that cases the entry and exit can use data from any other class.

Any state can contain some transitions which are variables of type StateSimple.Trans. If a transition should contain an action the transition variable should be an anonymous inner derived class of StateSimple.Trans which overrides the StateSimple.Trans.action(EventObject). The other possibility is assignment of action code with StateSimple.Trans.setAction(StateAction)

Any state should override the method StateSimple.checkTrans(EventObject). This method checks all conditions which can fire any transition and returns the selected transition instance or null if nothing should fire. This method should not execute actions. It should only test the condition and select the transition. The actions are done in the calling environment of this method, lastly if processEvent(EventObject) of the whole statemachine is invoked.

On construction of the whole StateMachine all state classes are instantiated and listed in the StateMachine. All transitions are evaluated and transformed in a unified list of transition objects. For all transitions the necessary exitState()- and entryState() operations are detected and stored, so that complex state switches are executed correctly. The designation of destination states in the written source code uses the class names of the states. The transition evaluation process on construction searches and lists the instances of the states.

A state instance can be gotten with getState(Class)

The StateMachine can be quested whether a state is active yet: isInState(Class) or isInState(Class)


Creation of a StateMachine with or without a timer and an event queue:
One can execute the state machine in 2 modes:

• State execution inside a thread which processes events. That thread can process more as one state machine. The limit is: If many events can be occured, the execution of all state transitions should be able to done in a limited time. The advantage is: All state machines are executed in the same thread. The transitions are fibers of that thread. They are non-interrupt-able. If more as one state machines work with the same data, no additional mutexes are necessary.
• State execution inside the calling thread. That is the more simple variant. Events to trigger the state machine are possible but not necessary. The user should have control over mutual exclusion access to data if some more threads are used.

In the first case an instance of EventTimerThread#EventThread(String) are necessary which is a parameter for the constructor #StateMachine(EventTimerThread, EventTimerMng).

If an EventTimerThread is used an instance of EventTimerMng is possible and recommended . The timer manager can manage any number of time orders. It sends an EventTimerMng.TimeEvent to this StateMachine it the time is expired.

The state machine can be animated using processEvent(EventObject) with or without events by given a null argument, for example cyclically if an EventTimerThread is not used.

To see how transitions and timeouts should be written see on StateSimple.Trans and StateSimple.Timeout.