org.vishia.states

Class StateComposite

java.lang.Object

org.vishia.states.StateSimple

org.vishia.states.StateCompositeFlat

org.vishia.states.StateComposite

All Implemented Interfaces:

InfoAppend

Direct Known Subclasses:

StateMachine.StateCompositeTop

public abstract class StateComposite
extends StateCompositeFlat
implements InfoAppend

A composite state with its own state variable stateAct.

Nested Class Summary

Nested classes/interfaces inherited from class org.vishia.states.StateSimple

StateSimple.PlugStateSimpleToGenState, StateSimple.Timeout, StateSimple.Trans, StateSimple.TransChoice, StateSimple.TransJoin

Field Summary

Fields

Modifier and Type	Field and Description
(package private) boolean	isActive Stores whether this composite state is active.
protected int	maxStateSwitchesInLoop
(package private) StateSimple	stateAct
static java.lang.String	version Version, history and license.

Fields inherited from class org.vishia.states.StateCompositeFlat

aSubstates, stateDefault

Fields inherited from class org.vishia.states.StateSimple

compositeState, ctEntry, dateLastEntry, durationLast, enclState, entry, evTimeout, exit, ixCompositeState_inStatePath, mEventConsumed, mEventDonotRelinquish, mEventNotConsumed, millisectimeout, modeTrans, mRunToComplete, mStateEntered, mStateLeaved, mTransit, notTransit, stateId, stateMachine, statePath, transTimeout

Constructor Summary

Constructors

Constructor and Description
StateComposite() The constructor of any StateComposite checks the class for inner classes which are the states.
StateComposite(java.lang.String name, StateMachine stateMachine, StateSimple[] aSubstates) Only used for the StateMachine.stateTop and as special constructor to build a state machine from other data.

Method Summary

Modifier and Type	Method and Description
private void	assembleDstState(java.lang.StringBuilder uStateNext, StateSimple stateAct1)
private static int	doEntryDeepHistory(StateSimple state, java.util.EventObject ev) Execution routine of enter the deep history.
protected int	entryDeepHistory(java.util.EventObject ev) This method is called from StateSimple.Trans.doEntry(EventObject) if the history state should be entered and all history states should be entered in sub states.
int	entryShallowHistory(java.util.EventObject ev) This method should be called from outside if the history state should be entered but the default state of any sub state should be entered.
java.lang.CharSequence	getStatePath() Gets the path to this state.
java.lang.CharSequence	infoAppend(java.lang.StringBuilder u) Appends or returns tan information about the instance.
boolean	isInState(StateSimple state) Check whether this composite state has the given state as direct actual sub state
private void	printStateSwitchInfo(StateSimple statePrev, java.util.EventObject evTrans, int cont)
(package private) int	processEvent(java.util.EventObject evP) Processes the event for the states of this composite state.
java.lang.String	toString() Returns the state Id and maybe some more debug information.
(package private) void	XXXexitTheState(int level) Exits first the actual sub state (and that exits its actual sub state), after them this state is exited.

Methods inherited from class org.vishia.states.StateCompositeFlat

addState, buildStatePathSubstates, createTransitionListSubstate, entryDefaultState, prepareTransitionsSubstate, stateDefault

Methods inherited from class org.vishia.states.StateSimple

_checkTransitions, auxInfo, buildStatePath, checkTrans, compositeState, createTransitionList, enclState, entry, entryTheState, exit, exitTheState, getName, isInState, isTimeout, prepareTransitions, setAuxInfo, setEntryAction, setExitAction, statePath

Methods inherited from class java.lang.Object

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

Field Detail

version

public static final java.lang.String version

Version, history and license.

