State Transitions and Lifecycles — State and Behavior… | OneNoughtOne

0/86

System Design (LLD)State and Behavior Modeling

State and Behavior Modeling

LevelBeginner

Duration60 mins

TopicState and Behavior Modeling

2 / 4

State Transitions and Lifecycles

Objects in Motion

Objects don't just have state—they change state. An order moves from pending to confirmed to shipped. A user transitions from anonymous to authenticated to logged-out. A document evolves from draft to review to published. These changes aren't random; they follow patterns, rules, and constraints that we call state transitions . Understanding state transitions transforms how you design objects. Instead of thinking about static data structures, you begin to see objects as living entities with histories, futures, and well-defined paths through their existence. This temporal perspective is essential for building robust, predictable systems.

What You Will Learn

By the end of this page, you will understand how to model state transitions explicitly, design object lifecycles with clear phases, enforce valid transition rules, and use state machines to create predictable, self-documenting object behavior.

What Are State Transitions?

A state transition is a change in an object's state from one valid configuration to another. While the previous page discussed state as a snapshot, transitions are the edges that connect one snapshot to the next. Formally, a state transition can be described as: Initial State (S₁) : The object's state before the transition Trigger/Event : What causes the transition (method call, external event, time passage) Guard Condition : Optional conditions that must be true for the transition to occur Action : Operations performed during the transition Final State (S₂) : The object's state after the transition

OrderTransition.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
public class Order {
    private OrderStatus status;
    private LocalDateTime statusChangedAt;
    
    public enum OrderStatus {
        PENDING, CONFIRMED, PROCESSING, SHIPPED, DELIVERED, CANCELLED
    }
    
    /**
     * State Transition: PENDING → CONFIRMED
     * 
     * Trigger: confirm() method call
     * Guard: status must be PENDING
     * Action: update status, record timestamp
     * Result: status becomes CONFIRMED
     */
    public void confirm() {
        // Guard condition: only PENDING orders can be confirmed
        if (status != OrderStatus.PENDING) {
            throw new IllegalStateException(
                "Cannot confirm order in " + status + " state. " +
                "Only PENDING orders can be confirmed."
            );
        }
        
        // Action: perform the transition
        OrderStatus previousStatus = this.status;
        this.status = OrderStatus.CONFIRMED;
        this.statusChangedAt = LocalDateTime.now();
        
        // Transition complete: S₁(PENDING) → S₂(CONFIRMED)
        log.info("Order transitioned: {} → {}", previousStatus, this.status);
    }
    
    /**
     * State Transition: CONFIRMED → PROCESSING
     * Similar pattern with different guard and actions
     */
    public void startProcessing() {
        if (status != OrderStatus.CONFIRMED) {
            throw new IllegalStateException(
                "Cannot start processing order in " + status + " state"
            );
        }
        this.status = OrderStatus.PROCESSING;
        this.statusChangedAt = LocalDateTime.now();
    }
}

Transitions Are Domain Logic

State transition rules encode business logic. "Orders can only be cancelled before shipping" is a business rule expressed as a transition constraint. When you model transitions explicitly, you make business rules visible, testable, and enforceable in code rather than just in documentation.

The Object Lifecycle

Every object has a lifecycle —a pattern of states it moves through from creation to destruction. Understanding lifecycles helps you design objects that behave predictably at every phase of their existence. A typical object lifecycle includes:

Lifecycle Phases

•Creation/Birth — Object is instantiated and enters its initial state. Constructors establish invariants and set up initial attribute values.
•Initialization — Object may need additional setup after construction (dependency injection, configuration loading, resource acquisition).
•Active/Operational — The object's main working phase. Most state transitions occur here as the object performs its purpose.
•Suspended/Paused — Some objects can be temporarily inactive while retaining their state (serialized, pooled, cached).
•Termination/Death — Object reaches a final state and releases resources. Some objects have explicit terminal states; others are simply garbage collected.

Lifecycle Examples Across Different Object Types
Object Type	Creation	Active States	Terminal States
Database Connection	connect()	OPEN, BUSY, IDLE	CLOSED
HTTP Request	new Request()	PENDING, IN_PROGRESS	COMPLETED, FAILED, TIMEOUT
User Session	login()	ACTIVE, IDLE	EXPIRED, LOGGED_OUT
Thread	new Thread()	RUNNABLE, BLOCKED, WAITING	TERMINATED
Order	new Order()	PENDING → ... → SHIPPED	DELIVERED, CANCELLED, REFUNDED

ConnectionLifecycle.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
public class DatabaseConnection {
    
    public enum ConnectionState {
        // Creation phase
        INITIALIZING,
        
        // Active phase  
        OPEN,        // Ready to execute queries
        BUSY,        // Currently executing a query
        
        // Suspended phase
        IDLE,        // Open but unused, may be returned to pool
        
        // Terminal phase
        CLOSED,      // Permanently closed, cannot be reused
        FAILED       // Connection failed, cannot be reused
    }
    
    private ConnectionState state = ConnectionState.INITIALIZING;
    private final String connectionString;
    private Socket socket;
    
    public DatabaseConnection(String connectionString) {
        this.connectionString = connectionString;
        // Object exists but is not yet connected
    }
    
    // Creation → Active transition
    public void connect() throws ConnectionException {
        if (state != ConnectionState.INITIALIZING) {
            throw new IllegalStateException("Can only connect from INITIALIZING state");
        }
        
        try {
            this.socket = establishConnection(connectionString);
            this.state = ConnectionState.OPEN;
        } catch (Exception e) {
            this.state = ConnectionState.FAILED;  // Terminal state on failure
            throw new ConnectionException("Failed to connect", e);
        }
    }
    
    // Active → Active transition
    public ResultSet executeQuery(String sql) {
        if (state != ConnectionState.OPEN && state != ConnectionState.IDLE) {
            throw new IllegalStateException("Cannot execute query in " + state + " state");
        }
        
        this.state = ConnectionState.BUSY;
        try {
            ResultSet result = doExecute(sql);
            this.state = ConnectionState.OPEN;
            return result;
        } catch (Exception e) {
            // Decide: return to OPEN, go to FAILED, or stay BUSY?
            this.state = ConnectionState.OPEN;  // Recoverable error
            throw e;
        }
    }
    
    // Active → Terminal transition
    public void close() {
        if (state == ConnectionState.CLOSED) {
            return;  // Idempotent: already closed
        }
        
        if (socket != null) {
            socket.close();
        }
        this.state = ConnectionState.CLOSED;
        // Object is now in terminal state; no further transitions possible
    }
    
    public boolean isTerminal() {
        return state == ConnectionState.CLOSED || state == ConnectionState.FAILED;
    }
}

Terminal States Are Final

