State and Behavior Modeling

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();
    }
}

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;
    }
}

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);
    }
}

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;
    }
}

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);
    }
}

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);
    }
}

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());
    }
}