Skip to content
Software Architecture Guide

State Machine Transition

Explanation

Section titled “Explanation”

A state machine describes the states an object can be in. A transition is the switch from one active state to another. An event triggers it (see State and Event).

Guard. A guard is a yes/no check. The system runs it first. If it returns false, the transition does not fire.

Completion transitions. Some transitions have no trigger event. They are called completion (or anonymous) transitions. They fire as soon as their source state becomes active, unless a guard blocks them.

Kinds of transitions. The kind tells you whether the source state is left:

  • An external transition exits its source state.
  • A local transition exists only inside a composite state (see Composite State). It does not exit that containing state.
  • An internal transition runs inside the source state. It does not exit or enter that state. It can only be defined when the source is a state.

Internal transitions are not drawn as explicit arrows in diagrams. A reader must find them elsewhere in the state’s description.

Deferred events. A state can defer an event. While that state is active, the system does not process the event. It keeps the event for later.

For the label format of trigger, guard, and effect, see Transition Syntax (Trigger, Guard, Behavior).

Example

Section titled “Example”

Picture an order object with the states “Placed” and “Paid”.

The event “payment received” triggers a transition from “Placed” to “Paid”. A guard checks the amount. If the check returns false, the transition does not fire and the order stays in “Placed”.

Now suppose “Paid” has a transition with no trigger. It fires as soon as “Paid” becomes active, unless its guard blocks it.

Trade-offs

Section titled “Trade-offs”

Internal transitions keep a state active, so they avoid leaving and re-entering it. The cost is visibility: they are not drawn as arrows, so a reader scanning only the arrows can miss them. Completion transitions fire immediately, so a missing or wrong guard can push the object onward at once.

A guarded transition from Placed to Paid, and a trigger-free completion transition from Paid to Shipped.

Diagram source 
@startuml
[*] --> Placed
Placed --> Paid : paymentReceived [amountCorrect]
Paid --> Shipped
@enduml

Checks

Section titled “Checks”
  • Each transition that must not always fire has a guard, and the guard is a yes/no check.
  • Transitions without a trigger are intentional completion transitions, and any guard on them is stated.
  • Internal transitions are documented somewhere other than as arrows, since diagrams do not draw them.
  • Local transitions appear only inside composite states.
  • Events that a state defers are identified, because they are kept and not processed while that state is active.
Section titled “Related”

Sources

Section titled “Sources”