Once an object reaches a terminal state, it should not transition to any other state. A CLOSED connection cannot become OPEN again. Attempting to use an object in a terminal state should throw an exception. Design terminal states explicitly and enforce their finality.

State Machines in Object Design

A Finite State Machine (FSM) is a formal model for objects with discrete states and well-defined transitions. State machines are powerful tools for designing complex objects because they make all possible states and transitions explicit and verifiable. Components of a State Machine: States : A finite set of possible states (enum values, string constants, or state objects) Initial State : The state the machine starts in Terminal States : States from which no further transitions are possible Events/Triggers : Inputs that cause transitions Transition Table : Rules mapping (current state, event) \to (next state, action)

OrderStateMachine.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
public class OrderStateMachine {
    
    public enum State {
        PENDING, CONFIRMED, PROCESSING, SHIPPED, DELIVERED, CANCELLED
    }
    
    public enum Event {
        CONFIRM, START_PROCESSING, SHIP, DELIVER, CANCEL
    }
    
    // Transition table: (current state, event) → next state
    private static final Map<State, Map<Event, State>> TRANSITIONS = Map.of(
        State.PENDING, Map.of(
            Event.CONFIRM, State.CONFIRMED,
            Event.CANCEL, State.CANCELLED
        ),
        State.CONFIRMED, Map.of(
            Event.START_PROCESSING, State.PROCESSING,
            Event.CANCEL, State.CANCELLED
        ),
        State.PROCESSING, Map.of(
            Event.SHIP, State.SHIPPED
            // Note: Cannot cancel once processing starts
        ),
        State.SHIPPED, Map.of(
            Event.DELIVER, State.DELIVERED
        )
        // DELIVERED and CANCELLED are terminal states: no transitions out
    );
    
    private State currentState;
    
    public OrderStateMachine() {
        this.currentState = State.PENDING;  // Initial state
    }
    
    public void fire(Event event) {
        // Look up valid transitions from current state
        Map<Event, State> validTransitions = TRANSITIONS.get(currentState);
        
        if (validTransitions == null || !validTransitions.containsKey(event)) {
            throw new IllegalStateException(String.format(
                "Invalid transition: cannot apply %s in state %s. " +
                "Valid events: %s",
                event, currentState,
                validTransitions != null ? validTransitions.keySet() : "none"
            ));
        }
        
        State previousState = currentState;
        currentState = validTransitions.get(event);
        
        // Notify listeners, execute actions, etc.
        onTransition(previousState, event, currentState);
    }
    
    public boolean canFire(Event event) {
        Map<Event, State> validTransitions = TRANSITIONS.get(currentState);
        return validTransitions != null && validTransitions.containsKey(event);
    }
    
    public Set<Event> getValidEvents() {
        Map<Event, State> validTransitions = TRANSITIONS.get(currentState);
        return validTransitions != null ? validTransitions.keySet() : Set.of();
    }
    
    private void onTransition(State from, Event event, State to) {
        log.info("Order: {} --[{}]--> {}", from, event, to);
    }
}

Benefits of State Machine Design

•Explicit States: All possible states are enumerated. No hidden or unexpected states.
•Valid Transitions Only: Invalid transitions are rejected at runtime with clear error messages.
•Self-Documenting: The transition table IS the documentation. No ambiguity about what's allowed.
•Testable: Each transition can be tested independently. Coverage means all transitions are verified.
•UI Enablement: canFire() and getValidEvents() directly inform UI about available actions.

When to Use State Machines

Use state machines when an object has discrete states with restricted transitions (orders, workflows, connections). Don't use them for objects with continuous or combinatorial state (a Point with x,y coordinates, or a Document with arbitrary text content). State machines shine for lifecycle management.

Transition Guards and Actions

Real-world state transitions are rarely as simple as "go from A to B." They often have conditions that must be met and side effects that must occur. These are modeled as guards and actions . Guards are boolean conditions that must be true for a transition to be allowed, beyond just being in the right state. Actions are operations executed during the transition—before, during, or after the state change.

Guard Examples

•Order can ship only if inventory available
•Payment can complete only if funds sufficient
•File can save only if not read-only
•User can login only if not already locked out
•Timer can start only if not already running

Action Examples

•Send confirmation email on order confirm
•Debit account on payment complete
•Write to disk on file save
•Create audit log on any state change
•Release resources on connection close

GuardsAndActions.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
public class PaymentProcessor {
    
    private PaymentState state = PaymentState.PENDING;
    private final BigDecimal amount;
    private final Account sourceAccount;
    private final Account targetAccount;
    private String transactionId;
    
    /**
     * Transition: PENDING → COMPLETED
     * 
     * Guards:
     *   - Source account has sufficient balance
     *   - Source account is not frozen
     *   - Target account is active
     * 
     * Actions:
     *   - Debit source account
     *   - Credit target account
     *   - Generate transaction ID
     *   - Send notification
     *   - Log audit trail
     */
    public void complete() {
        // Validate current state
        if (state != PaymentState.PENDING) {
            throw new IllegalStateException("Can only complete PENDING payments");
        }
        
        // === GUARD CONDITIONS ===
        if (sourceAccount.getBalance().compareTo(amount) < 0) {
            throw new InsufficientFundsException(
                "Source account balance " + sourceAccount.getBalance() + 
                " is less than payment amount " + amount
            );
        }
        
        if (sourceAccount.isFrozen()) {
            throw new AccountFrozenException("Source account is frozen");
        }
        
        if (!targetAccount.isActive()) {
            throw new InvalidAccountException("Target account is not active");
        }
        
        // All guards passed; execute transition
        
        // === ENTRY ACTIONS (before state change) ===
        this.transactionId = generateTransactionId();
        log.info("Starting payment {}: {} from {} to {}", 
            transactionId, amount, sourceAccount.getId(), targetAccount.getId());
        
        // === TRANSITION ACTIONS (during state change) ===
        try {
            sourceAccount.debit(amount);
            targetAccount.credit(amount);
            
            // === STATE CHANGE ===
            this.state = PaymentState.COMPLETED;
            
        } catch (Exception e) {
            // Transition failed; move to error state
            this.state = PaymentState.FAILED;
            log.error("Payment {} failed: {}", transactionId, e.getMessage());
            throw e;
        }
        
        // === EXIT ACTIONS (after state change) ===
        notificationService.sendPaymentConfirmation(this);
        auditLog.recordPayment(transactionId, sourceAccount, targetAccount, amount);
        
        log.info("Payment {} completed successfully", transactionId);
    }
    
    // Guards can be checked without triggering transition
    public boolean canComplete() {
        return state == PaymentState.PENDING
            && sourceAccount.getBalance().compareTo(amount) >= 0
            && !sourceAccount.isFrozen()
            && targetAccount.isActive();
    }
    
