UML State Machine Diagrams

A UML state machine diagram models the states one object passes through during its lifetime and the events that move it from one state to the next. It applies when the response to an input depends on what happened earlier. An order can be cancelled while it is unpaid but not after it ships, and a connection accepts data only once it is open. Developers use it for device controllers and protocol handlers, and to write down which status changes an application allows.

What is a UML State Machine Diagram?

A state machine diagram describes an object as a set of states connected by transitions. The object stays in a state until an event occurs that a transition out of that state accepts. It shows:

• States: named situations the object remains in, such as Idle or Charging
• Transitions: arrows from one state to another, labeled with the event that fires them
• Triggers: the events a transition accepts, including operation calls, signals, time events, and changes of condition
• Guards: conditions in square brackets that must be true for the transition to fire
• Effects: behavior run while the transition fires
• Entry, exit, and do behaviors: behavior attached to a state rather than to a transition
• Pseudostates: points the machine does not stay in, including initial, choice, junction, fork, join, and terminate
• Composite states and regions: states that contain other states, and the parts a state machine or a composite state is divided into

A state machine handles one event at a time. The next event is dispatched only after the previous one has been handled and the machine has settled in a stable configuration, which UML calls run-to-completion. An event is discarded when no transition of the active states accepts it and no active state defers it.

UML defines two kinds of state machine. A behavior state machine specifies what an object does in response to events. A protocol state machine specifies the order in which the operations and signal receptions of a classifier, interface, or port may be invoked. Its name carries the keyword «protocol». Its transitions have no effects. Its states have no entry, exit, or do behavior, and may carry an invariant in square brackets.

Why Use State Machine Diagrams?

• Specifying a status field: the diagram names every status value and every change allowed between them.
• Specifying device and protocol behavior: an event that no transition of the active states accepts is either deferred or discarded, and the diagram states which.
• Filling in one participant of an interaction: a sequence diagram shows the messages between objects, and the state machine shows what one of those objects does with them.
• Finding unhandled events: for each state, checking every event that can occur shows which events that state has no transition for.

Core Components and Notation

State and Transition

A state is a rounded rectangle with the state name inside. The object stays in that state until an event moves it out. A transition is an arrow between two states, labeled trigger [guard] / effect. The trigger names the event that fires the transition, usually an operation call or a signal. A trigger can also be a time event, written after 30 seconds, or a change event, written when (temperature > 100). The guard is a condition that must be true for the transition to fire. The effect is behavior run while the transition fires. All three parts of the label are optional. In a support ticket, Open and In progress are states, and the arrow between them carries assign [agent available] / notify agent.

Initial, Final, and Terminate

An initial pseudostate is a small solid circle. It marks where a region starts, and the transition out of it carries no trigger and no guard. A final state is a small solid circle inside a hollow circle. Reaching it means the region that contains it has completed. A terminate pseudostate is a cross. Entering it stops the machine at once, without exiting any state and without running any exit behavior.

A library loan starts at an initial pseudostate and ends at a final state after Returned. A loan for a book reported lost reaches a terminate pseudostate instead.

Entry, Exit, and Do Behaviors

A state may be divided into compartments by a horizontal line. The name goes in the top compartment, and the behaviors below it, one per line. An entry behavior runs when the state is entered. An exit behavior runs when the state is left. A do behavior starts after the entry behavior and runs for as long as the state is active, or until it finishes on its own. Leaving the state aborts a do behavior that has not finished.

A state has a further compartment for internal transitions, below the behavior lines. An internal transition is a line of the form trigger [guard] / effect in that compartment. The state handles the event and is not exited, so neither the exit nor the entry behavior runs. A deferred trigger is listed the same way, with / defer after the trigger name. The event stays pending for as long as an active state defers it.

A thermostat in Heating opens the valve on entry and closes it on exit. Its do behavior holds the target temperature. The internal transition setpoint changed / update target changes the target without leaving Heating, and schedule updated / defer holds a schedule change until the thermostat is Idle.

Composite State

