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 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.
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 ..."
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.
|
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 |
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 |
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. |
The statechart language comes with two built-in functions that can be used inside a guard or effect expression:
| Built-in Function | Meaning |
|---|---|
event.value |
Returns the payload of an event. Note, that the event needs to be raised when
.value is called.
|
valueof(event) |
Same as the one before except member acces is not available if the payload is some complex type. This expression will be deprecated in the future. |
active(state) |
Returns
true if the given state is active, otherwise
false. This function is especially useful in combination with orthogonality.
|
When a state transition occurs, the specified reaction effects are executed in a defined execution order:
Consider the following simple example:
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).