    // Get detailed reasons why completion is blocked
    public List<String> getCompletionBlockers() {
        List<String> blockers = new ArrayList<>();
        
        if (state != PaymentState.PENDING) {
            blockers.add("Payment is not in PENDING state");
        }
        if (sourceAccount.getBalance().compareTo(amount) < 0) {
            blockers.add("Insufficient funds");
        }
        if (sourceAccount.isFrozen()) {
            blockers.add("Source account is frozen");
        }
        if (!targetAccount.isActive()) {
            blockers.add("Target account is inactive");
        }
        
        return blockers;
    }
}

Action Atomicity

Actions should be atomic with the state change. If you change state but an action fails, you have inconsistency. Use transactions, compensation logic, or the Saga pattern for complex multi-step actions. Never leave objects in partially-transitioned states.

Modeling Complex Lifecycles

Not all lifecycles are simple linear progressions. Real-world objects often have: Branching paths : Different sequences depending on conditions Loops : Returning to previous states under certain circumstances Concurrent states : Being in multiple states simultaneously Hierarchical states : States that contain sub-states Let's examine techniques for modeling these complexities:

ComplexDocumentLifecycle.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
/**
 * Complex document lifecycle with branching, loops, and hierarchy.
 * 
 * Lifecycle Diagram:
 * 
 *  ┌──────────┐    save    ┌──────────┐   submit   ┌───────────┐
 *  │  DRAFT   │ ─────────► │  SAVED   │ ─────────► │  REVIEW   │
 *  └──────────┘            └──────────┘            └───────────┘
 *       │                       ▲                    │       │
 *       │ discard               │ revise        approve  reject
 *       ▼                       │                    ▼       │
 *  ┌──────────┐                 │              ┌───────────┐ │
 *  │ DISCARDED│                 └──────────────│ APPROVED  │ │
 *  └──────────┘                                └───────────┘ │
 *                                                    │       │
 *                              publish               │       ▼
 *                                    ┌───────────┐   │  ┌──────────┐
 *                                    │ PUBLISHED │◄──┘  │ REJECTED │
 *                                    └───────────┘      └──────────┘
 *                                          │                  │
 *                                      archive                revise
 *                                          ▼                  │
 *                                    ┌───────────┐            │
 *                                    │ ARCHIVED  │◄───────────┘
 *                                    └───────────┘
 */
public class Document {
    
    public enum State {
        DRAFT,      // Initial state
        SAVED,      // Changes saved, ready for submission
        REVIEW,     // Under editorial review
        APPROVED,   // Approved by reviewer
        REJECTED,   // Rejected by reviewer (can revise or archive)
        PUBLISHED,  // Live and public
        ARCHIVED,   // No longer active
        DISCARDED   // Deleted before saving
    }
    
    private State state = State.DRAFT;
    private List<StateTransition> history = new ArrayList<>();
    
    // Valid transitions mapped explicitly
    private static final Map<State, Set<State>> VALID_TRANSITIONS = Map.of(
        State.DRAFT, Set.of(State.SAVED, State.DISCARDED),
        State.SAVED, Set.of(State.DRAFT, State.REVIEW),        // Can go back to DRAFT
        State.REVIEW, Set.of(State.APPROVED, State.REJECTED),
        State.APPROVED, Set.of(State.PUBLISHED, State.REVIEW), // Can revise approval
        State.REJECTED, Set.of(State.SAVED, State.ARCHIVED),   // Revise or give up
        State.PUBLISHED, Set.of(State.ARCHIVED),
        State.ARCHIVED, Set.of(),                               // Terminal
        State.DISCARDED, Set.of()                               // Terminal
    );
    
    private void transitionTo(State newState, String reason) {
        if (!VALID_TRANSITIONS.get(state).contains(newState)) {
            throw new IllegalStateException(String.format(
                "Cannot transition from %s to %s. Valid targets: %s",
                state, newState, VALID_TRANSITIONS.get(state)
            ));
        }
        
        history.add(new StateTransition(state, newState, Instant.now(), reason));
        state = newState;
    }
    
    // Business methods that trigger transitions
    public void save() { transitionTo(State.SAVED, "Document saved"); }
    public void submit() { transitionTo(State.REVIEW, "Submitted for review"); }
    public void approve() { transitionTo(State.APPROVED, "Approved by reviewer"); }
    public void reject(String reason) { transitionTo(State.REJECTED, reason); }
    public void publish() { transitionTo(State.PUBLISHED, "Published to public"); }
    public void archive() { transitionTo(State.ARCHIVED, "Archived"); }
    public void discard() { transitionTo(State.DISCARDED, "Discarded by user"); }
    public void revise() { transitionTo(State.SAVED, "Returned for revision"); }
    
    // Query lifecycle position
    public boolean isEditable() {
        return state == State.DRAFT || state == State.SAVED;
    }
    
    public boolean isTerminal() {
        return state == State.ARCHIVED || state == State.DISCARDED;
    }
    
    public boolean isPublic() {
        return state == State.PUBLISHED;
    }
    
    // Audit trail
    public List<StateTransition> getHistory() {
        return List.copyOf(history);
    }
}

Visualize Before You Code

Draw the state diagram before implementing. State diagrams expose impossible transitions, missing states, and dead ends that are hard to spot in code. Tools like PlantUML, Mermaid, or even whiteboard sketches make complex lifecycles visible and discussable.

Event Sourcing and Transition History

Sometimes you need more than just the current state—you need the complete history of how the object got there. Event sourcing is a pattern where you store all state transitions (events) rather than just the current state. The current state is derived by replaying all events. This is particularly powerful for: Audit trails : See exactly what happened and when Debugging : Understand how the object reached an unexpected state Temporal queries : "What was the order status on January 15th?" Undo/Redo : Reverse transitions by applying compensating events

EventSourcedOrder.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
public class EventSourcedOrder {
    
    // Events (immutable records of what happened)
    public sealed interface OrderEvent {
        Instant timestamp();
        String actor();  // Who triggered this event
    }
    
    public record OrderCreated(Instant timestamp, String actor, 
                               String orderId, List<OrderItem> items) 
        implements OrderEvent {}
    
    public record OrderConfirmed(Instant timestamp, String actor) 
        implements OrderEvent {}
    
    public record OrderShipped(Instant timestamp, String actor, 
                               String trackingNumber, String carrier) 
        implements OrderEvent {}
    
    public record OrderDelivered(Instant timestamp, String actor, 
                                 String signedBy) 
        implements OrderEvent {}
    
    public record OrderCancelled(Instant timestamp, String actor, 
                                 String reason) 
        implements OrderEvent {}
    
    // The event log: all transitions ever made
    private final List<OrderEvent> events = new ArrayList<>();
    
