Hierarchical state machines allow to enclose a group of states within a composite state.

This introduces a bunch of new situations for transitions within a state machine. Regardless of the fact that transtions may start from or end on composite states, the state machine will transfer the active state of the state machine from a leaf simple state to (usually) another leaf simple state. For such cases the transition effectively crosses the border of the involved composite states which causes that the entry or exit actions of the composite state are executed additionally to the entry or exit actions of the ultimate leaf simple states.

The transition excution rules are as follows:

1. Targeting a sub-state of a composite state from outside of the composite state will execute the entry action of the composite state and then the entry action of the target state. The actions of the composite state are common for all sub-states.

2. Targeting a composite state at its border instead of a sub-state will enter the defined initial state of the enclosed group of sub-states, unless the history functionality is enabled.

3. Targeting a state outside of a composite state from one of its sub-states will execute the exit action of the leaf simple state and then the exit action of the composite state.

4. Starting a transition at the composite state will exit from any sub-state in case the state machine resides in a sub-state. Both the exit action of the sub-state and the exit action of the composite state will be executed.

5. Starting a transition from a sub-state and targeting a sub-state within the same composite state will execute only the exit and entry actions of the sub-states and not those of the composite state.

6. Starting a transition from a sub-state, leaving the composite state and re-entering a composite state (eventually the same) will execute the composition of all exit and entry actions of the involved states.

   This transition attaches with a special aggregation symbol to the composite state, but the actual source state is a sub-state of the composite state. The aggregation symbol has two effects: First it defines to which state the transition belongs and which priority it has in case of conflicting transitions. Second it defines that the composite state shall be left and re-entered.

Figure 1: State machine diagram with composite state and transitions.

Figure 2: Tree structure for the above state machine with composite state.

Sub-states of a composite state are added as a sequence of State..EndState statement pairs grouped through an embedding Region..EndRegion statement pair inside the composite state State..EndState statement pair, after any Transition statements of the composite state.

See below sample code:

StateMachineTemplate t = new StateMachineTemplate();
t.Region(StateA, false);
    t.State(StateA, null, null);
        t.Transition(Transit1, StateB1A, Event1, null, null);
        t.Transition(Transit2, StateB, Event2, null, null);
    t.EndState();
    t.State(StateB, null, null);
        t.Transition(Transit4, StateA, Event4, null, null);
        t.Transition(Transit6, StateB1A, StateB1B, Event6, null, null);
        t.Region(StateB1A, false);
            t.State(StateB1A, null, null);
                t.Transition(Transit3, StateA, Event3, null, null);
                t.Transition(Transit5, StateB1B, Event5, null, null);
            t.EndState();
            t.State(StateB1B, null, null);
            t.EndState();
        t.EndRegion();
    t.EndState();
t.EndRegion();

All transitions of the current state and its hierarchical ancestors are subject to be executed if their event arrives and/or the guard condition is fulfilled. In order to maintain a defined precedence across conflicting transitions, the transitions starting from the outer composite states take precedence over transitions starting from a sub-state.

Unlike the other transitions, Transit6 explicitly specifies the source state StateB1A to indicate that the transition starts from a sub-state of the state to which it is aggregated.