Chapter 5: System Sequence Diagrams and Operation Contracts
Source files used: Lecture 5 - Sequence diagrams, Operation contracts; textbook (applying-uml-and-patterns.pdf) Chapters 9 and 13 as support.
A focused guide to system sequence diagrams (SSDs) and operation contracts for the COMP302 Midterm 1. It covers what an SSD shows, how to draw one from a use case, how to name system events, and how to write contracts with correct postconditions. This is the last analysis step: SSDs come from the use cases of Guide 3, and contracts describe changes to the domain model of Guide 4.
Roadmap: 1 OOA/D and UP → 2 Inception and Requirements → 3 Use Cases → 4 Domain Models → 5 SSDs and Contracts → 6 Logical Architecture → 7 Interaction Diagrams
System Sequence Diagrams
What Is an SSD?
A system sequence diagram shows, for one particular scenario of a use case, the external actors that interact directly with the system, the system as a black box, and the system events that the actors generate. Time proceeds downward, and the order of events follows their order in the scenario.
- SSDs are simple diagrams of the input and output events of the system.
- They are one particular use of UML sequence diagrams. Later (Guide 7), sequence diagrams are used to design interacting software objects.
- They serve as input to operation contracts and to object design.
Guideline: Draw an SSD for the main success scenario of each use case, and for frequent or complex alternative scenarios.
Notation by Example: NextGen Process Sale
Legend for the SSDs in this guide: : is a lifeline, ---> is a message (solid line, filled arrowhead), and <- - - is a return (dashed line).
Process Sale Scenario
:Cashier :System
: :
: makeNewSale() :
:----------------------------------------->:
+------:------------------------------------------:---+
| loop [more items] : |
| : enterItem(itemID, quantity) : |
| :----------------------------------------->: |
| : description, total : |
| :<- - - - - - - - - - - - - - - - - - - - -: |
+------:------------------------------------------:---+
: endSale() :
:----------------------------------------->:
: total with taxes :
:<- - - - - - - - - - - - - - - - - - - - -:
: makePayment(amount) :
:----------------------------------------->:
: change due, receipt :
:<- - - - - - - - - - - - - - - - - - - - -:What each element means:
:Cashieris the external actor;:Systemis the whole system as one black box (the name could be NextGenPOS, but “System” keeps it simple).- Messages with parameters, such as
makePayment(amount), are abstractions of system events (entering payment data by some mechanism). - Return values are an abstraction that ignores presentation and medium. The return line is optional if nothing is returned.
- The loop frame with a boolean guard,
[more items], shows repetition.
The lecture’s Monopoly SSD is even smaller:
:Observer :System
: initialize(numOfPlayers) :
:------------------------------------->:
: playGame :
:------------------------------------->:
+------:--------------------------------------:---+
| loop [no winner] : |
| : dice total, player, square : |
| :<- - - - - - - - - - - - - - - - - - -: |
+------:--------------------------------------:---+Exam Trap #1: Drawing software objects inside an SSD.
WRONG: :Cashier --> :Register --> :Sale --> :ProductCatalog
CORRECT: :Cashier --> :System (one black box; internal objects come in Guide 7)Why Draw an SSD?
A software system reacts to three things: external events from actors (humans or computers), timer events, and faults or exceptions (often from external sources). The software must be designed to handle the incoming events and execute a response, so we need to know exactly which events come in.
“Isn’t this already in the use case?” Not explicitly: the SSD makes the input and output events and their arguments concrete. Put detailed explanations of event names and arguments in the Glossary.
SSDs Come From Use Cases
An SSD shows the system events for one scenario of a use case, so it is generated by inspecting that use case. In Process Sale, step 2 “Cashier starts a new sale” becomes makeNewSale(), steps 3-4 become the loop with enterItem(itemID, quantity), “until indicates done” becomes endSale(), and step 7 becomes makePayment(amount).
A system event is an external event that directly stimulates the software (textbook). The boundary decides who generates events: in the cash-only scenario the customer talks only to the cashier, so the customer is not a generator of system events; only the cashier is.
Naming System Events
Which is better, scan(itemID) or enterItem(itemID)?
- Express system events at the abstract level of intention, not in terms of the physical input device.
enterItemcaptures the intent while staying noncommittal about the interface;scanassumes a laser scanner. - Start the name with a verb (add…, enter…, end…, make…).
- SSD elements are terse; explain names, parameters, and return data in the Glossary.
Exam Trap #2: Device-level or widget-level event names.
WRONG: scan(itemID), clickPayButton(), swipeCard()
CORRECT: enterItem(itemID, quantity), endSale(), makePayment(amount)Operation Contracts
What Is a Contract?
Use cases are the main way the UP describes behavior, and they are usually sufficient. When more precision is valuable, an operation contract uses a pre- and post-condition form to describe detailed changes to objects in the domain model as the result of a system operation.
Key Insight: A use case has pre- and postconditions for the entire use case. A contract has them per system event (per system operation).
What Is a System Operation?
- System operations are the operations the system offers in its public interface.
- They are identified while sketching SSDs: each input system event implies a system operation that handles it, just as an OO message is handled by an OO method.
- The entire set of system operations across all use cases defines the public system interface, viewing the system as a single component or class.
Sections of a Contract
| Section | Content |
|---|---|
| Operation | name of the operation and its parameters |
| Cross References | use cases this operation can occur within |
| Preconditions | noteworthy assumptions about the state of the system or of objects in the domain model before the operation |
| Postconditions | the most important section: the state of objects in the domain model after the operation completes |
Postconditions: Three Kinds of State Change
Postconditions describe changes in the state of domain model objects. There are exactly three categories:
- instances created (and, rarely, deleted),
- associations formed (or broken),
- attributes changed (attribute modification).
Postconditions are not actions performed during the operation. They are observations about domain model objects that are true when the operation has finished. The textbook’s image: photograph the stage, close the curtain, run the operation, open the curtain, photograph again, and describe the difference.
Exam Trap #3: Writing postconditions as commands.
WRONG: Create a SalesLineItem.
CORRECT: A SalesLineItem was created. (declarative, passive past tense)Exam Trap #4: Creating an instance but forgetting to connect it.
WRONG: - A SalesLineItem instance sli was created.
CORRECT: - A SalesLineItem instance sli was created (instance creation).
- sli was associated with the current Sale (association formed).A new instance is almost never useful on its own; state which associations it joined.
How to Create and Write Contracts
- Identify the system operations from the SSDs.
- Write a contract for the system operations that are complex and subtle in their results, or that are not clear in the use case.
- Describe the postconditions using the three categories: instance creation and deletion, attribute modification, associations formed and broken.
The textbook adds that writing contracts often reveals new conceptual classes, attributes, or associations, so update the domain model as you go (Sale’s isComplete attribute below is an example).
The NextGen Contracts
Contract CO1: makeNewSale
Operation: makeNewSale()
Cross References: Use Cases: Process Sale
Preconditions: none
Postconditions: - A Sale instance s was created (instance creation).
- s was associated with a Register (association formed).
- Attributes of s were initialized.
Contract CO2: enterItem
Operation: enterItem(itemID: ItemID, quantity: integer)
Cross References: Use Cases: Process Sale
Preconditions: There is a sale underway.
Postconditions: - A SalesLineItem instance sli was created (instance creation).
- sli was associated with the current Sale (association formed).
- sli.quantity became quantity (attribute modification).
- sli was associated with a ProductDescription, based on
itemID match (association formed).
Contract CO3: endSale
Operation: endSale()
Cross References: Use Cases: Process Sale
Preconditions: There is a sale underway.
Postconditions: - Sale.isComplete became true (attribute modification).
Contract CO4: makePayment
Operation: makePayment(amount: Money)
Cross References: Use Cases: Process Sale
Preconditions: There is a sale underway.
Postconditions: - A Payment instance p was created (instance creation).
- p.amountTendered became amount (attribute modification).
- p was associated with the current Sale (association formed).
- The current Sale was associated with the Store (association
formed), to add it to the historical log of completed sales.Exam Trap #5: Mentioning software or UI in postconditions (“the sale was saved to the database”, “the screen shows the total”). Postconditions talk only about domain model objects: instances, associations, attributes.
How the Pieces Connect
Use Case → SSD → Contract → Design
use case text --(system events)------------> SSD
SSD --(system operations)--------> operation contracts
domain model --(objects that change)------> contract postconditions
SSD + contract --(starting events, details)-> design model (Guide 7)Guide 6 shows that the SSD messages are exactly the calls the UI layer forwards to the domain layer.
Exam-Style Practice Problems
Problem 1: SSD for Chess
Question: The Fall 2024 Midterm 1 study sheet: for the single-player computer chess game (start a new game; you and the computer keep making moves; the game ends at checkmate), draw an SSD for the main scenario of “Play Game”. Think about the actors, the system, and the messages that cross the system boundary.
Answer:
:Player :System
: startNewGame() :
:----------------------------------------->:
: board :
:<- - - - - - - - - - - - - - - - - - - - -:
+------:------------------------------------------:---+
| loop [no checkmate] : |
| : playerMakeMove(from, to) : |
| :----------------------------------------->: |
| : computer's move, board : |
| :<- - - - - - - - - - - - - - - - - - - - -: |
+------:------------------------------------------:---+
: result (winner) :
:<- - - - - - - - - - - - - - - - - - - - -:The computer opponent is inside the system, so it is not drawn as an actor.
Problem 2: Contract for playerMakeMove
Question: Write an operation contract for the imaginary system operation playerMakeMove (same study sheet).
Answer: assuming domain classes Game, Move, Piece, and Square:
Contract: playerMakeMove
Operation: playerMakeMove(from: Square, to: Square)
Cross References: Use Cases: Play Game
Preconditions: A game is underway and it is the player's turn.
Postconditions: - A Move instance m was created (instance creation).
- m was associated with the current Game (association formed).
- The moved Piece's association with the from Square was
broken, and an association with the to Square was formed.
- If an opponent's Piece was on the to Square, its
association with that Square was broken (capture).
- Game.isCheckmate became true if the move gives checkmate
(attribute modification).Problem 3: Short Answers
Question: (a) What are the three types of state change that a postcondition can guarantee? (b) Explain “system event” and “pre-condition (in the context of an operation contract)”.
Answer:
- (a) Instance creation (or deletion), association formed (or broken), attribute modification.
- (b) A system event is an external input event that an actor generates to the system (shown on an SSD), and it invokes a system operation. A precondition is a noteworthy assumption about the state of the system or domain model objects before the system operation runs.
Common Exam Traps
1. SSDs Treat the System as a Black Box
WRONG: lifelines for :Register, :Sale, :Payment
CORRECT: one :System lifeline, plus the external actorsWhy: Internal objects are a design decision, made later.
2. One Scenario per SSD
WRONG: one SSD crammed with every extension of the use case
CORRECT: one SSD for the main success scenario (plus SSDs for frequent
or complex alternatives)Why: An SSD shows the events of one particular scenario.
3. Intent-Level Event Names
WRONG: scan(itemID)
CORRECT: enterItem(itemID, quantity)Why: Name the intention, not the input device; start with a verb.
4. Actors That Do Not Touch the System
WRONG: :Customer sending makePayment() in the cash-only Process Sale
CORRECT: only :Cashier generates system events in that scenarioWhy: System events come from actors that directly stimulate the software.
5. Postconditions Are Past-Tense Observations
WRONG: Create a Payment. Associate it with the Sale.
CORRECT: A Payment p was created. p was associated with the current Sale.Why: They describe the state after the operation, not how to get there.
6. Forgetting Associations and Attributes
WRONG: only "a SalesLineItem was created"
CORRECT: created + associated with Sale + quantity set
+ associated with a ProductDescriptionWhy: Check all three categories for every contract.
7. Contract Scope vs Use Case Scope
WRONG: contract preconditions for the whole Process Sale use case
CORRECT: contract pre/postconditions for one system operation, such as enterItemWhy: Use cases have conditions for the whole use case; contracts have them per system event.
8. Postconditions Mention Only Domain Objects
WRONG: "The sale was inserted into the SALES table."
CORRECT: "The Sale was associated with the Store."Why: Postconditions are stated in terms of the domain model.
Final Tips for the Midterm
- Draw SSDs from the use case steps: one arrow per actor action that reaches the system; dashed returns only when something comes back.
- Add a loop frame with a guard: whenever the use case says “repeats”.
- Name events with verbs at the level of intent: makeNewSale, enterItem, endSale, makePayment.
- Memorize the four contract sections: Operation, Cross References, Preconditions, Postconditions.
- Recite the three state changes: instance created, association formed, attribute modified (plus their “deleted” and “broken” forms).
- Write postconditions in passive past tense: “was created”, “was associated with”, “became”.
Good luck on the midterm! You’ve got this.