    // Current state (recomputed from events)
    private String orderId;
    private List<OrderItem> items;
    private OrderStatus status;
    private String trackingNumber;
    private String signedBy;
    
    // Reconstruct state from events
    public static EventSourcedOrder fromEvents(List<OrderEvent> events) {
        EventSourcedOrder order = new EventSourcedOrder();
        for (OrderEvent event : events) {
            order.apply(event);
        }
        return order;
    }
    
    // Apply an event to update state
    private void apply(OrderEvent event) {
        events.add(event);
        
        switch (event) {
            case OrderCreated e -> {
                this.orderId = e.orderId();
                this.items = new ArrayList<>(e.items());
                this.status = OrderStatus.PENDING;
            }
            case OrderConfirmed e -> {
                this.status = OrderStatus.CONFIRMED;
            }
            case OrderShipped e -> {
                this.status = OrderStatus.SHIPPED;
                this.trackingNumber = e.trackingNumber();
            }
            case OrderDelivered e -> {
                this.status = OrderStatus.DELIVERED;
                this.signedBy = e.signedBy();
            }
            case OrderCancelled e -> {
                this.status = OrderStatus.CANCELLED;
            }
        }
    }
    
    // Business methods create and apply events
    public void confirm(String actor) {
        if (status != OrderStatus.PENDING) {
            throw new IllegalStateException("Cannot confirm: not pending");
        }
        apply(new OrderConfirmed(Instant.now(), actor));
    }
    
    public void ship(String actor, String trackingNumber, String carrier) {
        if (status != OrderStatus.CONFIRMED) {
            throw new IllegalStateException("Cannot ship: not confirmed");
        }
        apply(new OrderShipped(Instant.now(), actor, trackingNumber, carrier));
    }
    
    // Time-travel query: what was the status at a given time?
    public OrderStatus getStatusAt(Instant pointInTime) {
        EventSourcedOrder snapshot = new EventSourcedOrder();
        for (OrderEvent event : events) {
            if (event.timestamp().isAfter(pointInTime)) {
                break;  // Stop replaying at the requested time
            }
            snapshot.apply(event);
        }
        return snapshot.status;
    }
    
    // Complete audit trail
    public List<OrderEvent> getAuditTrail() {
        return List.copyOf(events);
    }
}

Event Sourcing Trade-offs

Event sourcing provides powerful capabilities but adds complexity. Event storage grows unboundedly (snapshots help). Replaying many events is slow (indexing helps). Schema evolution is tricky (event versioning helps). Use event sourcing when audit trails, temporal queries, or undo are requirements—not as a default.

Testing State Transitions

State transitions require systematic testing. You need to verify that: Valid transitions work — Given state S₁ and event E, the object reaches state S₂ Invalid transitions are rejected — Given state S₁ and invalid event E', an exception is thrown and state is unchanged Guards are enforced — Transitions only occur when guard conditions are met Actions execute correctly — Side effects happen in the right order and are atomic All paths are covered — Every transition in the state diagram is tested

OrderStateTransitionTest.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
class OrderStateTransitionTest {
    
    // Test valid transitions
    @ParameterizedTest
    @CsvSource({
        "PENDING, CONFIRMED",
        "CONFIRMED, PROCESSING", 
        "PROCESSING, SHIPPED",
        "SHIPPED, DELIVERED"
    })
    void shouldTransitionThroughHappyPath(String from, String to) {
        Order order = createOrderInState(OrderStatus.valueOf(from));
        
        triggerNextTransition(order);
        
        assertEquals(OrderStatus.valueOf(to), order.getStatus());
    }
    
    // Test invalid transitions
    @ParameterizedTest
    @CsvSource({
        "PENDING, ship",
        "PENDING, deliver",
        "SHIPPED, confirm",
        "DELIVERED, ship",
        "CANCELLED, confirm"
    })
    void shouldRejectInvalidTransitions(String state, String action) {
        Order order = createOrderInState(OrderStatus.valueOf(state));
        
        IllegalStateException exception = assertThrows(
            IllegalStateException.class,
            () -> invokeAction(order, action)
        );
        
        assertThat(exception.getMessage())
            .contains("Cannot")
            .contains(state);
        
        // State should be unchanged after failed transition
        assertEquals(OrderStatus.valueOf(state), order.getStatus());
    }
    
    // Test guard conditions
    @Test
    void shouldRejectShipmentWhenInventoryUnavailable() {
        Order order = createOrderInState(OrderStatus.CONFIRMED);
        inventoryService.setAvailable(false);  // Guard will fail
        
        assertThrows(InventoryException.class, () -> order.ship());
        
        assertEquals(OrderStatus.CONFIRMED, order.getStatus());  // Unchanged
    }
    
    // Test transition actions
    @Test
    void shouldSendNotificationOnConfirmation() {
        Order order = createOrderInState(OrderStatus.PENDING);
        
        order.confirm();
        
        verify(notificationService).sendOrderConfirmation(order);
        verify(auditLog).recordTransition(
            eq(order.getId()),
            eq(OrderStatus.PENDING),
            eq(OrderStatus.CONFIRMED),
            any(Instant.class)
        );
    }
    
    // Test terminal state behavior
    @Test
    void shouldRejectAllOperationsInTerminalState() {
        Order order = createOrderInState(OrderStatus.CANCELLED);
        
        assertThrows(IllegalStateException.class, () -> order.confirm());
        assertThrows(IllegalStateException.class, () -> order.ship());
        assertThrows(IllegalStateException.class, () -> order.cancel());
    }
    
    // Test complete lifecycle (integration test)
    @Test
    void shouldCompleteFullOrderLifecycle() {
        Order order = new Order(customer, items);
        assertEquals(OrderStatus.PENDING, order.getStatus());
        
        order.confirm();
        assertEquals(OrderStatus.CONFIRMED, order.getStatus());
        
        order.startProcessing();
        assertEquals(OrderStatus.PROCESSING, order.getStatus());
        
        order.ship("TRACK123");
        assertEquals(OrderStatus.SHIPPED, order.getStatus());
        assertEquals("TRACK123", order.getTrackingNumber());
        
        order.deliver();
        assertEquals(OrderStatus.DELIVERED, order.getStatus());
        assertTrue(order.isTerminal());
    }
}

State Transition Coverage

For safety-critical systems, use the transition table to generate tests programmatically. If you have N states and M events, you should have N \times M test cases: one for each (state, event) pair, verifying either successful transition or proper rejection. This ensures complete transition coverage.

System Design (LLD)State and Behavior Modeling

State and Behavior Modeling

LevelBeginner

Duration60 mins

TopicState and Behavior Modeling

2 / 4

State Transitions and Lifecycles

Objects in Motion