• 2015-12-20 Hartmut chg: processEvent(EventObject) more simple because enclosing non-StateComposite transitions are checked in StateSimple.
• 2015-11-21 Hartmut chg: printStateSwitchInfo(StateSimple, EventObject, int)
• 2014-11-09 Hartmut chg: Capability of StateParallel contained here, class StateParallel removed: It is possible to have a StateComposite with its own sub states, but a second or more parallel states in an own composite, which is yet the class StateAddParallel. It is StateParallel. More simple, more flexibility.
• 2014-09-28 Hartmut chg: Copied from org.vishia.stateMachine.StateCompositeBase, changed concept: Nested writing of states, less code, using reflection for missing instances and data.
• 2013-05-11 Hartmut new: It is a EventConsumer yet. Especially a timer event needs a destination which is this class.
• 2013-04-27 Hartmut adapt: The #entry(EventMsg2) and the #entryAction(EventMsg2) should get the event from the transition. See StateSimpleBase.
• 2013-04-13 Hartmut re-engineering:
  • New method #setDefaultState(StateSimpleBase)
  • StateCompositeFlat.entryDefaultState() is package private now, it regards requirements of StateParallelBase.
  • The old override-able method entryDefault() was removed.
  • The overridden entry() was removed, replaced by #entryComposite, which is called in StateSimpleBase#entry(int) if the instance is this type.
• 2013-04-07 Hartmut adap: Event with 2 generic parameter
• 2012-09-17 Hartmut improved.
• 2012-08-30 Hartmut created. The experience with that concept are given since about 2003 in C-language.

Copyright/Copyleft: For this source the LGPL Lesser General Public License, published by the Free Software Foundation is valid. It means:

1. You can use this source without any restriction for any desired purpose.
2. You can redistribute copies of this source to everybody.
3. Every user of this source, also the user of redistribute copies with or without payment, must accept this license for further using.
4. But the LPGL is not appropriate for a whole software product, if this source is only a part of them. It means, the user must publish this part of source, but don't need to publish the whole source of the own product.
5. You can study and modify (improve) this source for own using or for redistribution, but you have to license the modified sources likewise under this LGPL Lesser General Public License. You mustn't delete this Copyright/Copyleft inscription in this source file.

If you are intent to use this sources without publishing its usage, you can get a second license subscribing a special contract with the author.

See Also:

Constant Field Values

maxStateSwitchesInLoop

protected int maxStateSwitchesInLoop

isActive

boolean isActive

Stores whether this composite state is active. Note that the #stateAct is set as history state as well the state is not active. This bit is set to false too if the current state is exited and a new state is not entered yet, while temporary transition processing. It helps to prevent double execution of the #exitTheState() routine if exit of the enclosing state is processed.

stateAct

StateSimple stateAct

Constructor Detail

StateComposite

public StateComposite(java.lang.String name,
                      StateMachine stateMachine,
                      StateSimple[] aSubstates)

Only used for the StateMachine.stateTop and as special constructor to build a state machine from other data. See org.vishia.stateMGen.StateMGen.

StateComposite

public StateComposite()

The constructor of any StateComposite checks the class for inner classes which are the states. Each inner class which is instance of StateSimple is instantiated and stored both in the StateMachine.stateMap to find all states by its class.hashCode and in StateCompositeFlat.aSubstates for debugging only.

After them #buildStatePathSubstates() is invoked to store the state path in all states. Then StateCompositeFlat.createTransitionListSubstate(int) is invoked which checks the transition of all states recursively. Therewith all necessary data for the state machines's processing are created on construction.

See Also:

StateMachine#StateMachine(), StateComposite#buildStatePathSubstates(StateComposite, int), StateSimple#buildStatePath(StateComposite), StateCompositeFlat.createTransitionListSubstate(int), StateSimple#createTransitionList()

Method Detail

isInState

public final boolean isInState(StateSimple state)

Check whether this composite state has the given state as direct actual sub state

Parameters:

state - Only states of the own composite are advisable. It is checked in compile time with the strong type check with the generic type of state.

Returns:

true if it is in state.

entryDeepHistory

protected final int entryDeepHistory(java.util.EventObject ev)

This method is called from StateSimple.Trans.doEntry(EventObject) if the history state should be entered and all history states should be entered in sub states.

Returns:

or-relation of all return values of StateSimple.entry(EventObject), especially bit StateSimpleBase#mRunToComplete.

doEntryDeepHistory

private static final int doEntryDeepHistory(StateSimple state,
                                            java.util.EventObject ev)

Execution routine of enter the deep history.

• Enters all states in the statePath from the StateSimple.ixCompositeState_inStatePath.
• If the state is a StateComposite the entryDeepHistory(EventObject) will be called recursively.
• If the state is a StateParallel entryDeepHistory(EventObject) will be called for all parallel states.

