UML State Diagrams

Complete guide to UML State Diagrams (State Machine Diagrams): learn how to model object lifecycles, state transitions, and state-dependent behavior. Master state machines for designing robust systems.

1. What are State Diagrams?
2. States
3. Transitions
4. Initial and Final States
5. Composite States
6. Best Practices
7. Practical Examples
8. Conclusion

1. What are State Diagrams?

State diagrams (also called state machine diagrams or statecharts) model the lifecycle of objects that have distinct states. They show the states an object can be in, the transitions between states, and the events that trigger those transitions.

State diagrams are particularly useful for:

Modeling objects with complex state-dependent behavior
Documenting object lifecycles
Designing stateful systems
Understanding when certain operations are valid
Identifying all possible states and transitions

Use state diagrams when an object's behavior depends on its current state and when the object transitions between a finite number of states in response to events.

2. States

2.1 What is a State?

A state represents a condition or situation during the life of an object in which it satisfies some condition, performs some activity, or waits for some event. States are shown as rounded rectangles.

2.2 State Notation

@startuml [*] --> Pending state Processing { state "Processing" as Proc { entry / initialize() do / process() exit / cleanup() } } Pending --> Processing note right of Pending Simple state end note note right of Processing State with entry action, do activity, and exit action end note @enduml

2.3 State Components

State Name: Identifies the state
Entry Action: Action executed when entering the state
Do Activity: Ongoing activity while in the state
Exit Action: Action executed when leaving the state

2.4 State Types

Simple State: Basic state with no substates
Composite State: State containing substates
Submachine State: State that references another state machine
History State: Remembers the last active substate

3. Transitions

3.1 What is a Transition?

A transition represents a change from one state to another in response to an event. Transitions are shown as arrows connecting states.

3.2 Transition Notation

@startuml [*] --> State1 State1 --> State2 : Simple transition State1 --> State3 : event State1 --> State4 : event / action State1 --> State5 : event [guard] / action note right of State2 Simple transition end note note right of State3 Transition with event end note note right of State4 Transition with action end note note right of State5 Full transition with event, guard, and action end note @enduml

3.3 Transition Components

Event: What triggers the transition (e.g., "orderPlaced", "paymentReceived")
Guard Condition: Boolean condition that must be true for transition to occur (e.g., [amount > 0])
Action: Behavior executed during the transition (e.g., /sendConfirmation())

3.4 Transition Syntax

Full transition syntax:

event[guard]/action

Examples:

paymentReceived[amount > 0]/sendConfirmation()
timeout/notifyUser()
cancel/cancelOrder()

3.5 Self-Transitions

A self-transition returns to the same state, triggering entry and exit actions:

@startuml [*] --> State State --> State : event / action note right of State Self-transition returns to the same state end note @enduml

4. Initial and Final States

4.1 Initial State

The initial state (pseudostate) marks the starting point of a state machine. Shown as a filled circle.

@startuml [*] --> State1 note right of State1 Initial state marks the starting point end note @enduml

4.2 Final State

The final state marks the end of a state machine. Shown as a filled circle with a surrounding circle.

@startuml State1 --> [*] note right of State1 Final state marks the end of state machine end note @enduml

4.3 Using Initial and Final States

Every state machine should have at least one initial state
Final states are optional (object may not terminate)
Composite states can have their own initial/final states
Multiple final states can represent different termination conditions

5. Composite States

5.1 What are Composite States?

Composite states contain substates, allowing you to model hierarchical state machines. They help manage complexity by grouping related states.

5.2 Composite State Notation

@startuml state "Order Processing" as OrderProcessing { [*] --> Validating Validating --> Processing Processing --> Completed Completed --> [*] } [*] --> OrderProcessing note right of OrderProcessing Composite state contains substates end note @enduml

5.3 History States

A history state (shallow or deep) remembers the last active substate when re-entering a composite state:

@startuml state Active { [*] --> State1 [*] --> State2 State1 --> State2 State2 --> State1 } note right of Active History state (H) remembers the last active substate end note @enduml

5.4 Concurrent States

States can be divided into concurrent regions (orthogonal regions) that execute simultaneously:

@startuml state "Order State" as OrderState { state Payment { [*] --> PaymentState1 PaymentState1 --> PaymentState2 } -- state Shipping { [*] --> ShippingStateA ShippingStateA --> ShippingStateB } } [*] --> OrderState note right of OrderState Concurrent regions execute simultaneously end note @enduml

6. Best Practices

6.1 Identify All States

List all possible states the object can be in
Consider error states and exceptional conditions
Include intermediate states, not just start and end
Validate states with domain experts

6.2 Define Clear Transitions

Every transition should have a clear trigger (event)
Use guard conditions to clarify when transitions occur
Ensure all states are reachable
Avoid unreachable states

6.3 Use Composite States

Group related states into composite states
Use composite states to manage complexity
Keep state machines readable and understandable
Don't nest too deeply (2-3 levels usually sufficient)

6.4 Document Actions

Document entry/exit actions clearly
Specify transition actions
Keep actions simple and focused
Use consistent naming conventions

6.5 Validate Completeness

Ensure all valid transitions are modeled
Check for missing states or transitions
Verify state machine handles all scenarios
Test state machine logic

7. Practical Examples

7.1 Order State Machine

@startuml [*] --> Pending Pending --> Confirmed : orderPlaced Confirmed --> Paid : paymentReceived Confirmed --> Cancelled : cancel / refund Paid --> Shipped : itemsShipped Shipped --> Delivered : delivered Delivered --> [*] Cancelled --> [*] @enduml

7.2 User Account State Machine

@startuml [*] --> Inactive Inactive --> Pending : register Pending --> Active : verifyEmail Active --> Suspended : suspend Suspended --> Active : reactivate Suspended --> Deleted : delete Deleted --> [*] @enduml

7.3 Payment Processing State Machine

@startuml state "Payment Processing" as PaymentProcessing { [*] --> Validating Validating --> Processing : valid Validating --> Failed : invalid Processing --> Completed : success Completed --> [*] Failed --> [*] } [*] --> PaymentProcessing @enduml