Objects don't just have state—they change state. An order moves from pending to confirmed to shipped. A user transitions from anonymous to authenticated to logged-out. A document evolves from draft to review to published. These changes aren't random; they follow patterns, rules, and constraints that we call state transitions . Understanding state transitions transforms how you design objects. Instead of thinking about static data structures, you begin to see objects as living entities with histories, futures, and well-defined paths through their existence. This temporal perspective is essential for building robust, predictable systems.

What You Will Learn

By the end of this page, you will understand how to model state transitions explicitly, design object lifecycles with clear phases, enforce valid transition rules, and use state machines to create predictable, self-documenting object behavior.

What Are State Transitions?

A state transition is a change in an object's state from one valid configuration to another. While the previous page discussed state as a snapshot, transitions are the edges that connect one snapshot to the next. Formally, a state transition can be described as: Initial State (S₁) : The object's state before the transition Trigger/Event : What causes the transition (method call, external event, time passage) Guard Condition : Optional conditions that must be true for the transition to occur Action : Operations performed during the transition Final State (S₂) : The object's state after the transition

OrderTransition.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
public class Order {
    private OrderStatus status;
    private LocalDateTime statusChangedAt;
    
    public enum OrderStatus {
        PENDING, CONFIRMED, PROCESSING, SHIPPED, DELIVERED, CANCELLED
    }
    
    /**
     * State Transition: PENDING → CONFIRMED
     * 
     * Trigger: confirm() method call
     * Guard: status must be PENDING
     * Action: update status, record timestamp
     * Result: status becomes CONFIRMED
     */
    public void confirm() {
        // Guard condition: only PENDING orders can be confirmed
        if (status != OrderStatus.PENDING) {
            throw new IllegalStateException(
                "Cannot confirm order in " + status + " state. " +
                "Only PENDING orders can be confirmed."
            );
        }
        
        // Action: perform the transition
        OrderStatus previousStatus = this.status;
        this.status = OrderStatus.CONFIRMED;
        this.statusChangedAt = LocalDateTime.now();
        
        // Transition complete: S₁(PENDING) → S₂(CONFIRMED)
        log.info("Order transitioned: {} → {}", previousStatus, this.status);
    }
    
    /**
     * State Transition: CONFIRMED → PROCESSING
     * Similar pattern with different guard and actions
     */
    public void startProcessing() {
        if (status != OrderStatus.CONFIRMED) {
            throw new IllegalStateException(
                "Cannot start processing order in " + status + " state"
            );
        }
        this.status = OrderStatus.PROCESSING;
        this.statusChangedAt = LocalDateTime.now();
    }
}

Transitions Are Domain Logic

State transition rules encode business logic. "Orders can only be cancelled before shipping" is a business rule expressed as a transition constraint. When you model transitions explicitly, you make business rules visible, testable, and enforceable in code rather than just in documentation.

The Object Lifecycle

Every object has a lifecycle —a pattern of states it moves through from creation to destruction. Understanding lifecycles helps you design objects that behave predictably at every phase of their existence. A typical object lifecycle includes:

Lifecycle Phases

•Creation/Birth — Object is instantiated and enters its initial state. Constructors establish invariants and set up initial attribute values.
•Initialization — Object may need additional setup after construction (dependency injection, configuration loading, resource acquisition).
•Active/Operational — The object's main working phase. Most state transitions occur here as the object performs its purpose.
•Suspended/Paused — Some objects can be temporarily inactive while retaining their state (serialized, pooled, cached).
•Termination/Death — Object reaches a final state and releases resources. Some objects have explicit terminal states; others are simply garbage collected.

Lifecycle Examples Across Different Object Types
Object Type	Creation	Active States	Terminal States
Database Connection	connect()	OPEN, BUSY, IDLE	CLOSED
HTTP Request	new Request()	PENDING, IN_PROGRESS	COMPLETED, FAILED, TIMEOUT
User Session	login()	ACTIVE, IDLE	EXPIRED, LOGGED_OUT
Thread	new Thread()	RUNNABLE, BLOCKED, WAITING	TERMINATED
Order	new Order()	PENDING → ... → SHIPPED	DELIVERED, CANCELLED, REFUNDED

ConnectionLifecycle.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
public class DatabaseConnection {
    
    public enum ConnectionState {
        // Creation phase
        INITIALIZING,
        
        // Active phase  
        OPEN,        // Ready to execute queries
        BUSY,        // Currently executing a query
        
        // Suspended phase
        IDLE,        // Open but unused, may be returned to pool
        
        // Terminal phase
        CLOSED,      // Permanently closed, cannot be reused
        FAILED       // Connection failed, cannot be reused
    }
    
    private ConnectionState state = ConnectionState.INITIALIZING;
    private final String connectionString;
    private Socket socket;
    
    public DatabaseConnection(String connectionString) {
        this.connectionString = connectionString;
        // Object exists but is not yet connected
    }
    
    // Creation → Active transition
    public void connect() throws ConnectionException {
        if (state != ConnectionState.INITIALIZING) {
            throw new IllegalStateException("Can only connect from INITIALIZING state");
        }
        
        try {
            this.socket = establishConnection(connectionString);
            this.state = ConnectionState.OPEN;
        } catch (Exception e) {
            this.state = ConnectionState.FAILED;  // Terminal state on failure
            throw new ConnectionException("Failed to connect", e);
        }
    }
    
    // Active → Active transition
    public ResultSet executeQuery(String sql) {
        if (state != ConnectionState.OPEN && state != ConnectionState.IDLE) {
            throw new IllegalStateException("Cannot execute query in " + state + " state");
        }
        
        this.state = ConnectionState.BUSY;
        try {
            ResultSet result = doExecute(sql);
            this.state = ConnectionState.OPEN;
            return result;
        } catch (Exception e) {
            // Decide: return to OPEN, go to FAILED, or stay BUSY?
            this.state = ConnectionState.OPEN;  // Recoverable error
            throw e;
        }
    }
    
    // Active → Terminal transition
    public void close() {
        if (state == ConnectionState.CLOSED) {
            return;  // Idempotent: already closed
        }
        
        if (socket != null) {
            socket.close();
        }
        this.state = ConnectionState.CLOSED;
        // Object is now in terminal state; no further transitions possible
    }
    
    public boolean isTerminal() {
        return state == ConnectionState.CLOSED || state == ConnectionState.FAILED;
    }
}

Terminal States Are Final

Once an object reaches a terminal state, it should not transition to any other state. A CLOSED connection cannot become OPEN again. Attempting to use an object in a terminal state should throw an exception. Design terminal states explicitly and enforce their finality.

State Machines in Object Design

