Craig Larman is the author of Applying UML and Patterns— An Introduction to Object-Oriented Analysis and Design, and is Principal Instructor at ObjectSpace. He can be contacted at [email protected].

IN PREVIOUS COLUMNS we've been exploring common, useful object-oriented (OO) analysis and design activities and models, with the ultimate goal of producing a system in Java. In the analysis phase, we are focusing on questions of a "what" nature. Such as, what are the requirements, processes, concepts, information, and events related to this domain? There is not much point in designing a solution until we understand the problem domain and the desires of the stakeholders. That is the point of analysis-an investigation. Once understood, we will move forward and design a solution, focusing on "how" questions.

It is important to appreciate, however, that I am not recommending that this work proceed based on a waterfall process—a single major phase of analysis, followed by design, followed by construction. Rather, I advocate (for most projects of significant size) an iterative-incremental approach to development in which small cycles (say, 4 weeks long) of analysis, design, and construction are repeated for portions of the requirements.

In "Refining skills for expressive conceptual models," Java Report, Vol. 3, No. 12, we refined the conceptual model, which illustrates concepts, things, vocabulary, and information of interest to us. Here, we focus on another analysis model—one that specifies the external events and behavior of our system.

Our ongoing example is a video store software system that will support the use cases and conceptual model discussed earlier. This is the last analysis model we will explore (for now).

Introduction
Models that describe aspects of a domain or system can be characterized as either emphasizing static or dynamic information. For example, the use case model describes processes and activities—hence, it is a dynamic model. On the other hand, the conceptual model focuses on information about objects and their structural relationships—hence, it is a static model. We're going to review another dynamic model—the System Behavior model.
It is useful to understand what the external events are that our system must respond to, and to examine the details regarding what our system is supposed to do in response to those external events. This is useful because we design and program primarily to service these events. They are the driving force that define our software. The results of this investigation are referred to as the System Behavior model.

To illustrate and summarize the external system events, we use UML sequence diagrams. To elaborate the details of what our system does in response to external events we use a document called an operation contract.

Iterative-Incremental Development and Our Exploration
So far, in our exploration of modeling, we have not emphasized the process context, such as an iterative-incremental development process. This will be discussed more thoroughly in a later column. For now, note that we perform analysis and design on only a portion of the requirements. Thus, the system behavior model will only be developed for a simple, typical scenario of the Rent Videos use case, not for all the use cases.

System Sequence Diagrams
The UML includes a sequence diagram notation that can be used to illustrate and summarize external events from actors into our system. Figure 1 shows a system sequence diagram for a series of external events into our system for a typical scenario of the Rent Videos use case. A system sequence diagram is usually helpful for typical scenarios—that is, for common paths through an execution of the use case. It illustrates the external actor—the Clerk in this case—and the order of system events.

The incoming external events are expressed in a kind of function call syntax, with associated data passed as parameters. These events abstract away the design details of the user interface; they should therefore be named to express the essential intent, rather than specific input technology. Thus, recordVideoRental(videoID) is preferable to inputVideoFromLaserReader(videoID). Of course (as of 1998), the interface is most likely a GUI and a laser reader. A system event such as recordVideoRental(videoID) will probably be realized by a laser reader or by the clerk typing the videoID in a widget on the GUI, and then pressing a key on the keyboard or clicking on a button with a mouse.

Figure 1 contains annotation regarding other salient notational aspects of the diagram.

We do not expand the system or show inter-object interactions in this use of the sequence diagrams. The intent is to leave the system as a black box and simply show external input events, without making any decisions about how the system is internally designed to handle the events. Hence, this variation is called a system sequence diagram, to emphasize its use in describing the external interface to the entire system, rather than a possible alternative use as sequence diagrams to show inter-object collaboration during the design phase.

The system sequence diagram is primarily answering this question: What are the external incoming system events?

Inter-System Sequence Diagrams
System sequence diagrams may also be used to illustrate inter-system communication. For example, a credit payment at the video store will require communication with an external credit authorization service computing system. Such inter-system diagrams have been used for many years, especially in the telecommunications field, where they were sometimes referred to as call flow diagrams. Figure 2 illustrates the notation.

Figure 2. Inter-system events.

Introduction to Operation Contracts
The system sequence diagram shows the system events that an external actor generates, but it does not elaborate on the details of the functionality associated with the system operations invoked. It is missing the details necessary to understand the system response—the system behavior.

An operation contract is a text document that describes what an operation commits to achieve. It is usually declarative in style, emphasizing what will happen, rather than how it will be achieved. It is common for operation contracts to be expressed in terms of pre- and postcondition state changes. Contracts may be written for individual methods in software classes, but here we are using this notational device to describe large-scale operations on the entire system.

Pre- and postcondition expressions for operations are a well-established technique in computer science; they are used in some formal program semantics specifications. Bertrand Meyer, the creator of the Eiffel OO language, (and the author of a book on formal program semantics I had to struggle through in grad school!) championed their use in object technology. In both the Booch and (especially) Fusion OO analysis and design methods, contracts are recommended. If you dig into the UML metamodel, you will discover that operations have a set of predefined properties that include pre- and postconditions.

With that bit of history out of the way, let's examine system operation contracts more closely.

Example Operation Contract
Once the external system events have been identified in the system sequence diagrams, then we can write operation contracts for each major system operation.

As used here, an operation contract will describe changes in the state of objects from the conceptual model, when a system operation is invoked. By system operation, we refer to the response to a system event such as startRental( membershipID). Example 1 presents an operation contract for the startRental system operation. Example 2 shows one for recordVideoRental.

Example 2. Operation contact for recordVideoRental.

