Sequence Diagrams — Behavior Over Time

Lifelines establish who participates in an interaction. But participants don't accomplish anything in isolation—they collaborate by exchanging messages. In sequence diagrams, messages are the arrows that connect lifelines, representing the flow of control, information, and responsibility between objects.

Understanding messages is essential because they encode the actual behavior of your system. Each message represents a method call, a signal, or a response. Together, they tell the complete story of how a feature is implemented through object collaboration.

In sequence diagrams, a message represents a communication between two participants. It typically corresponds to:

• A method call — One object invoking a method on another
• A return value — The result sent back from a method call
• A signal — An asynchronous notification or event
• Object creation — Instantiating a new object
• Object destruction — Terminating an object's lifecycle

Visual Representation:

Messages are drawn as horizontal arrows between lifelines. The arrow points from the sender (caller) to the receiver (callee). The message name (usually a method name) labels the arrow.

Key Properties of Messages:

1. Direction — The arrow shows who initiates (sender) and who responds (receiver)
2. Name — The label identifies the method or signal being invoked
3. Timing — Vertical position indicates temporal order (earlier messages are higher)
4. Type — Different arrow styles denote different message types (synchronous, asynchronous, return)

The most common message type is the synchronous message, represented by a solid arrow with a filled arrowhead. A synchronous message indicates that the sender:

1. Invokes a method on the receiver
2. Waits for the receiver to complete execution
3. Receives a response (return value) before continuing

This is the standard method call in most programming languages. When you write result = objectB.processOrder(data), you're making a synchronous call—your code pauses until processOrder() finishes and returns.

Reading the Diagram:

1. Controller synchronously calls calculateTotal(items) on Service
2. Service activates and synchronously calls findPrices(itemIds) on Repository
3. Repository activates, processes, then returns prices[] to Service
4. Service processes the prices and returns totalAmount to Controller

Notice how the caller (Controller) must wait through the entire chain. Only after Service returns does Controller continue execution.

Synchronous Call Characteristics:

A return message represents the response flowing back from a method call. It uses a dashed arrow with an open arrowhead, pointing from the callee back to the caller.

Visual Distinction:

When to Show Returns:

Return messages are optional in sequence diagrams. Two conventions exist:

Return Message Labels:

Return arrows are typically labeled with:

• The return value or its type: prices[], totalAmount, true
• A description: order created, validation passed
• The assigned variable from the caller's perspective: result = ...

Best Practice: Be consistent within a diagram. If you show some returns, show all meaningful ones. If you omit returns, do so throughout (except for critical decision points).

Message labels can include varying levels of detail, from simple method names to complete signatures with parameters and return types.

Levels of Detail:

Parameter Passing:

When parameters are shown, they represent the data flowing from caller to callee:

controller -> service: calculateShipping(order, destination)

This tells us that the calculateShipping method receives two arguments: the order being shipped and the destination address. The reader understands what information is available inside the called method.

Showing Actual Values:

For scenario-specific diagrams (showing a particular use case execution), you might show actual values:

controller -> service: calculateShipping(order#1234, "New York")

This is useful for illustrating specific test cases or debugging scenarios.

A self-message (or self-call) occurs when an object invokes a method on itself. This is drawn as an arrow that loops back to the same lifeline.

Visual Representation:

The arrow starts from the activation bar, curves out, and returns to the same lifeline, typically creating a nested activation bar.

When Self-Calls Occur:

1. Internal Method Decomposition — A public method delegates to private helper methods:

   • process() calls this.validate() then this.execute()

2. Recursive Algorithms — A method calls itself with different parameters:

   • sort(list) calls sort(leftHalf) and sort(rightHalf)

3. Template Method Pattern — A base method defines structure, calling overridable steps:

   • handleRequest() calls this.preProcess(), this.doHandle(), this.postProcess()

4. State Transitions — An object triggers its own state changes:

   • processEvent() calls this.transitionTo(newState)

Nested Activation Bars:

When an active object calls itself, a new, narrower activation bar is stacked on top of the existing one. This visualizes the growing call stack:

|████|     ← Outer activation (handleRequest)
|██████|   ← Inner activation (self-call to validate)
|████|     ← Back to outer after validate returns

Each nested bar represents a deeper level in the call stack within the same object.

Sequence diagrams derive their power from the vertical axis, which represents time. This temporal dimension establishes causality and ordering between messages.

The Vertical Time Axis:

• Higher position = earlier in time
• Lower position = later in time
• Messages at the same vertical level happen "around the same time" (or their relative order is unspecified)

Causality and Ordering:

The vertical ordering establishes causal relationships:

1. A message cannot be received before it is sent
2. A return cannot occur before the corresponding call
3. An object cannot send a message before it's created

Reading Temporal Flow:

In the diagram above:

1. first() happens before second() (causally—B can't call C until A calls B)
2. second() completes (result2) before first() completes (result1)
3. third() happens after first() returns (A waits for result1 before calling C)

Horizontal Distance Is Not Time:

A common misconception: the horizontal distance between messages has no meaning. Two arrows at different horizontal positions but the same vertical level represent events at the same logical time (or unordered events).

Let's consolidate all the message types we've discussed, plus a preview of asynchronous messages (covered in the next page):

Distinguishing Arrow Heads:

• Filled arrowhead (▶) = Synchronous, blocking call
• Open arrowhead (>) = Asynchronous or return
• Dashed line = Return message or optional/conditional message

Note: Different UML tools may vary slightly in their notation. The key is to be consistent within your diagrams and establish conventions with your team.

Let's apply message concepts to model a user authentication flow. This example demonstrates synchronous calls, returns, and the message signatures that communicate essential information.

The Scenario:

A user submits login credentials. The system validates the credentials, checks account status, generates a session token, and returns the result.

Message Analysis:

Design Insights from the Diagram:

1. Separation of Concerns: Controller orchestrates; AuthService handles logic; Repository handles persistence; TokenService handles token generation
2. Single Responsibility: Each participant has a focused role
3. Self-Calls Reveal Internal Logic: Password verification and status checks are internal to AuthService
4. Return Values Drive Flow: The presence/absence of user, validity of password, and token generation all influence the outcome

We've explored how objects communicate through messages—the arrows that bring sequence diagrams to life. Here's what we've covered:

What's Next:

Synchronous calls are just one communication style. Modern systems increasingly rely on asynchronous communication—messages that don't block the sender. The next page explores asynchronous calls, their notation, and when each style is appropriate.