A Finite State Machine (FSM) is a formal model for objects with discrete states and well-defined transitions. State machines are powerful tools for designing complex objects because they make all possible states and transitions explicit and verifiable. Components of a State Machine: States : A finite set of possible states (enum values, string constants, or state objects) Initial State : The state the machine starts in Terminal States : States from which no further transitions are possible Events/Triggers : Inputs that cause transitions Transition Table : Rules mapping (current state, event) \to (next state, action)

OrderStateMachine.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
public class OrderStateMachine {
    
    public enum State {
        PENDING, CONFIRMED, PROCESSING, SHIPPED, DELIVERED, CANCELLED
    }
    
    public enum Event {
        CONFIRM, START_PROCESSING, SHIP, DELIVER, CANCEL
    }
    
    // Transition table: (current state, event) → next state
    private static final Map<State, Map<Event, State>> TRANSITIONS = Map.of(
        State.PENDING, Map.of(
            Event.CONFIRM, State.CONFIRMED,
            Event.CANCEL, State.CANCELLED
        ),
        State.CONFIRMED, Map.of(
            Event.START_PROCESSING, State.PROCESSING,
            Event.CANCEL, State.CANCELLED
        ),
        State.PROCESSING, Map.of(
            Event.SHIP, State.SHIPPED
            // Note: Cannot cancel once processing starts
        ),
        State.SHIPPED, Map.of(
            Event.DELIVER, State.DELIVERED
        )
        // DELIVERED and CANCELLED are terminal states: no transitions out
    );
    
    private State currentState;
    
    public OrderStateMachine() {
        this.currentState = State.PENDING;  // Initial state
    }
    
    public void fire(Event event) {
        // Look up valid transitions from current state
        Map<Event, State> validTransitions = TRANSITIONS.get(currentState);
        
        if (validTransitions == null || !validTransitions.containsKey(event)) {
            throw new IllegalStateException(String.format(
                "Invalid transition: cannot apply %s in state %s. " +
                "Valid events: %s",
                event, currentState,
                validTransitions != null ? validTransitions.keySet() : "none"
            ));
        }
        
        State previousState = currentState;
        currentState = validTransitions.get(event);
        
        // Notify listeners, execute actions, etc.
        onTransition(previousState, event, currentState);
    }
    
    public boolean canFire(Event event) {
        Map<Event, State> validTransitions = TRANSITIONS.get(currentState);
        return validTransitions != null && validTransitions.containsKey(event);
    }
    
    public Set<Event> getValidEvents() {
        Map<Event, State> validTransitions = TRANSITIONS.get(currentState);
        return validTransitions != null ? validTransitions.keySet() : Set.of();
    }
    
    private void onTransition(State from, Event event, State to) {
        log.info("Order: {} --[{}]--> {}", from, event, to);
    }
}

Benefits of State Machine Design

•Explicit States: All possible states are enumerated. No hidden or unexpected states.
•Valid Transitions Only: Invalid transitions are rejected at runtime with clear error messages.
•Self-Documenting: The transition table IS the documentation. No ambiguity about what's allowed.
•Testable: Each transition can be tested independently. Coverage means all transitions are verified.
•UI Enablement: canFire() and getValidEvents() directly inform UI about available actions.

When to Use State Machines

Use state machines when an object has discrete states with restricted transitions (orders, workflows, connections). Don't use them for objects with continuous or combinatorial state (a Point with x,y coordinates, or a Document with arbitrary text content). State machines shine for lifecycle management.

Transition Guards and Actions

Real-world state transitions are rarely as simple as "go from A to B." They often have conditions that must be met and side effects that must occur. These are modeled as guards and actions . Guards are boolean conditions that must be true for a transition to be allowed, beyond just being in the right state. Actions are operations executed during the transition—before, during, or after the state change.

Guard Examples

•Order can ship only if inventory available
•Payment can complete only if funds sufficient
•File can save only if not read-only
•User can login only if not already locked out
•Timer can start only if not already running

Action Examples

•Send confirmation email on order confirm
•Debit account on payment complete
•Write to disk on file save
•Create audit log on any state change
•Release resources on connection close

GuardsAndActions.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
public class PaymentProcessor {
    
    private PaymentState state = PaymentState.PENDING;
    private final BigDecimal amount;
    private final Account sourceAccount;
    private final Account targetAccount;
    private String transactionId;
    
    /**
     * Transition: PENDING → COMPLETED
     * 
     * Guards:
     *   - Source account has sufficient balance
     *   - Source account is not frozen
     *   - Target account is active
     * 
     * Actions:
     *   - Debit source account
     *   - Credit target account
     *   - Generate transaction ID
     *   - Send notification
     *   - Log audit trail
     */
    public void complete() {
        // Validate current state
        if (state != PaymentState.PENDING) {
            throw new IllegalStateException("Can only complete PENDING payments");
        }
        
        // === GUARD CONDITIONS ===
        if (sourceAccount.getBalance().compareTo(amount) < 0) {
            throw new InsufficientFundsException(
                "Source account balance " + sourceAccount.getBalance() + 
                " is less than payment amount " + amount
            );
        }
        
        if (sourceAccount.isFrozen()) {
            throw new AccountFrozenException("Source account is frozen");
        }
        
        if (!targetAccount.isActive()) {
            throw new InvalidAccountException("Target account is not active");
        }
        
        // All guards passed; execute transition
        
        // === ENTRY ACTIONS (before state change) ===
        this.transactionId = generateTransactionId();
        log.info("Starting payment {}: {} from {} to {}", 
            transactionId, amount, sourceAccount.getId(), targetAccount.getId());
        
        // === TRANSITION ACTIONS (during state change) ===
        try {
            sourceAccount.debit(amount);
            targetAccount.credit(amount);
            
            // === STATE CHANGE ===
            this.state = PaymentState.COMPLETED;
            
        } catch (Exception e) {
            // Transition failed; move to error state
            this.state = PaymentState.FAILED;
            log.error("Payment {} failed: {}", transactionId, e.getMessage());
            throw e;
        }
        
        // === EXIT ACTIONS (after state change) ===
        notificationService.sendPaymentConfirmation(this);
        auditLog.recordPayment(transactionId, sourceAccount, targetAccount, amount);
        
        log.info("Payment {} completed successfully", transactionId);
    }
    
    // Guards can be checked without triggering transition
    public boolean canComplete() {
        return state == PaymentState.PENDING
            && sourceAccount.getBalance().compareTo(amount) >= 0
            && !sourceAccount.isFrozen()
            && targetAccount.isActive();
    }
    