A composite state contains one or more regions, drawn nested inside it. A region holds states and transitions of its own, and may have an initial pseudostate and a final state. A transition drawn from the border of a composite state applies to every substate inside it. A border transition that ends outside the composite state exits it, so the exit behavior of the composite state runs. A composite state whose contents are drawn on a separate diagram may carry an icon instead, usually in the lower right corner. The icon is two small circles joined by a line.

A washing machine in Running passes through Wash, Rinse, and Spin. A transition from the border of Running on door opened leaves the composite state from any of those three substates.

Orthogonal Regions

An orthogonal state is a composite state divided by dashed lines into two or more regions. Each region holds its own states and runs concurrently with the others, so the object is in one state from every region at the same time. The state's name may be placed in a tab on the outside of the top edge instead of inside the rectangle. A solid line separates the text compartments from the regions.

A printer has one region with Idle and Printing, and a second region with Paper loaded and Paper empty.

Fork and Join

A fork is a short heavy bar with one incoming arrow and two or more outgoing arrows that end in different regions of an orthogonal state. A join is the same bar with one incoming arrow from each of several regions and a single outgoing arrow. It waits for all of them. Transitions leaving a fork and transitions entering a join carry no trigger and no guard. An alarm panel forks on arm into Perimeter watched and Motion watched, and the two regions join back into Disarmed.

Choice and Junction

A choice pseudostate is a diamond. The guards on its outgoing transitions are evaluated when the flow reaches the diamond, so a guard can test a value that an effect earlier in the same transition produced. A junction pseudostate is a small solid circle. Its guards are evaluated before the transition starts. A junction also merges several incoming transitions into a single outgoing one. It uses the same circle as an initial pseudostate, and always has at least one incoming transition. Both accept the predefined guard [else] on at most one outgoing transition, taken when no other guard is true. A parcel locker weighs the parcel, and a choice then sends it to Small compartment or Large compartment.

Practical Example: Electric Vehicle Charging Connector

The diagram models one connector on a public charging station, from the moment a cable is plugged in until the connector is free again.

1. The initial pseudostate leads to Available, where the connector waits with no cable attached.
2. cable plugged moves the machine into the composite state Session, which has entry/ lock connector and exit/ unlock connector.
3. Inside Session, the initial pseudostate leads to Authorizing, whose do behavior waits for a card or an app token.
4. token presented runs the authorization check and reaches a choice. [authorized] continues to Charging, and [else] returns to Authorizing.
5. Charging has entry/ close contactor, do/ deliver current, and exit/ open contactor. pause requested moves to Suspended, and resume moves back to Charging.
6. charge complete in Charging reaches the final state inside the region. Session has then completed, and it generates a completion event. The transition from Session to Available carries no trigger and fires on that event, running the effect / record energy total. UML calls it a completion transition.
7. Two transitions leave the border of Session and apply to Authorizing, Charging, and Suspended alike. cable unplugged returns to Available. fault detected leads to Faulted, and reset returns from there to Available.
8. Both border transitions exit Session, so exit/ unlock connector runs on each of them. It also runs when the completion transition fires.

Best Practices

• Give every choice pseudostate an [else] branch: when the flow reaches a choice and no guard is true, the model is ill formed.
• Write guards so that only one of them can be true at a time: when one event enables two transitions and both guards hold, which one fires is not defined by the specification.
• Keep side effects out of guard expressions: a guard that changes something while it is evaluated is ill formed.
• Leave triggers and guards off fork and join transitions: the specification allows neither on a transition leaving a fork or entering a join.
• Put an initial pseudostate in every region: what happens when a region without one is entered by default is not defined.
• Use an internal transition when the state must not be re-entered: an internal transition runs neither the exit nor the entry behavior of its state.
• Defer an event that a later state has to handle: a deferred event stays pending until the machine reaches a configuration that no longer defers it.
• Do not put work that has to finish in a do behavior: exiting the state aborts a do behavior that is still running.

Conclusion

A state machine diagram records the states one object can be in and the events that move it between them. Behavior that runs inside a state or while a transition fires is written on the same diagram. The notation has no symbol for another object. Other objects are named only in the text of a guard or an effect. The messages exchanged between several objects belong on a sequence diagram, and the class whose instances the state machine describes is defined on a class diagram. A sequence of steps that never waits for an event can be drawn with completion transitions, but the activity diagram is the notation built for it.