Name: recordVideoRental (videoID) Preconditions: videoID is known to system. A RentalTransaction has been created. Postconditions: A VideoRental, vr, was created. vr was associated with the current RentalTransaction that is underway at this terminal. vr.dueDate was set to tomorrow. The Video whose ID matches videoID was associated with vr.

The important section to focus on, for now, is Postconditions. It describes changes in the state of objects drawn from the conceptual model shown in Figure 3. For example, the first postcondition states:

• A RentalTransaction txn was created.

RentalTransaction is a concept in the conceptual model. In this business domain, after this operation has completed, a new instance of this type (which will be named txn as a reference in the contract) will exist in the domain. This is an example of an instance creation state change.

The second postcondition states:

• txn.date was set to the current date.

For the transaction that was created, its date was initialized. This is an example of object attribute modification.

The third postcondition states:

• The Membership whose ID matches membershipID was associated with txn.

Figure 3. Sample conceptual model of the video rental domain.

Some kind of a relationship was formed between the transaction and the membership of the renter, because we need to remember for whom the rental transaction was created. This is an example of associations formed.

Elaboration
To reiterate, the postconditions make statements about changes in objects drawn from the conceptual model. In particular, the following kinds of changes may occur:

1. Instances created.
2. Instances destroyed.
3. Attribute modified.
4. Associations formed.
5. Associations broken.

In the approach to using system operation contracts that we suggest, postconditions are limited to these categories of statements.

In addition, notice that the statements are expressed in the past tense:

• A RentalTransaction txn was created.
• txn.date was set to the current date.

Because they are postconditions—conditions that must be true after the operation has completed—they are expressed in the past.

Avoiding Design Creep
Expressing the postconditions in the past tense and limiting them to the five categories of state changes in the conceptual model has the important advantage of avoiding design creep—premature decisions about how these postconditions will be achieved. As analysts, we can make statements about what must be achieved in terms of changes in the domain, in the vocabulary and information of the domain, without worrying about how they will be achieved.

As an example, consider the postcondition:

• The Membership whose ID matches membershipID was associated with txn.

There is no discussion about how the Membership was found or how an association was established. It could range from looking up index cards in a file cabinet and stapling paper together, to using an object database and setting pointer links.

So while creating these contracts we can keep on our business analyst hats and focus on questions of an investigative or "what" nature. Later, it is the responsibility of the software designer (which will probably be us in another role) to decide how to achieve those state changes using object technology. We claim it is not appropriate while designing a solution or (worse) programming the solution, to try to figure out what the software was supposed to achieve—that's the job of analysis.

Preconditions
The Preconditions section should define assumptions about the state of the system at the beginning of the operation. There are many possible preconditions we can declare for an operation, but experience suggests that the following preconditions are worth noting:

• Things that are important to test in software at the beginning of execution of the operation.
• Things that will not be tested, but upon which the success of the operation hinges. We wish to communicate this assumption to future readers of the contract to highlight their importance and to raise their awareness in the mind of the readers.

A contract, like all artifacts, is a document meant for human consumption, to help a software engineer make decisions. So the preconditions should be of practical value that aid in some decision making later on. There is arguably not much value in stating preconditions such as:

• The customer is in the store.
• The video is in the store.

These are correct preconditions but not much help.

The Spirit of Postconditions: The Stage and Curtain
Postconditions should describe the state of a system; they should not be actions to perform. Express postconditions in the past tense to emphasize they are declarations about a past state change. For example:

• (better) A RentalTransaction txn was created. Rather than
• (worse) Create a RentalTransaction.

Think about postconditions using the following image:

1. The system and its objects are presented floating before you on a theater stage.
2. Before the operation, take a picture of the stage.
3. Close the curtains on the stage and apply the system operation (background noise of clanging, screams, and screeches...).
4. Open the curtains and take a second picture.
5. Compare the before and after pictures and express as postconditions the changes in the state of the stage (A RentalTransaction was created...).

More Details in a Contract
The initial examples of contracts emphasized their core features of pre- and postconditions. However, other sections may be optionally useful, depending on the context and project. Example 3 illustrates some other sections that people have found useful. But please remember, it is important to avoid adding information that no one will ever read, use, or make a decision with; stick to essential information in the documentation that will be of practical value farther along the development path.

Example 3. Operation contact with more details.

Name: startRental (membershipID) Responsibilities: Confirm that the membership is valid—that it exists, and that the membership is not suspended, if it is OK, create a new rental transaction. Cross References: Use Case: Renting Videos Fulfilled requirements: R1.2, R1.4 Notes: Arbitrary notes that may relate to the analysis or design. Exceptions: Especially if this is a remote operation invoked from another system, a description of exceptions that may be generated. Output: The membership status is communicated to the operator. Preconditions: System does not have a rental transaction underway at this terminal. Postconditions: If the membership was valid: A RentalTransaction txn was created. txn.date was set to the current date. The Membership whose ID matches membershipID was associated with txn.

I consider the Responsibilities section to be the second most important, after the post-conditions. This section can summarize the responsibilities that must be fulfilled by the operation in an informal easy-to-write style.

Figure 4. Sample artifacts and their influence.

For large projects with significant requirements, it is important to not miss things when there are many details and people to manage. Therefore, the Cross References section can be an aid in traceability. Throughout the last four columns, we have explored use cases, conceptual models, system sequence diagrams, and operation contracts. Figure 4 illustrates some of the influential relationships between these artifacts.

Next Time
In the next installment, we will make a major transition: from analysis to design. We will put on our software engineer hats, and as OO designers, start to consider how to design a solution using the paradigm of collaborating responsible objects. A significant portion of that examination will be an exploration of how to assign responsibilities to classes of objects, and the use of design patterns.