    // Get detailed reasons why completion is blocked
    public List<String> getCompletionBlockers() {
        List<String> blockers = new ArrayList<>();
        
        if (state != PaymentState.PENDING) {
            blockers.add("Payment is not in PENDING state");
        }
        if (sourceAccount.getBalance().compareTo(amount) < 0) {
            blockers.add("Insufficient funds");
        }
        if (sourceAccount.isFrozen()) {
            blockers.add("Source account is frozen");
        }
        if (!targetAccount.isActive()) {
            blockers.add("Target account is inactive");
        }
        
        return blockers;
    }
}

Action Atomicity

Actions should be atomic with the state change. If you change state but an action fails, you have inconsistency. Use transactions, compensation logic, or the Saga pattern for complex multi-step actions. Never leave objects in partially-transitioned states.

Modeling Complex Lifecycles

Not all lifecycles are simple linear progressions. Real-world objects often have: Branching paths : Different sequences depending on conditions Loops : Returning to previous states under certain circumstances Concurrent states : Being in multiple states simultaneously Hierarchical states : States that contain sub-states Let's examine techniques for modeling these complexities:

ComplexDocumentLifecycle.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
/**
 * Complex document lifecycle with branching, loops, and hierarchy.
 * 
 * Lifecycle Diagram:
 * 
 *  ┌──────────┐    save    ┌──────────┐   submit   ┌───────────┐
 *  │  DRAFT   │ ─────────► │  SAVED   │ ─────────► │  REVIEW   │
 *  └──────────┘            └──────────┘            └───────────┘
 *       │                       ▲                    │       │
 *       │ discard               │ revise        approve  reject
 *       ▼                       │                    ▼       │
 *  ┌──────────┐                 │              ┌───────────┐ │
 *  │ DISCARDED│                 └──────────────│ APPROVED  │ │
 *  └──────────┘                                └───────────┘ │
 *                                                    │       │
 *                              publish               │       ▼
 *                                    ┌───────────┐   │  ┌──────────┐
 *                                    │ PUBLISHED │◄──┘  │ REJECTED │
 *                                    └───────────┘      └──────────┘
 *                                          │                  │
 *                                      archive                revise
 *                                          ▼                  │
 *                                    ┌───────────┐            │
 *                                    │ ARCHIVED  │◄───────────┘
 *                                    └───────────┘
 */
public class Document {
    
    public enum State {
        DRAFT,      // Initial state
        SAVED,      // Changes saved, ready for submission
        REVIEW,     // Under editorial review
        APPROVED,   // Approved by reviewer
        REJECTED,   // Rejected by reviewer (can revise or archive)
        PUBLISHED,  // Live and public
        ARCHIVED,   // No longer active
        DISCARDED   // Deleted before saving
    }
    
    private State state = State.DRAFT;
    private List<StateTransition> history = new ArrayList<>();
    
    // Valid transitions mapped explicitly
    private static final Map<State, Set<State>> VALID_TRANSITIONS = Map.of(
        State.DRAFT, Set.of(State.SAVED, State.DISCARDED),
        State.SAVED, Set.of(State.DRAFT, State.REVIEW),        // Can go back to DRAFT
        State.REVIEW, Set.of(State.APPROVED, State.REJECTED),
        State.APPROVED, Set.of(State.PUBLISHED, State.REVIEW), // Can revise approval
        State.REJECTED, Set.of(State.SAVED, State.ARCHIVED),   // Revise or give up
        State.PUBLISHED, Set.of(State.ARCHIVED),
        State.ARCHIVED, Set.of(),                               // Terminal
        State.DISCARDED, Set.of()                               // Terminal
    );
    
    private void transitionTo(State newState, String reason) {
        if (!VALID_TRANSITIONS.get(state).contains(newState)) {
            throw new IllegalStateException(String.format(
                "Cannot transition from %s to %s. Valid targets: %s",
                state, newState, VALID_TRANSITIONS.get(state)
            ));
        }
        
        history.add(new StateTransition(state, newState, Instant.now(), reason));
        state = newState;
    }
    
    // Business methods that trigger transitions
    public void save() { transitionTo(State.SAVED, "Document saved"); }
    public void submit() { transitionTo(State.REVIEW, "Submitted for review"); }
    public void approve() { transitionTo(State.APPROVED, "Approved by reviewer"); }
    public void reject(String reason) { transitionTo(State.REJECTED, reason); }
    public void publish() { transitionTo(State.PUBLISHED, "Published to public"); }
    public void archive() { transitionTo(State.ARCHIVED, "Archived"); }
    public void discard() { transitionTo(State.DISCARDED, "Discarded by user"); }
    public void revise() { transitionTo(State.SAVED, "Returned for revision"); }
    
    // Query lifecycle position
    public boolean isEditable() {
        return state == State.DRAFT || state == State.SAVED;
    }
    
    public boolean isTerminal() {
        return state == State.ARCHIVED || state == State.DISCARDED;
    }
    
    public boolean isPublic() {
        return state == State.PUBLISHED;
    }
    
    // Audit trail
    public List<StateTransition> getHistory() {
        return List.copyOf(history);
    }
}

Visualize Before You Code

Draw the state diagram before implementing. State diagrams expose impossible transitions, missing states, and dead ends that are hard to spot in code. Tools like PlantUML, Mermaid, or even whiteboard sketches make complex lifecycles visible and discussable.

Event Sourcing and Transition History

Sometimes you need more than just the current state—you need the complete history of how the object got there. Event sourcing is a pattern where you store all state transitions (events) rather than just the current state. The current state is derived by replaying all events. This is particularly powerful for: Audit trails : See exactly what happened and when Debugging : Understand how the object reached an unexpected state Temporal queries : "What was the order status on January 15th?" Undo/Redo : Reverse transitions by applying compensating events

EventSourcedOrder.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
public class EventSourcedOrder {
    
    // Events (immutable records of what happened)
    public sealed interface OrderEvent {
        Instant timestamp();
        String actor();  // Who triggered this event
    }
    
    public record OrderCreated(Instant timestamp, String actor, 
                               String orderId, List<OrderItem> items) 
        implements OrderEvent {}
    
    public record OrderConfirmed(Instant timestamp, String actor) 
        implements OrderEvent {}
    
    public record OrderShipped(Instant timestamp, String actor, 
                               String trackingNumber, String carrier) 
        implements OrderEvent {}
    
    public record OrderDelivered(Instant timestamp, String actor, 
                                 String signedBy) 
        implements OrderEvent {}
    
    public record OrderCancelled(Instant timestamp, String actor, 
                                 String reason) 
        implements OrderEvent {}
    
    // The event log: all transitions ever made
    private final List<OrderEvent> events = new ArrayList<>();
    
    // Current state (recomputed from events)
    private String orderId;
    private List<OrderItem> items;
    private OrderStatus status;
    private String trackingNumber;
    private String signedBy;
    
