In Chapter 2 we presented formal definitions of the fundamental elements of a use-case model, described the additional artifacts that are required to enable a use-case model to form a complete software requirements specification, and had a brief look at the contents of the use-case descriptions. Before we delve into the mechanics of writing detailed use-case descriptions and completing the use case’s documentation we need to take a closer look at the structure and contents of a use case. [1]
Table 7-1 provides a summary of all of the properties of a use case. We have already discussed the importance and role of the name, brief description, and special requirements properties when we looked at the basic building blocks of the use-case model in Chapter 2, Fundamentals of Use-Case Modeling. We also provided a brief introduction to the flow of events, relationships, preconditions, and postconditions, but there is still a lot more to learn about these particular use-case properties. In this chapter, we will take a closer look at these as well as examine two new properties, extension points and diagrams, introduced for the first time in Table 7-1.
First, we will take a more formal look at the relationship between a system’s use cases and the system’s state. This will complete our understanding of how use cases interact and how preconditions and postconditions are used in practice. Next, we look more closely at the structure of the flow of events, the significance of this structure, and its implications for other software development activities that depend on the use cases. We will also introduce the final set of use-case properties: extension points and diagrams. This will complete our understanding of the nature of the flow of events. Finally, we will take a brief look at scenarios and use-case realizations. These concepts are related to, and often confused with, use cases. Understanding them, and their role in software development, will help us remain focused when use-case modeling. You will have to wait until Chapter 10, Here There Be Dragons, to learn more about use-case relationships.
Table 7-1. The Properties of a Use Case
|
Property Name |
Brief Description |
|---|---|
|
Name |
The name of the use case. Each use case should have a name that indicates what is achieved by its interaction with the actor(s). The name may have to be several words long to be understood. No two use cases should have the same name. |
|
Brief description |
A brief description of the role and purpose of the use case. |
|
Flow of events |
A textual description of what the system does in regard to the use case (not how specific problems are solved by the system). The description is understandable by the stakeholders. The flow of events is structured into a basic flow, alternative flows, and subflows. |
|
Special requirements |
A textual description that collects all requirements, such as nonfunctional requirements, on the use case that are not considered in the flow of events, but that need to be taken care of during design or implementation. |
|
Preconditions |
A textual description that defines a constraint on the system when the use case may start. |
|
Postconditions |
A textual description that defines a constraint on the system when the use cases have terminated. |
|
Extension points |
A list of locations within the flow of events of the use case at which additional behavior can be inserted. |
|
Relationships |
The relationships, such as communication relationships, in which the use case participates. |
|
Diagrams |
Diagrams that illustrate aspects of the use case, such as the structure of the flow of events or the relationships involving the use case. |
To discover and define effective use cases, you must understand the relationship between the use cases and the state of the system and how these are related to events happening outside the system. The reason for this is that the use cases describe the behavior of the system, behavior that results in changes in the state of the system. In order to understand how use cases start and how use cases end, you must consider the state of the system.
Thus far, we have spent a lot of time talking about the use-case model of the system and the requirements of the system without specifically defining what we mean by a system. The Collins Modern English Dictionary defines a system as
A group of things or parts working together or connected in some way as to form a whole [a solar system, system of motorways].
The UML contains the following definition of system:
(1) A collection of connected units that are organized to accomplish a specific purpose. A system can be described by one or more models, possibly from different viewpoints. Synonym: physical system.
(2) A top-level subsystem.
So far as this book is concerned, the system is the thing that is being developed. The system itself may be composed of a number of smaller units [2] and may, if necessary, collaborate with any number of peer systems. The key thing about a system is that it clearly forms a whole. We can clearly see what is part of the system and what is outside the system. The system has a distinct boundary. The system boundary defines the border between the system (our proposed solution) and the environment that surrounds, and interacts with, the system.
Because of the existence of the system boundary, most systems can be treated as black boxes that respond to stimuli from their surrounding environment. The system takes inputs from the surrounding environment and processes them to produce outputs (see Figure 7-1). One way of defining the system is to document all of the possible inputs and their corresponding outputs. A small subset of systems performs pure transformations on the input data, producing the same output for the same input at all times. The vast majority of systems are more complex and vary the output depending on the state of the system and the state of the environment surrounding the system.
Systems can also be treated as stimulus-response machines. [3] In this case, rather than considering only the input/output relationship, we consider the events in the environment that the system will respond to, the state that the system is in, and the events that the system will generate to effect change in the surrounding environment, as shown in Figure 7-2. Use-case models are a variation on the stimulus-response model of systems. The actors represent people, or other systems, that interact with the system. The actors are outside the system but are essential to the definition of the behavior of the system, as they are the source of the events detected by the system and the target for any events generated by the system (see Figure 7-3).
In a use-case model, the detected and generated events are categorized as
Major Events: Those that start a use case
Minor Events: Those that are generated as part of an ongoing interaction between the system and an actor
It is this classification of events that enables use cases to focus on the value provided by the system, to put requirements into context, and prevent the unnecessary multiplication of use cases, which would happen if a use case was produced for every event detected by the system.
The use-case description must clearly describe the event that will start the use case. The communicates relationships clearly denote the source of the initial event (the actor that starts the use case) and whether the use case starts interactions with any additional, supporting actors. To see the details of the events, and the corresponding dialog between the use case and its actors, we will have to look to the detail of the use-case description. As we shall see, this description includes the definition of all of the inputs and outputs that make up the dialog as well as details of how the behavior of the system is affected by the underlying state of the system.
If we revisit our simple telephone system example, last seen in Chapter 2, we can superimpose a box representing the system boundary onto the diagram. This is shown in Figure 7-4. This presentation illustrates the stimulus-response nature of the use-case model and is preferred by many use-case modelers, as it clearly shows the boundary of the system.
Sometimes, the system must be in a particular state in order for the use case to be executed: An automated teller must possess funds to dispense, an engine must have fuel, and a user must be authorized to use the system. Sometimes these conditions can be verified by a simple test, and sometimes there will be a use case to verify or establish the condition. Whatever the case, it is inconve-nient, distracting, and even wrong to force every use case that depends on these conditions to repeat the description of how the system is put into the desired state. Instead, we simply want to declare the required condition, or state, in which the system must be; we call this declaration the precondition.
Examples of Preconditions
The user must be authorized to use the system (or, alternately, the user is logged-in).
The system must have sufficient cash available to process a typical transaction. [*]
The communication channel to the host system is open and available for use.
The precondition is a statement about the condition or conditions that are required in order for the use case to be performed. Often, these preconditions are established by the execution of other use cases, so why do we use preconditions stated in terms of the desired result, instead of saying, “The use case ‘Authenticate User’ has been executed”?
There are three reasons. First, we want to make the use-case descriptions as much as possible into independent stories of what the system does to provide value for one or more actors. If one use case becomes dependent on other use cases, it makes the use case harder to understand. Second, just because the use case Authenticate User has been executed, that doesn’t mean the user executing the current use case has been authenticated. Perhaps the result of the execution of Authenticate User was to allow the user to access the system but with re-duced privileges, or perhaps a different user executed it several months ago. Finally, there may be more than one way for the system to reach the desired state. We may have more than one way to authenticate the user (we could use a user identifier and password scheme, or we may use a special card combined with a personal identification number (PIN), or we could even use a retinal scan if we want to be really exotic). Each one of these could be a different use case with a different flow of events, all resulting in the same state—the user is authorized to execute transactions in the system.
The preconditions themselves are “necessary but not sufficient” for the use case to be performed. The precondition must hold if the use case is to be started but is not going to result in the use case being started automatically just because it becomes true. Starting a use case requires an actor to do something. The precondition merely states the conditions under which the use case can be started. The states that the precondition refers to should also be “externally visible”—in other words, be a condition that the actors would understand. Preconditions must not refer to the design of the system; they should be applicable regardless of how the system is implemented.
Postconditions are statements about the state (or condition) in which the system is at the conclusion of the use case. Postconditions are not triggers for other use cases; they are just summarizations of fact. They help ensure that the reader understands what the result of executing the use case has been. In the example of the use cases that authenticate the user, the postcondition is that the user is authorized to execute transactions in the system or the user has been barred from using the system.
Sometimes we try to make things more complicated than they really are. Preconditions and postconditions are simply statements of the condition (or state) in which the system is when the use case starts and ends. In addition, preconditions and postconditions are optional features of a use case—they may be omitted if the system state is not important to how the use case starts or ends. They are seldom required for every use case in a system, but when they are needed, it’s typically obvious. If no precondition is defined, then there is no restriction on when the use case can be started. If no postcondition is defined, then there are no explicit constraints on the state of the system when the use case ends.
Use cases do not directly communicate with one another (they are, after all, just descriptions). The only way for use cases to interact is via the state of the underlying system. Use cases can check the state of the system at any time, or wait for the state of the system to change, or can be dependent on the state of the system via the use of preconditions. There is no way of directly relating use cases. In fact, there is nothing in the definition of a use case that allows the sequencing of use cases in a direct way. This is by design. Each use case is intended to be independent of other use cases; use cases are independent sequences of behavior that results in something of value to a user of the system.
Sometimes, a group of headstrong developers will subvert the use case into a design tool, decomposing the system behavior into use cases. They produce use cases that may sound something like Login, Select Products, Enter Order Information, Enter Shipping Information, Enter Payment Information, and Confirm Order if the system provides on-line order capabilities. These “things” certainly describe behaviors that the system must support, but ask yourself this: Is each of these things independently valuable? Would you ever do just one without the others? The answer is, of course, no; there is no need to enter shipping information if there is no order.
The team has most likely taken a wrong turn. This is usually confirmed by their expressed need to somehow sequence the use cases. Lacking an association that might allow one use case to “call” another use case, clever modelers sometimes turn to the use of preconditions and postconditions. This trouble-some cleverness is founded upon the idea that the precondition for one use case could be said to be the successful completion of another use case. Or the postcondition for a use case could be the execution of another use case. So, like a row of dominoes, the use cases fall one-by-one in a sequence.
The first problem with this is that the need to strictly sequence use cases is a symptom of a poor set of use cases—steps or functions masquerading as use cases. To solve this problem, the use cases should be grouped together so that they become a single use case that provides some value to the use of the system. So the preceding “use cases” merge into a single use case, Browse Products and Place Orders. [4]
The second problem with using preconditions and postconditions to sequence use cases is that the solution is hard to maintain because the dependencies are hard to see. Even if the use cases are at the right level of granularity, it is better to state precondition dependencies in terms of some state or condition that must exist before the use case can begin. That state may occur, of course, as the result of some other use case completing, or there may be several different use cases that all result in the system being in the same state. Stating precondition dependencies in terms of some condition that must be satisfied is more robust and is unlikely to be affected by changes to the use-case model, such as splitting or combining use cases.
The use of preconditions can have a direct effect on the shape of the use-case model as a whole as well as the shape of the individual use cases.
The precondition defines a state in which the system must be before the use case can be performed; as a result, the flow of events of the use case does not test the precondition. An alternative to stating a precondition is to include the test specifically in the flow of events of the use case. Only use preconditions where they help to clarify the required behavior.
Example
If one of the automatic teller machine’s use cases has the precondition “The communication channel to the host system is open and available for use,” then the use case cannot be started unless the connection is available. An alternative to using the precondition is to test the state of the connection inside the use case.
The use case starts when the actor Customer inserts the bank card.
If there is no connection to the financial institution, then the system informs the Customer that the service is not available and the use case ends.
The dangers of using preconditions to reduce the amount of checking to be done within a use case include
The checking specification can often be forgotten. In most cases, it is very easy to deduce what the check should be. What is more difficult to deduce is what action should be undertaken when the condition does occur. If the test is undertaken by the use case, then corrective actions can be defined.
Use cases can be created that can never be started. Remember the precondition must be true for the use case to be executed. If preconditions are overused, it is not unusual for use cases to be given preconditions that are impossible for the system to achieve.
If we were to revisit our simple phone system example, we could look at the precondition for the Place Local Call use case:
This simple application of a precondition raises issues about the completeness of our use-case model:
How does a handset get registered to an account?
How is an account activated or deactivated?
In this case we would need to add at least one use case to our simple telephone system model:
Example
To allow accounts to be managed and handsets to be registered to accounts, a new use case needs to be added to the model. This is shown in Figure 7-5.
The use of preconditions can help with the assessment of the completeness of the use-case model by explicitly calling out important system states and making them more visible to the use-case developers and reviewers.
People find several things about the flow of events confusing:
The structure of the flow
The relationship between the complexity of the use-case model and the complexity of the system being described
The relationship between flows, scenarios, and use-case realizations
In this section, we address these issues. (Note: This section uses lots of short extracts from the Browse Products and Place Orders use case last seen in Chapter 6, The Life Cycle of a Use Case. A more complete version of this use case can be found in Appendix A.) Additional examples can be found at www.usecasemodeling.com.
Unfortunately, the UML treats the entire flow of events as a single property of a use case and has little to say about how it should be structured. As we have seen throughout this book, a good structure of the flow of events makes the use-case description easier to understand and therefore more useful. By this point, you should be comfortable with the concepts of the basic flow, subflows, and alternative flows. In this section, we will look at their structure and definition in more detail.
As seen in Chapter 6, The Life Cycle of a Use Case, there are many styles for writing up the flows of events. We recommend adopting the narrative style, numbering each step and titling each self-contained section in newspaper style. This will enable the reader to see an overview of the flow without having to read all the details and to unambiguously refer to a step when it is being reviewed.
When you detail each step in the outline, be sure to describe the flow of events, not only what the system is doing. A suggestion for how to enforce this is, where possible, to start every step with “The [actor] . . . ” or “The [system] . . . .” Each time the interaction between the actor and the system changes focus (between the actor and the system), the next segment of behavior should start with a new paragraph. This ensures adherence to the spirit of the purpose of a use case and makes analysis of the use case far easier.
Example
The Browse Products and Place Orders use case includes the following behavior:
The system displays the product offerings, highlighting the product categories associated with the Customer’s profile.
The Customer selects a product to be purchased, entering the number of items required.
For each selected item that is in stock, the system records the product identifier and the number of items required, reserving them in inventory and adding them to the Customer’s shopping cart.
Steps 3 and 4 are repeated until the Customer selects to order the products.
The majority of actions in the flow of events are system controlled. That is, after the user’s initial request to begin the use case, the system controls the interaction: The system asks for information and the user supplies information; the system asks for a decision and the user takes it; and so on.
General guidelines for the contents of a flow are
Describe how the flow starts and ends.
Describe what data is exchanged between the actor and the use case.
When first referring to an actor, precede the name of the actor with the identifier “actor.” For example, use “Actor Customer” rather than just “Customer” to clearly distinguish the actor from a reference to any similarly named entity.
Do not describe the details of the user interface, unless they are necessary to understand the behavior of the system.
Describe the flow of events, not only the functionality. To enforce this, start every action with “The actor . . . ” or “The system . . . .”
Describe the events that belong only to the use case and not what happens in other use cases or outside of the system. [5]
Describe what the system does, but be careful—remember the flow of events should present what the system does to perform the required behavior, not how the system is designed.
Detail the flow of events—all “whats” should be answered. Remember that test designers are to use this text to identify test cases.
Describe things clearly enough that an outsider could easily understand them.
Use straightforward vocabulary. Don’t use a complex term when a simple one will do.
Write short, concise sentences.
Avoid adverbs, such as very, more, rather, and the like.
Avoid vague terminology, such as information, etc., appropriate, required, relevant, and sufficient.
Use correct punctuation.
Avoid compound sentences.
Make sure that the sequence of events is clear. If the order of the events is not important, make sure that this is clearly stated. If the order of the events described for the use case does not have to be fixed, do not describe it as though it does have to be fixed.
Use terminology consistently throughout the use-case model. To manage common terms, put them in a glossary.
When using glossary terms in the flow of events, clearly distinguish them from the other text by making them bold.
These guidelines apply to all the different kinds of flow: the basic flow, subflows, and alternative flows.
The basic flow of events should cover what “normally” happens when the use case is performed. The basic flow should be named “Basic Flow” and be the first flow to be described in the use case’s flow-of-events section. The basic flow should start by clearly defining the actor and event that the actor initiates to start the use case. It should then describe the normal way that the actor (or actors) and the system interact to derive value from the system. Finally, it should describe how the use case ends.
Example
The Browse Products and Place Orders basic flow case starts with the paragraph:
The use case starts when the actor Customer selects to browse the catalogue of product offerings.
It ends with:
The system asks the Customer if there are any more products to be ordered.
If the Customer wants to order some more products, the use case resumes from {Display Product Catalogue}.
If the Customer does not want to order any more products, the use case ends.
Complex flows of events should be further divided into subflows. The main goal in doing this should be improving the readability of the text.
A subflow should be a segment of behavior within the use case that has a clear purpose and is “atomic,” in the sense that either all or none of the actions described are performed. You may need to have several levels of subflows, but if you can, you should avoid this as it makes the text more complex and harder to understand. Remember that the use case can perform subflows in optional sequences or in loops or even several at the same time.
For clarity, subflows should be named and numbered. Number the subflows S1 . . . SN and give them active names that sum up their purpose.
Example
The Browse Products and Place Orders use case contains the following subflows:
S1 Validate Payment Instructions
S2 Validate Shipping Instructions
S3 Execute the Financial Transaction
To reference a subflow from another flow of events, use the syntax:
Perform subflow <subflow name>
Example
The following extract from the Browse Products and Place Orders use case illustrates the use of the three subflows named in the previous example:
7. The Customer enters the payment instructions.
8. The system captures the payment instructions using a secure protocol.
9. Perform Subflow Validate Payment Instructions.
{Invalid Payment Instructions}
10. The system prompts the Customer to enter shipping instructions.
11. The Customer enters the shipping instructions, supplying at least the billing address, shipping address, shipper preference, and delivery options.
12. The system captures the shipping instructions using a secure protocol.
13. Perform Subflow Validate Shipping Instructions.
{Invalid Shipping Instructions}
14. Perform Subflow Execute the Financial Transaction.
The guidance for writing flows outlined in the preceding Defining a Flow of Events section also applies to subflows.
Extension points are named places in the flow of events where additional behavior can be inserted or attached. Extension points may be private (used only within the use case in which they appear) or public (used by other extending use cases). Chapter 10 will describe the use of public extension points. Extension points presented in Chapters 7–9 are private extension points. Within the flow of events, extension points are shown in bold and enclosed in curly brackets: [6]
Example
The use case Browse Products and Place Orders includes the following extension points:
{Display Product Catalogue}
{Out of Stock}
{Process the Order}
{Order Processed}
There is no specific naming convention for extension points. They are least intrusive if they sum up some aspect of where the position is in the use case or what the use case has achieved.
Extension points can occur anywhere in the flow of events, although we prefer them to be on their own line and not embedded in a chunk of text. [7] One good way to use extension points is as headings in the text to delimit self-contained sections of flows.
Example
The Basic Flow of the Browse Products and Place Orders
Use Case Including Extension Points
The {Display Product Catalogue}, {Select Products}, and {Process the Order} extension points are used as headings, whereas the {Out of Stock} and {Order Processed} extension points reflect the state of the use case.
With extension points, the basic flow now becomes
The use case starts when the actor Customer selects to browse the catalogue of product offerings.
{Display Product Catalogue}
The system displays the product offerings highlighting the product categories associated with the Customer’s profile.
{Select Products}
The Customer selects a product to be purchased, entering the number of items required.
For each selected item that is in stock, the system records the product identifier and the number of items required, reserving them in inventory and adding them to the Customer’s shopping cart.
{Out of Stock}
Steps 3 and 4 are repeated until the Customer selects to order the products.
{Process the Order}
The system prompts the Customer to enter payment instructions.
. . .
There are three kinds of extension points. [8] They can be used to define
A single location, the most straightforward of usages. In this case, the extension point defines a single point in the flow of events; this is indicated by placing the extension point at a unique position in the flow of events.
A set of discrete locations. In some cases you wish to place the extension point in multiple places within the flow of events. The extension point will therefore represent a state that several of the flows of events can reach rather than a position in the flow of events. This is indicated by the extension point appearing in multiple places in the flow of events.
A region. In some cases you may want to mark up a region of a use case, in effect marking the set of all of the locations between two defined points in the flow of events. Without sophisticated tool support, this actually requires the introduction of two extension points. The region could be between any two extension points, but typically there is a clearly matched pair of extensions points whose names are intuitively related.
Example
In a use case for a system that controls a pump to dispense fuel, you could delimit the section of the flow of events where fuel is being dispensed with the extension points {Pump Activated} and {Pump Deactivated}
In the Browse Products and Place Orders use case basic flow, the flow of events between the two extension points {Select Products} and {Process the Order} could be treated as a region.
The beauty of extension points is that their location can be changed without affecting their identity or requiring any changes in the flows of events that reference them. As we shall see in the next section, the primary use for extension points is for defining alternative flows.
The alternative flows of events cover behavior that is of optional, exceptional, or truly alternate character in relation to another flow of events. Alternative flows are always dependent on some condition occurring at an explicit point in another flow of events. If the alternative flow is not conditional, then it is not an alternative.
There are three kinds of alternative flow:
Specific Alternative Flows: These are alternative flows that start at a specific named point in another flow of events.
General Alternative Flows: These are alternative flows that can start at any point within the use case.
Bounded Alternative Flows: These are like general alternative flows but can only occur between two named points.
We will look at examples of these after we have examined the syntax for declaring the different kinds of alternative flow.
Alternative flows are named and numbered. Number the alternative flows A1 . . . An and give them active names that sum up their purpose. The first line of the alternative flow’s flow of events identifies the point at which the alternative will be activated and the conditions under which it will occur. This clause is always of the form:
At {extension point} when <some event occurs> . . .
or
At {extension point} if <some condition is true> . . .
Note: If required, both the {extension point} and the <condition> can be compound clauses, although great care should be taken to ensure that it is actually possible for them to be true simultaneously. The last line of the alternative flow, and any other exit points within it, must state explicitly where the actor resumes the flow of events. This will be either the original extension point where the alternative flow was triggered or another extension point elsewhere in the flow of events, unless the use case ends. For optional behavior, this is usually the original extension point; for truly alternative behavior, this is usually another extension point; for exceptional behavior, this is usually the end of the use case. (Note: The flow of events can only be resumed at an extension point that identifies a single location or the extension point from which it was started.) If the use case ends in the alternative flow, explicitly state “The use case ends” in the alternative flow’s flow of events.
In the use case Browse Products and Place Orders, there are many alternative flows, including A3 Handle Product Out Of Stock and A1 Undertake a Keyword Search.
Example 1
A specific alternative flow
A3 Handle Product Out Of Stock
At {Out of Stock} if there are insufficient amounts of the product in the inventory to fulfill the Customer request.
The system informs the user that the order cannot be fulfilled.
. . . the flow continues to describe the offering of alternative amounts and products to the Customer . . .
The flow of events is resumed from the point at which it was interrupted.
Example 2
A bounded alternative flow
A1 Undertake a Keyword Search
At any point between {Display Product Catalogue} and {Process Order} when the Customer selects to undertake a keyword search.
The system prompts the Customer to enter the product search criteria.
The Customer enters the product search criteria.
. . . the flow continues to describe what the Customer and the System do to complete the search. . .
The flow of events is resumed at {Select Product}.
Unfortunately, there are no general alternative flows in the Browse Product and Place Orders use case, but if there were, they would have the pseudo extension point “At any time in the flow of events . . . ,” and they would have to either resume from the point where the original flow was interrupted or end the use case.
You may well be wondering why we have focused so on the structure of the flow of events, especially on exception points and alternative flows. Why don’t we just do everything using subflows and if statements as one long and continuous narrative? The reason is related to the way that use cases are used to manage the scope of the system. You want to be able to define meaningful subsets of functionality that will actually deliver value to the customer. You also want to be able to take subsets of functionality away without breaking the system and/or failing to provide any value at all.
If we consider things only at the level of entire use cases, we will not be able to do very much scope management because the use cases will tend to be large and relatively indivisible. By adding structure within the use-case description using alternative flows, we introduce a way to remove scope from the system by removing alternative flows. The very purpose of alternative flows is to permit behavior to be removed without affecting the basic flow or other alternative flows, because alternative flows are often optional and address behaviors that are outside of the normally expected behavior.
Consider the Cash Withdrawal use case as it was outlined in Chapter 4:
Example
Basic Flow
Insert Card
Validate Card
Validate Bank Customer
Select Withdraw
Select Amount from List of Standard Amounts
Confirm Transaction with Banking System
Dispense Money
Eject Card
List of Alternative Flows
A1 Card cannot be identified
A2 Customer cannot be identified
A3 Withdraw not required
A4 Nonstandard amount required
A5 No money in the account
A6 Attempt to withdraw more than daily amount
A7 No connection to the banking system
A8 Link goes down
A9 Card stolen—the card is on the hot card list
A10 The ATM is out of money
A11 The card cannot be dispensed
A12 A receipt is required
A13 The withdrawal is not from the card’s primary account
and so on . . .
What is the impact of not delivering “A3 Withdraw not required” and “A4 Nonstandard amount required” and “A12 A receipt is required” and “A13 The withdrawal is not from the card’s primary account”? Would you still have a usable system that delivers the value of the use case (the ability to withdraw cash)? Yes, you would. Not all of the alternative flows represent core functionality. In fact, you may well discover that some of them are not required at all; they may cost too much or may not provide enough value to warrant further development.
In comparison, what would be the impact of not delivering part of the basic flow? Would you be able to deliver a usable system if you failed to deliver the capability to validate the card or confirm the transaction with the banking system or dispense the cash? No, you would not. Without the entire basic flow the use case cannot deliver any value at all.
The alternative flows allow you to incrementally add functionality on top of the basic flow as the use case evolves or to remove functionality as the time and money run out. You can also clearly see the impact of not including a use case or an alternative flow: If it is not included, you will not get the value that it delivers. This does not hold true if you divide the functionality up in a more stepwise (part 1, part 2, part 3) sort of way. If you leave out the second half of the use case, then you do not deliver any of its value.
It is this structure that makes use cases so integral to iterative and incremental development. It allows the targeting of individual sets of flows onto the iterations and the value provided by the system to increase iteration by iteration.
Some people have the idea that a system with a complex design will have a complex use-case model. It may, but the complexity of the required behavior of the system (as expressed in use cases) is really wholly unrelated to the complexity of the design. Design complexity is a function of how hard something is to implement, whereas use-case complexity is a function of how hard the desired behavior is to describe.
A system such as a building monitoring system may have a quite simple use case model, even though the system itself can be quite complex. The main use case is Monitor Building, and this is responsible for monitoring for events (fires, break-ins, and so on) and responding to them. A few other use cases exist to maintain the system information, but otherwise, that’s about it. The system itself can become quite complex, having to correctly detect events (and screen out false alarms) as well as control and coordinate many different devices. The complexity of the system comes from the problem domain and certain nonfunctional requirements that dictate the required responsiveness of the system, the types of devices that must be used, the need to correctly report fires and detect false alarms, and so on. But the use-case model itself is fairly simple.
Example
Five analysts (business experts) eventually decided that a medium-scale system development effort for a transportation system had only eight use cases—the main two being Import Goods and Export Goods. Initially, they had assumed that the system was complex and identified over a hundred use cases. These turned out to be functions or features that the use cases provided; once they realized this, the model became much easier to understand.
If you have too many use cases—if your use cases are really functions in disguise—you will struggle to write meaningful use cases. You will find yourself needing to invent ways to string use cases together to provide something the user finds meaningful or valuable. In the need to fill the “use cases” with content, you will tend to fill them with design and implementation details that obscure the real value of the system to its users. And you will probably end up wondering why use cases are so great—you will have the same problems you do with every other technique: Technical documentation that is incomprehensible to the stakeholders of the system and also very detailed “requirements” that do little to help you build the right system.
The internal complexity of the system is completely unrelated to the number or length of the use cases. What the use cases reflect is really the complexity of using the system, and that should be as simple as possible.
Although the additive nature of the use cases is crucial to their effective use in requirements management, planning, risk reduction, testing, and other downstream activities, it can make it very hard to get an overview of the entirety of the use case. Sometimes, although the basic flow is clearly defined, the stakeholders need to have an overview of the key alternative flows to fully understand the scope of the use case. This can be difficult when you have to wade through a long list of alternative flows and track back to their extension points to see when and where they will apply. If the stakeholders require some kind of holistic overview of the entire functionality provided by the use case, then the use-case authors need to supply it. One way to do this is to provide some form of visualization of the flow of events to act as a map of the underlying textual definitions.
The most typical way to do this is to use a UML activity diagram or a traditional flowchart. Figure 7-6 shows an activity diagram illustrating the Browse Products and Place Orders use case. Figure 7-6 uses the following elements:
Figure 7-6. An activity diagram presenting an overview of the Browse Products and Place Orders use case. The basic flow is shown shaded to distinguish it from the alternative flows.
|
UML Element |
Meaning |
|---|---|
|
 |
