States and transitions

States and transitions are the basic building blocks of a statechart. States and transitions are contained in regions. At each point of a statechart’s execution, there is at most one active state per region.

States are connected by transitions. Transitions are directed, therefore states have incoming and outgoing transitions. All states must have at least one incoming transition.

Transition reactions

Transition reactions specify under which conditions a state transition is taken. Reactions have the following syntax:

trigger [guard] / effect

A state transition is taken when its trigger is raised and the guard condition is satisfied. When the transition is taken, its effect actions are executed.

Completion transitions

This feature is compatible with OMG UML 2.5.1 specification. (For more details please see the corresponding documentation under chapter 14.2.3.8.3)

Completion transitions are semantically identical to regular transitions but with optionally only effects specified for them. This means „empty” transitions are allowed and considered completion transitions.

They are immediately taken when the transition’s source state is " completed" and they have priority over any other events, thus they are dispatched before any other pending event occurrences in the event pool.
This also means that these kinds of transitions implicitly raises completion events, which are raised and consumed throughout the statechart’s execution (and with that, they are present in the code generated from it).

A state is considered completed when all of its entry actions are executed (if there are any). A Composite states is considered completed when all of its subregions reach their final state . This means completion transitions can only be used with composite states if all subregions contain a final state.

Completion transitions can’t be used with source states that contain local reactions. Those states do not complete and adding a completion transition is considered as an error. A validation check will add a error message: „Completion transition is not allowed with local reactions”.

Defining other transitions with trigger(s) from the same leaf state as the completion transition will raise a warning with a message: „Dead transition. This transition can not be taken due to completion transition.” This is because these will never be taken due to the precedence of the completion transition. Also defining multiple completion transitions from the same state will result in a warning for both transitions with the message: "Multiple completion transition. There should be only one completion transition from state ..."

Triggers

A transition reaction can specify the following triggers:

Trigger Syntax Examples Meaning
ev1 Event trigger, triggers when the event ev1 is raised. The used event needs to be declared in the definition section.
ev1, ev2 Multiple event triggers, triggers when one of the events ev1 or ev2 is raised. The used events need to be declared in the definition section.
after 10s Time trigger, trigger after given amount of time.
always Always trigger, triggers always. Can be omitted when used with a guard.
oncycle Oncycle trigger, same as always trigger.
else Else trigger, only valid on outgoing transitions of choice states to denote the default transition if no other outgoing transition can be taken.
default Default trigger, same as else trigger.

Guards

The reaction guard is optional. If specified, it needs to be a boolean expression. Here are some examples of valid guard conditions:

 Guard Syntax Examples Expression Kind
 [var1 && !var2] Logical AND, OR, NOT
 [var1 > 0 && var1 <= 10] Logical comparisons <, <=, >, >=
 [var1 == 10 && var2 != 17] Logical equality or inequality
 [isOdd(var1)] Operation calls with boolean return type
 [var1] Boolean variables or constants

Effects

The reaction effect is optional. If specified, the effect is executed when the transition is taken. Multiple effects are separated by a semicolon. The last effect has no trailing semicolon.

Effect Syntax Examples  Meaning
/ var1+=10; var2=var1 Variable assignment
/ calculate(var1, var2) Operation call
/ raise ev1 Event raising
/ raise ev2 : 42 Event raising with payload
/ var1 > 10 ? var1=0 : var1++ Conditional expression
/ var1 << 8 Bit shifting

State reactions

A state can also define reactions. The syntax is the same as for transitions. In addition to the above mentioned examples, a state can also define entry and exit reactions.

 State Reaction Examples Meaning
entry / var1=10 Entry reaction, is executed when the state is entered.
exit / var1=0 Exit reaction, is executed when the state is exited.
ev1 / var1+=1 Local reaction, is executed when no outgoing transition can be taken.

Built-in functions

The statechart language comes with two built-in functions that can be used inside a guard or effect expression:

 Built-in Function Meaning
valueOf(even) Returns the payload of an event. Note, that the event needs to be raised when valueOf is called.
active(state) Returns true if the given state is active, otherwise false. This function is especially useful in combination with orthogonality.

Basic execution flow

When a state transition occurs, the specified reaction effects are executed in a defined execution order:

  1. All source state’s exit actions are executed
  2. All transition actions are executed
  3. All target state’s entry actions are executed

Consider the following simple example:

Example to understand execution order of reaction effects

When StateA is entered, its entry reaction is executed first ( a=1). When event ev1 is raised, the transition towards StateB is taken. As StateA is left, its exit reaction is executed ( b=1) before the transition reaction is executed ( c=1), following by entering StateB and executing its entry reaction ( d=1). While StateB is active, each time the event ev1 is raised, the state’s local reaction is executed ( d++). Note, that this is a different behavior compared to StateB having an outgoing transition pointing to itself, as taking such a self-transition would also invoke the state’s exit and entry reactions. Finally, when event ev2 is raised, StateB is left and its exit reaction is executed ( e=1, followed by the transition’s reaction ( f=1), and StateA's entry reaction ( a=1).