    // Reconstruct state from events
    public static EventSourcedOrder fromEvents(List<OrderEvent> events) {
        EventSourcedOrder order = new EventSourcedOrder();
        for (OrderEvent event : events) {
            order.apply(event);
        }
        return order;
    }
    
    // Apply an event to update state
    private void apply(OrderEvent event) {
        events.add(event);
        
        switch (event) {
            case OrderCreated e -> {
                this.orderId = e.orderId();
                this.items = new ArrayList<>(e.items());
                this.status = OrderStatus.PENDING;
            }
            case OrderConfirmed e -> {
                this.status = OrderStatus.CONFIRMED;
            }
            case OrderShipped e -> {
                this.status = OrderStatus.SHIPPED;
                this.trackingNumber = e.trackingNumber();
            }
            case OrderDelivered e -> {
                this.status = OrderStatus.DELIVERED;
                this.signedBy = e.signedBy();
            }
            case OrderCancelled e -> {
                this.status = OrderStatus.CANCELLED;
            }
        }
    }
    
    // Business methods create and apply events
    public void confirm(String actor) {
        if (status != OrderStatus.PENDING) {
            throw new IllegalStateException("Cannot confirm: not pending");
        }
        apply(new OrderConfirmed(Instant.now(), actor));
    }
    
    public void ship(String actor, String trackingNumber, String carrier) {
        if (status != OrderStatus.CONFIRMED) {
            throw new IllegalStateException("Cannot ship: not confirmed");
        }
        apply(new OrderShipped(Instant.now(), actor, trackingNumber, carrier));
    }
    
    // Time-travel query: what was the status at a given time?
    public OrderStatus getStatusAt(Instant pointInTime) {
        EventSourcedOrder snapshot = new EventSourcedOrder();
        for (OrderEvent event : events) {
            if (event.timestamp().isAfter(pointInTime)) {
                break;  // Stop replaying at the requested time
            }
            snapshot.apply(event);
        }
        return snapshot.status;
    }
    
    // Complete audit trail
    public List<OrderEvent> getAuditTrail() {
        return List.copyOf(events);
    }
}

Event Sourcing Trade-offs

Event sourcing provides powerful capabilities but adds complexity. Event storage grows unboundedly (snapshots help). Replaying many events is slow (indexing helps). Schema evolution is tricky (event versioning helps). Use event sourcing when audit trails, temporal queries, or undo are requirements—not as a default.

Testing State Transitions

State transitions require systematic testing. You need to verify that: Valid transitions work — Given state S₁ and event E, the object reaches state S₂ Invalid transitions are rejected — Given state S₁ and invalid event E', an exception is thrown and state is unchanged Guards are enforced — Transitions only occur when guard conditions are met Actions execute correctly — Side effects happen in the right order and are atomic All paths are covered — Every transition in the state diagram is tested

OrderStateTransitionTest.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
class OrderStateTransitionTest {
    
    // Test valid transitions
    @ParameterizedTest
    @CsvSource({
        "PENDING, CONFIRMED",
        "CONFIRMED, PROCESSING", 
        "PROCESSING, SHIPPED",
        "SHIPPED, DELIVERED"
    })
    void shouldTransitionThroughHappyPath(String from, String to) {
        Order order = createOrderInState(OrderStatus.valueOf(from));
        
        triggerNextTransition(order);
        
        assertEquals(OrderStatus.valueOf(to), order.getStatus());
    }
    
    // Test invalid transitions
    @ParameterizedTest
    @CsvSource({
        "PENDING, ship",
        "PENDING, deliver",
        "SHIPPED, confirm",
        "DELIVERED, ship",
        "CANCELLED, confirm"
    })
    void shouldRejectInvalidTransitions(String state, String action) {
        Order order = createOrderInState(OrderStatus.valueOf(state));
        
        IllegalStateException exception = assertThrows(
            IllegalStateException.class,
            () -> invokeAction(order, action)
        );
        
        assertThat(exception.getMessage())
            .contains("Cannot")
            .contains(state);
        
        // State should be unchanged after failed transition
        assertEquals(OrderStatus.valueOf(state), order.getStatus());
    }
    
    // Test guard conditions
    @Test
    void shouldRejectShipmentWhenInventoryUnavailable() {
        Order order = createOrderInState(OrderStatus.CONFIRMED);
        inventoryService.setAvailable(false);  // Guard will fail
        
        assertThrows(InventoryException.class, () -> order.ship());
        
        assertEquals(OrderStatus.CONFIRMED, order.getStatus());  // Unchanged
    }
    
    // Test transition actions
    @Test
    void shouldSendNotificationOnConfirmation() {
        Order order = createOrderInState(OrderStatus.PENDING);
        
        order.confirm();
        
        verify(notificationService).sendOrderConfirmation(order);
        verify(auditLog).recordTransition(
            eq(order.getId()),
            eq(OrderStatus.PENDING),
            eq(OrderStatus.CONFIRMED),
            any(Instant.class)
        );
    }
    
    // Test terminal state behavior
    @Test
    void shouldRejectAllOperationsInTerminalState() {
        Order order = createOrderInState(OrderStatus.CANCELLED);
        
        assertThrows(IllegalStateException.class, () -> order.confirm());
        assertThrows(IllegalStateException.class, () -> order.ship());
        assertThrows(IllegalStateException.class, () -> order.cancel());
    }
    
    // Test complete lifecycle (integration test)
    @Test
    void shouldCompleteFullOrderLifecycle() {
        Order order = new Order(customer, items);
        assertEquals(OrderStatus.PENDING, order.getStatus());
        
        order.confirm();
        assertEquals(OrderStatus.CONFIRMED, order.getStatus());
        
        order.startProcessing();
        assertEquals(OrderStatus.PROCESSING, order.getStatus());
        
        order.ship("TRACK123");
        assertEquals(OrderStatus.SHIPPED, order.getStatus());
        assertEquals("TRACK123", order.getTrackingNumber());
        
        order.deliver();
        assertEquals(OrderStatus.DELIVERED, order.getStatus());
        assertTrue(order.isTerminal());
    }
}

State Transition Coverage

For safety-critical systems, use the transition table to generate tests programmatically. If you have N states and M events, you should have N \times M test cases: one for each (state, event) pair, verifying either successful transition or proper rejection. This ensures complete transition coverage.

State Transitions and Lifecycles

Objects in Motion

What Are State Transitions?

The Object Lifecycle

State Machines in Object Design

Transition Guards and Actions

Modeling Complex Lifecycles

Event Sourcing and Transition History

Testing State Transitions

There’s more to understand.

State Transitions and Lifecycles

Objects in Motion

What Are State Transitions?

The Object Lifecycle

State Machines in Object Design

Transition Guards and Actions

Modeling Complex Lifecycles

Event Sourcing and Transition History

Testing State Transitions

There’s more to understand.