Parameters:

state - The stored current state used as history.

ev -

Returns:

see entryDeepHistory(EventObject)

entryShallowHistory

public final int entryShallowHistory(java.util.EventObject ev)

This method should be called from outside if the history state should be entered but the default state of any sub state should be entered.

Parameters:

isProcessed - The bit StateSimpleBase#mEventConsumed is supplied to return it.

Returns:

isProcessed, maybe the additional bits StateSimpleBase#mRunToComplete is set by user.

processEvent

int processEvent(java.util.EventObject evP)

Processes the event for the states of this composite state. First the event is applied to the own (inner) states invoking either its processEvent(EventObject) which calls this method recursively.

If this method returns with StateSimpleBase#mRunToComplete that invocation is repeated in a loop, to call the transition of the new state too. But if the event was consumed by the last invocation, it is not supplied again in the loop, the event parameter is set to null instead. It means only conditional transitions are possible. This behavior is conform with the UML definition.

If the loop would not terminate because any state have a valid transition and the state machine switches forever, the loop is terminated with an exception for a number of maxStateSwitchesInLoop. This exception occurs if the user stateMachine conditions are faulty only.

At least the StateSimple._checkTransitions(EventObject) of this state is invoked but only if the event is not processed or the state contains non-event triggered (conditional) transitions. Last one is signified by the StateSimple.modeTrans.

This method overrides the StateSimple.processEvent(EventObject) which is overridden by StateParallel.processEvent(EventObject) too to provide one method for event processing for all state kinds with the necessary different handling.

Return bits:

• StateSimpleBase#mEventConsumed as result of the inside called StateSimple._checkTransitions(EventObject) to remove the event for further usage in an enclosing state processing.
• StateSimpleBase#mRunToComplete is not delivered because it has no sense outside.
• StateSimpleBase#mRunToComplete

Overrides:

processEvent in class StateSimple

Parameters:

evP - The event.

Returns:

Some bits defined in StateSimple

printStateSwitchInfo

private void printStateSwitchInfo(StateSimple statePrev,
                                  java.util.EventObject evTrans,
                                  int cont)

assembleDstState

private void assembleDstState(java.lang.StringBuilder uStateNext,
                              StateSimple stateAct1)

XXXexitTheState

void XXXexitTheState(int level)

Exits first the actual sub state (and that exits its actual sub state), after them this state is exited. It calls StateSimple#exitTheState() which invokes the maybe application overridden StateSimple.exit() routine.

getStatePath

public java.lang.CharSequence getStatePath()

Description copied from class: StateSimple

Gets the path to this state. The path is build from the StateSimple.stateId of all enclosing states separated with a dot and at least this stateId. For example "topStateName.compositeState.thisState".

Overrides:

getStatePath in class StateSimple

infoAppend

public java.lang.CharSequence infoAppend(java.lang.StringBuilder u)

Description copied from interface: InfoAppend

Appends or returns tan information about the instance. It is similar Object.toString() but it works with a given StringBuilder.
Application pattern:

 StringBuilder u = new StringBulder(1000);
 u.append(something_else);
 
 myInstance.infoAppend(u);     //uses this interface
 
 u.append(some_more);
 System.out.append(u);             //output the information
 String savedInfo = u.toString();  //save permanent.
 

Implementing pattern

 QOverride public infoAppend(StringBuilder u) {
   if(u == null){ u = new StringBuilder(); }  //it can be null!
   u.append(special_information).append(": ").append(somewhatElse);
   return u;
 }
 

Contiguity with toString: It uses the same information, assembled in a StringBuilder:

 QOverride public String toString(){ return infoAppend(null).toString()); } 
 

Specified by:

infoAppend in interface InfoAppend

Overrides:

infoAppend in class StateSimple

Parameters:

u - if not null then the info is appended to u, u is returned.
if null then a String can be returned if it is sufficient.

Returns:

u if given or a new StringBuilder instance which contains the info or a String if it is sufficient.

toString

public java.lang.String toString()

Description copied from class: StateSimple

Returns the state Id and maybe some more debug information.

Overrides:

toString in class StateSimple

See Also:

Object.toString()