Start State—represents the event that starts the flow of events. |
|
 |
Activity State—represents the performance of an activity or step within the flow of events. Activities allow you to show the subflows and sections of the basic and alternative flows. |
|
 |
State Transition—shows the ordering of the activities. The transition is triggered by the completion of the activity the activity state represents. |
|
 |
Decision Points—represent extension points where decisions may be taken. The condition to be evaluated at the decision point is shown by a guard condition. Decisions and guard conditions allow you to show alternative flows in the flow of events of a use case. |
|
[condition] |
Guard Conditions—control which transition (of a set of alternative transitions) follows once the activity has been completed. |
|
 |
End State—shows where the use case ends |
Other elements are available for use on activity diagrams:
Synchronization bars. that you can use to show parallel subflows. Synchronization bars allow you to show concurrent threads in the flow of events of a use case.
Swim lanes. that let you show whether the responsibility lies with the actors or the system.
As you can see from the example, the diagram does not capture all of the nuances of the textual flow of events. It is very difficult to show bounded or general alternative flows when using this kind of notation. It also does not show all of the detail of the flow of events, as this would render the diagram overly complex and make it harder to understand than the original flow of events it is supposed to illuminate. It does allow the highlighting of the most significant alternative flows and their relationship to the basic flow. The thing to remember is that this is just an illustration, not the definition of the flow of events. Only use these forms of diagram if they make the use case more accessible to the readers and add value to the use case modeling process.
A dangerous side effect of attempting this kind of diagrammatic representation of the flow of events is a tendency to overly decompose the use case to force the text to match the structure of the diagram. These sorts of diagrams should only be added to the use case to provide an informal overview of the general shape and purpose of the use case. Using this kind of pictorial representation does not reduce the amount of text that needs to be written—you still have to write all of the flows of events, and, in our opinion, you should do this first. If this kind of diagrammatic representation is used, it is recommended that you take great care and limit it to providing high-level overviews of the structure of the flow of events.
Scenarios are instances, or specific occurrences, of use cases. Scenarios are useful because they help us think in concrete terms about what a system will do when a particular use case is performed. They help us walk through exactly what will happen to make sure that we have handled everything properly, and they can be useful later on in defining the test cases that are required to test the system to make sure that it performs the way the use cases say it should.
A typical use case will have a main flow of events and several alternative flows of events. A single scenario will walk through one particular path of the use case, exploring a particular way that the use case can be performed from beginning to end. To explore the relationship between a use case and its scenarios, let’s consider an example. Assume that we have a simple use case that maintains the temperature in a room (in other words, a use case for a thermo-stat). Just to make things interesting, let’s assume that the room has temperature sensors and that the system makes sure that the average temperature of the room is within the acceptable range.
Example
Monitor and Maintain Temperature use case
1. The use case begins when the Facility Manager engages the temperature control system.
{Determine Temperature}
2. The system determines the average temperature of the room by polling the temperature sensors placed throughout the room, summing the readings, and dividing by the number of sensors deployed.
{Turn On/Off Heat}
3. If the average temperature of the room is below the desired room temperature minus 5 percent, the system activates the flow of gas, ignites the gas, and turns on the forced-air fan if it is not already on.
4. If the average temperature of the room exceeds the desired room temperature plus 5 percent, the system deactivates the flow of gas. It also turns off the forced-air fan if the fan setting is set to “automatic”; otherwise, the forced-air fan continues to run.
5. The use case continues until the system is deactivated by the Facility Manager.
The variables presented in this use case are highlighted in bold in the example: the average room temperature, the sensor readings, the number of sensors, the desired room temperature, and the fan setting. So many variables for such a simple use case!
When you consider scenarios, look at “boundary” conditions, the points at which a small change in the value of some variable causes some very different behavior in the system as a whole. The boundary conditions help you find interesting values for the variables and spot flaws in the use case. For example, what happens if there are no sensors? The system will try to divide by zero and will halt. What happens if the average temperature is exactly equal to the desired temperature minus 5 percent? The system will not turn on the heat, because the average temperature has to be more than 5 percent below the desired temperature. Is this acceptable? What happens if the fan is set to “off” when the temperature falls below the desired temperature threshold? Should the system still turn on the fan? What should it do when the desired temperature threshold is exceeded? Should it turn the fan off? If you focus on the boundary conditions when forming your scenarios, you will find the number of scenarios much more manageable and the scenarios themselves much more useful. From looking at our scenarios, we are forced to really think about the use case and what it says, and by so doing we are better able to spot and fix the flaws in the use case basic flow and the alternative flows.
One final point about use-case scenarios: The number of scenarios can multiply combinatorially if you’re not careful. Consider the situation in which there are four completely independent alternate flows (A1–A4) plus the main flow. If you were to create independent scenarios for each possible path through the use case, you would have at minimum 1 (main) + 4 factorial, or 25 different scenarios, and this does not even include different boundary conditions. It is clearly impossible to formally document all of these scenarios.
In fact, you rarely have to document (or even identify) all of the scenarios. If the alternative flows are really independent, then you can consider only five scenarios—the main plus each of the four alternatives combined with the main—because the alternative flows won’t affect one another. And sometimes alternative flows can be combined into a single scenario (if they occur in different parts of the main flow of events), so the number can drop further. Look for these opportunities to “prune” the number of scenarios, and you’ll make your life a lot easier.
The purpose of the use-case realization is to separate the concerns of the speci-fiers of the system (as represented by the use-case model and the requirements of the system) from the concerns of the designers of the system. A use-case realization represents the design perspective of a use case. It provides a construct in the design model that organizes artifacts related to the use case but which belong to the design model. The use-case realization is a collaboration of components that realizes (or performs) some use case. The realization describes how the behavior of a use case is performed by the collaboration of elements within the system
The main purpose of the use-case realization is to provide a bridge between the descriptions of the system used by external stakeholders (principally users and customers), such as use cases and requirements, and the descriptions of the system used by internal stakeholders (principally developers and testers), such as designs, code, and test cases. Use-case realizations overcome a problem area that is key in many other development techniques— the discontinuity between requirements and design. By connecting these two major areas of interest, they prevent the design and tests from significantly diverging from the user and customer perspectives of the system.
The separation of the use-case realization from the use case is essential, as it decouples the use case from its implementation, allowing the design to progress without affecting the baseline requirements captured in the use case. It also allows multiple designs to be produced for the same use case. This is particularly important for larger projects or families of systems where the same use cases may be designed differently in different products within the product family. Consider the case of a family of telephone switches, which have many use cases in common but which are designed and implemented differently according to product positioning, performance, and price.
Typically, for each use case in the use-case model, there is a use-case realization in the design model with a realization relationship to the use case. Figure 7-7 shows how this is visualized using the UML. In addition, there is typically at least one test case for every use-case realization. Use-case realizations can be expressed visually, using UML constructs such as sequence and collaboration diagrams, or textually, using structured English. In fact, when people write their use cases with an implementation focus, discussing the components of the system and the way that they work, they are actually creating a textual use-case realization rather than a use-case description.
In this chapter we have looked in detail at how the contents of a use-case description is structured and defined. We are now ready to look at the mechanics of actually writing some of these detailed use-case descriptions.
Chapter 8, Writing Use-Case Descriptions: An Overview, describes the objectives and challenges related to writing detailed descriptions of use cases and presents strategies for successfully mastering this task. Chapter 9, Writing Use-Case Descriptions: Revisited, discusses the mechanics of writing use-case descriptions, how to handle details, and how to structure the descriptions for readability. The chapter uses an evolving example in which a variety of techniques are progressively and systematically applied to improve the quality of the use-case description.
[1] This chapter builds on the work of Ivar Jacobson, who originally identified the concepts presented in this chapter.
[2] A system at one level of abstraction may be a subsystem of a system at a higher level of abstraction (the earth can be considered a system but is itself part of a larger system: the solar system).
[3] See Cooke and Daniels “Designing Object Systems” for a discussion of systems as stimulus-re-sponse machines.
[*] As we get further into the details of writing use cases, we will see that all of the descriptive text that we write is dependent on the existence of a well-understood and documented set of underlying definitions. The reference to a “typical transaction” is OK as long as there is a definition of a typical transaction somewhere.
[4] You may have already noticed that this set of mini use cases are just the major steps of the Browse Products and Place Orders use case we examined in Chapter 6, The Life Cycle of a Use Case.
[5] If you need to describe events that don’t belong to the use case, to make the use case more accessible to the stakeholders, make sure that they are clearly distinguished from the rest of the flow of events and marked as being a comment. We would suggest using quotation marks and italics to distinguish any comments inserted into the use-case description.
[6] There are other ways of showing extension points, but this is the one we prefer and is therefore the one that we have used throughout this book.
[7] Note: There is another way of defining extension points separately from the flow of events, but the technique is harder to use, harder to maintain, and, most important, actually renders the flow of events harder to read. A sophisticated editing tool could enable the extension points to be suppressed or displayed at the user’s convenience, providing the best of both worlds.
[8] As detailed in Rumbaugh, Jacobson, and Booch, The Unified Modeling Language Reference Manual.