In this chapter we discuss requirements[1]. Some may question whether a developer-focused process should include requirements at all, since many developers are not responsible for defining them. We have chosen to include a discussion on this topic because some requirements artifacts have a significant impact on the development effort. In particular, we discuss the specification of Use Cases, which then drive the rest of the development process.
A key concern of any software development project is not only building the system right, but also building the right system, where the “right system” is one that meets the requirements as specified by the end users and other key stakeholders[2]. Implementing a requirements management process ensures that the system delivered to the end users meets their expectations.
Requirements management is a systematic approach to:
Eliciting, organizing, and documenting the requirements of the system in such a way that all stakeholders (including the developers) understand them
Establishing and maintaining agreement between the customer and the project team on the system's changing requirements
We have found Use Cases to be a very effective technique for achieving both objectives. In fact, one of RUP's characteristics is that it is use-case-driven, which means that Use Cases are not only used for documenting the requirements, but are also used to drive iteration planning, analysis and design, implementation, and testing. As we will demonstrate in subsequent chapters, Use Cases provide the unifying thread through the software development process and its artifacts. This thread starts with the Use Cases themselves (discussed in this chapter), continues with the Use-Case Storyboards and the analysis-level Use-Case Realizations (both discussed in Chapter 7, Analysis) and culminates with the design-level Use-Case Realizations (discussed in Chapter 8, Design), which describe how the Use Cases are performed by collaborations of system elements.
For the purpose of this book, we assume that a Vision of what needs to be built already exists. A Vision defines the stakeholders' view of the system to be developed, and is specified in terms of the stakeholders' key needs and desired features. A Vision outlines the envisioned core requirements and may be as simple as a problem statement.
In this chapter, we describe the process for developing the following re quirements artifacts:
Use-Case Model. The Use-Case Model defines the behavior of the system from an external perspective. It includes the Actors that interact with the system (such as the end user), and the Use Cases that describe these interactions (such as “Place Bid” in an auction system).
Supplementary Specification. The Supplementary Specification captures system-wide requirements that are not readily captured in the Use-Case Model. Such requirements include legal and regulatory requirements, application standards, quality attributes (such as usability, reliability, scalability, performance), operating systems and environment requirements, compatibility requirements, and other design and implementation constraints.
Glossary. The Glossary defines important terms used by a project. It provides a set of definitions, which promotes consistency of the terminology used on the project.
These artifacts serve as a contract between the customer, the end users and the system developers. They allow customers and end users to verify that the system will become what they expected, and enable system developers to build what is expected.
As described in Chapter 3, An Introduction to the Rational Unified Process, the requirements activities vary throughout the development life cycle as shown in Figure 6.1.
The definition of the system requirements is not something that happens once, at the beginning of the project. It would be unrealistic to assume that we could fully understand and document all of the requirements of the system up front. The requirements must be refined throughout the life cycle of the project (hence the need for an effective requirements management process). The requirements activities are most visible late in the Inception phase, where the scope of the system is established and the Use Cases are prioritized, and during the early Elaboration phase, where the architecturally significant requirements are detailed as part of the development of the architectural baseline. However, some requirements activities are performed in the Construction phase, as the remaining requirements are detailed, and even in the Transition phase, as requirements are refined based on feedback received as a result of transitioning the system to the end user.
The Requirements discipline in the J2EE Developer Roadmap is described using two workflow details (1) Define the System and (2) Refine the System Definition as shown in Figure 6.2.
The Define the System workflow detail is where the scope of the system is established and documented in the Use-Case Model. It concentrates on the requirements “big picture” and is usually performed very early in the project. However, since the system definition is rarely (if ever) known completely, the system definition resulting from this workflow detail evolves over time as we gain a better understanding of what is expected of the system.
The Refine the System Definition workflow detail concentrates on the details of the Use Cases being addressed in the current iteration, and on refining the overall system definition, where necessary. Thus, the Refine the System Definition activities are performed multiple times in a project, usually once per iteration.
Throughout the requirements activities, system-wide requirements that are not applicable to specific Use Cases are captured in the Supplementary Specification and common terms and concepts are captured in the Glossary.
We look at the activities performed in each of these workflow details in subsequent sections.
One of the first things that must be done on a project is to initially define what is to be included in the system, and what is not. Establishing this system scope is the purpose of this workflow detail, whose activities and key artifacts are shown in Figure 6.3.
In early iterations we establish the common terms and concepts to be used throughout the project. This is done in the activity Capture a Common Vocabulary. The use of a single Glossary eliminates the need to document the same concept in multiple places and ensures that the same term is used consistently. The Glossary is continually refined throughout the project, as new terms and concepts are identified and existing ones are better understood.
A critical aspect of the system definition is its scope and therefore, its boundaries. In the activity Find Actors and Use Cases, we identify the Actors and Use Cases and document them in the Use-Case Model. We do not describe the Use Cases in detail at this point. Instead, we concentrate on defining their intent and purpose and possibly on outlining their content in order to allocate requirements to them. We document the requirements that we cannot associate with a particular Use Case in the Supplementary Specification.
Once the scope of the system is understood, we prioritize the identified Use Cases in the activity Prioritize Use Cases. We can then use the resulting Use-Case Priority List to plan the iterations, scheduling the work on the highest priority Use Cases first[3].
The workflow detail concludes with the Review the Requirements activity where, as the name implies, we review the requirements artifacts to verify that they reflect the customer's view of the system and we make sure that we understand what we are building.
A project should consistently use a common vocabulary that is aligned with the terminology of the problem domain. It is especially important that the use-case descriptions consistently use that vocabulary to avoid misunderstandings among the project members. The vocabulary terms are documented in the Glossary.
Table 6.1. Online Auction Application Glossary Terms
| Name | Description |
|---|---|
| Auction | A sale in which an item is sold to the highest bidder |
| Auction Information | Information about an auction, which includes the start time and duration of the auction, product information (title, description, image), starting price (minimum initial bid price), minimum bid increment, and auction category (the category in which the auction is listed) |
| Credit Card Information | Information about a credit card, which includes the credit card number, billing address, and the card's expiration date |
| Pending Payment Notice | Information about a payment that the user still owes to the system |
| User Information | Information about a user, which includes the user's name, password, and e-mail address |
Common terms are typically those that frequently come up when describing the system and what it does. Each term should have a clear and concise definition, and all stakeholders should agree on these definitions. In Table 6.1, we show a few terms from the Glossary of the Online Auction application.
The Actors and Use Cases that we identify during this activity are considered preliminary. We will refine them as we examine the use-case flows of events in more detail in the Refine the System Definition workflow detail, and as we gain a better understanding of the requirements. Also, even though we present the identification of the Actors and Use Cases as a series of discrete and sequential steps, in reality the Actors and Use Cases are usually identified at the same time—defining a Use Case may result in the identification of additional Actors, defining an Actor may result in the identification of additional Use Cases, and the cycle continues.
When defining the system, one of the first things we identify is the system Actors. An Actor is someone or something outside the system that interacts with the system. An Actor can be a person, an external system, or an external device (such as a printer).
Finding Actors helps establish the boundaries of the system since Actors, by definition, are external to the system. It also assists us in understanding the purpose and extent of the system. Only Actors that communicate directly with the system are considered.
The Actors we identified for the Online Auction application are shown in Figure 6.4. As you can see, we have defined a generalization relationship between the Buyer and Seller Actors, and the User Actor. We use generalization to express the commonality of these roles. The benefits of defining a separate User Actor will become clearer once we identify the Use Cases in the next step and see how the individual roles interact with the system. We discuss generalization among Actors in more detail in the Structure the Use-Case Model activity.
In Table 6.2, we show our descriptions of the Actors for the Online Auction application.
In the Online Auction application, we put the Actors in the “Actors” package of the Use-Case Model, as shown in Figure 6.5. Figure 6.5 represents a “model explorer view” of the model elements. Model explorer views are not UML, but are a graphical notation we use throughout this book to represent the organization of the models in an “outline form.”
Table 6.2. Online Auction Application Actors' Descriptions
| Actor | Description |
|---|---|
| User | The User represents the general, casual user of the Auction system who has not yet committed to either buying or selling anything. It is the role that performs a basic set of system features that may be performed by all roles derived from this role. |
| Buyer | The Buyer represents a User who has registered with the system and is inter- ested in purchasing an item that is available for auction. |
| Credit Service Bureau | The Credit Service Bureau is an external system that validates a User's credit card information and assists in handling credit card payments. |
| Seller | The Seller represents a User who has registered with the system and is inter- ested in selling an item in an auction. |
Now that we have a candidate list of Actors, the next step is to look for the system's Use Cases. A Use Case is a description of a complete flow of events that results in something of value to an Actor. The best way to find Use Cases is to consider what each Actor requires of the system. This is because the system only exists in order to service the requests of the Actors that interact with it.
The following is a set of questions that we have found useful when identifying Use Cases.
For each Actor, what are the tasks in which the system would be involved?
Does the Actor need to be informed about certain occurrences in the system?
Will the Actor need to inform the system about external changes?
Can the identified Use Cases provide all the system features described in the Vision?
What information must be modified or created in the system, and what Actors must participate in those changes?
What Use Cases will support administration and maintenance of the system (for example, adding new users)?
In the Online Auction application, we put the Use Cases in the “Use Cases” package of the Use-Case Model, as shown in Figure 6.6.
When we identify a Use Case, we need to name it and give it a brief description. The name of the Use Case should indicate what is achieved through the interactions between the Actors and the Use Case, and may consist of several words, of which one should be a verb. The brief description of a Use Case should reflect its goal and purpose, should refer to the Actors involved, and should use the terms defined in the Glossary. We have found that a name and brief description is usually all that is needed for the Use Case at this point in the process. We will expand on this information when we flesh out the details of the Use Case in the Detail a Use Case activity.
In Table 6.3, we show the Use Cases we have identified for the Online Auction application, as well as their brief descriptions.
Table 6.3. Online Auction Application Use Cases
| Use Case | Description |
|---|---|
| Browse Auction Catalog | The Browse Auction Catalog use case allows the User to browse items currently available for auction. The User may search for a specific item, or look at all of the items currently available for auction, sorted by category. The User has the option to place a bid on an item available for auction (see the Place Bid use case). The User does not have to be signed in to browse the auction catalog. |
| Close Auction | The Close Auction use case describes what occurs when an auction is closed. This use case is executed when an auction's end time is reached. When an auction is closed, the current highest bid becomes the purchase price for the item. The Buyer and Seller are notified that the auction has closed, what the final purchase price is, and information on how to contact each other in order to complete the transaction. The transaction fee is charged to the Seller's credit card. If the Seller's credit card cannot be charged, a pending payment is recorded for the Seller and the Seller will not be able to participate in any auctions until the pending payment is made. |
| Create Account | The Create Account use case allows the User to create and activate a user account, using entered user information, which optionally includes credit card information. Once the account has been created and activated, the User is considered to be signed in. |
| Create Auction | The Create Auction use case allows a Seller to create an online auction by specifying auction information (including the start and end times) and, if it was not provided when the Seller created his or her user account, credit card information (see the Create Account use case). Once the auction has been created, Buyers can then place a bid on the item (see the Place Bid use case). To create an auction, the Seller must be signed in (see the Sign In use case) and must not have any pending payments (see the Close Auction use case). |
| Manage Account | The Manage Account use case allows a User to update the information main- tained in his or her account. If new credit card information is entered, the system attempts to pay any pending payment notices via the Credit Service Bureau using the entered information. The User may also deactivate his or her account. If there are any auctions in progress for the account, or the User has any pending payments, the account cannot be deactivated. A deactivated account is not deleted from the system (it may be needed later for auditing purposes), but the User cannot access it. |
| Place Bid | The Place Bid use case allows a Buyer to place a bid on an item when browsing the auction catalog (see the Browse Auction Catalog use case). To place a bid on an item, the Buyer must be signed in (see the Sign In use case) and must not have any pending payments (see the Close Auction use case). |
| Sign In | The Sign In use case allows the User to identify him- or herself to the system. If the User already has an account in the system, the User supplies a username and password for authentication purposes. If the User does not have an account in the system, the system gives the User the opportunity to create one (see the Create Account use case). All sign in attempts, whether successful or not, are logged. If the User has pending payment notices, the system informs the User that payment for the notices must be made before the User can participate in any auction (as either the Buyer or the Seller). |
| Sign Out | The Sign Out use case allows the User to indicate that he or she no longer wants to use the system. The User's account remains unchanged (that is, it is not removed). Sign out events are not logged. The User must be signed in to sign out (see the Sign In use case.) |
As we examine the system requirements to identify Actors and Use Cases, we may find that some of the requirements cannot be allocated to specific Use Cases, but instead apply to the system as a whole. We document such requirements in the Supplementary Specification.
In Table 6.4, we show a few entries from the Supplementary Specification of the Online Auction application.
Now that we have identified the preliminary set of Actors and Use Cases, we model the relationships between them. A relationship between an Actor and a Use Case is represented in UML as an association. A Use Case has at most one association to a specific Actor, and an Actor has at most one association to a specific Use Case, no matter how many interactions there are between them. The complete network of such associations is a static picture of the communication between the system and its environment.
A Use Case is usually initiated by a single Actor, but may interact with multiple Actors. There are exceptions to this rule. One is Use Cases that have relationships with other Use Cases, which we will discuss later in the activity Structure the Use-Case Model. Another exception is Use Cases that are initiated by an internal system event, such as a timer. In such cases, the use of an Actor may be considered inappropriate since the Use Case is not initiated by something external to the system.
Table 6.4. An Extract from the Supplementary Specification of the Online Auction Application
| Category | Description |
|---|---|
| Usability | The system shall provide online help. |
| Availability | The system shall be continuously available (often referred to as 24 × 7 operation)[5]. Backup and maintenance operations shall not require a system shutdown. |
| Performance | The response time for any query shall be less than three seconds when measured on a 100Mb/sec local area connection. The response time for all transactions, such as creation of an auction, shall be less than five seconds from the time that transaction data is submitted to the time that transaction results are reported to the User. |
| Supportability | All errors shall be time stamped and logged in the system error file. Exception mes- sages should identify the system element that threw the caught exceptions. |
| Development and Deployment Environment | The application should be developed and deployed on the J2EE platform. |
[5] This is a simplification. In reality, a more detailed service level agreement is produced, which provides a much clearer guide as to the level of failure that is deemed “acceptable.” A blanket “24 × 7” availability requirement often results in an overengineered application. | |
In Figure 6.7, we show a subset of the interactions between the Actors and Use Cases identified for the Online Auction application. The interpretation of the model is straightforward and goes like this. A Seller can put an item up for sale by creating an auction (“Create Auction” Use Case), and a Buyer can request that a bid be entered for a particular item (“Place Bid” Use Case). In both of these cases, the Actor initiates the communication with the system, so the navigation is from the Actor to the Use Case. Periodically, the system closes auctions (“Close Auction” Use Case). Since the Use Case is initiated by the system itself, no initiating Actor is shown. When an auction is closed, the system notifies the Buyer and the Seller, as well as the Credit Service Bureau (to charge a fee to the Seller's credit card). In this case, the system initiates communication to the Actors, so the navigation is from the Use Case to the Actors.
Figure 6.7 also demonstrates the specific interactions that the individual roles have with the system in terms of the Use Cases they initiate. For example, a casual User can browse the auction catalog, sign in and out of the system, create a user account, and manage his or her account information. However, only Buyers can place bids and only Sellers can create auctions.
Keep in mind that the purpose of the Use-Case Model is to serve as the contract between the development team and the system stakeholders. It is therefore important that the complexity of the model be kept to a minimum. If the number of Actors or Use Cases becomes too great, then we group them and put them into separate packages in the Use-Case Model. This additional packaging can help with the communication, development and maintenance of the model. In our example, there are a small number of Actors and Use Cases, so no further packaging is required.
A critical input to this activity is the Vision, which identifies the key things the stakeholders require of the system, and the Risk List, which identifies the known and open risks to the project. Both the risks and the key requirements should have been prioritized in order of importance.
As we discussed in Chapter 3, a system is built in a series of iterations where a portion of the system's functionality is delivered incrementally. The sequence in which the functionality is developed is chosen in order to address and mitigate the most critical project risks as early as possible.
In this step, we order the Use Cases[6] according to established project-pecific criteria. This criteria may include the benefit to stakeholders (for example, how important the Use Case is to the end user, or how important it is to demonstrate a consistent part of the system functionality to the project's sponsor), the architectural impact and coverage (for example, performing the Use Case involves key aspects of the architecture such as access to databases, integration with legacy systems, and so on), and the risks mitigated by addressing the Use Case (for example, the Use Case includes access to an external system whose interface is not well understood).
We document the results in the Use-Case Priority List, which is used during iteration planning. The content and order of successive iterations is determined by selecting the Use Cases to be analyzed, designed, and implemented in the iterations, selecting the highest priority ones first. It is quite possible that in order to meet the specified project end date, the lower priority Use Cases may not be implemented before the release of the system.
It is important to note that the Use Cases are not just prioritized once. We examine their relative priorities in every iteration and, where necessary, adjust those priorities based on the current project status, including new requirements, discovery of new risks, and mitigation of existing risks.
In our Online Auction example application, we prioritized the Use Cases as follows:
Create Auction
Place Bid
Close Auction
Browse Auction Catalog
Create Account
Sign In
Manage Account
Sign Out
The first two Use Cases (Create Auction and Place Bid) are at the heart of the Online Auction application, so we put them at the top of the list. The third Use Case (Close Auction) may have some interesting performance requirements if we want to close a large number of auctions at the same time, so we put it next on the list. The fourth Use Case (Browse Auction Catalog) places more emphasis on the user interface than the other Use Cases and may best be experimented with after the core auction management capabilities are in place. The remaining Use Cases have to do with typical user account management that is expected to be straightforward to implement, so we put them last on the list.
Related to the prioritization of Use Cases is the identification of which Use Cases are architecturally significant. Architecturally significant Use Cases are those that represent some significant, central functionality, that have substantial architectural coverage, or that stress or illustrate a specific, delicate point of the architecture. There will always be overlap between the priority of a Use Case and its architectural significance. For example, early iterations focus on technical risks, so the Use Cases are primarily ordered by architectural significance. Later iterations focus on business risk, so the Use Cases are primarily ordered by critical business functionality.
In the case of our Online Auction application, the highest priority Use Cases are also the Use Cases that exercise the architecturally significant parts of the system.
The architecturally significant Use Cases are documented in the Requirements Review of the Software Architecture Document. For more information on documenting the software architecture, see Appendix A, Describing a Software Architecture.
In this step, we review the “big picture” requirements artifacts (those artifacts whose scope is the system as a whole). These are the artifacts that define the common terms to be used throughout the system (the Glossary), specify the scope of the system (the Use-Case Model), describe any system-wide requirements (the Supplementary Specification), and recommend the order in which the Use-Cases should be developed (the Use-Case Priority List).
This review serves as a “quality gate” where we make sure that the requirements artifacts are mature enough to support the next set of activities—detailed requirements definition. It is important that people outside the development team (for example, end users and customers) approve the requirements artifacts at this stage. They need to verify that the artifacts capture the intended scope of the system and the required system behavior. It is also important that the development team be involved to make sure they understand what needs to be built, as well as to identify areas where more information is needed.
We document any discovered problems in the artifacts in Change Requests. Once the review is complete, we briefly capture the results of the review, including any action items, in a Review Record.
The following checkpoints describe things that should be kept in mind when reviewing the requirements artifacts at this stage.
The Use Cases and Actors should capture the required system behavior and interactions. Each functional requirement should be mapped to at least one Use Case. All use-case-specific nonfunctional requirements should be mapped to the appropriate Use Cases.
All requirements that do not map to a specific Use Case should be captured in the Supplementary Specification.
There should be no unnecessary Use Cases. The Use-Case Model should not contain any superfluous behaviors; it should be possible to trace all Use Cases back to a functional feature in the Vision.
The Use-Case Model should adhere to the Use-Case Modeling Guidelines.
Each term in the Glossary should have a clear, concise, and unambiguous definition.
The Use-Case Model and the Glossary should be consistent. Terms defined in the Glossary should be used consistently within the Use Cases, and any terms that appear in multiple use-case specifications should be included in the Glossary.
The relative priorities of the Use Cases should be captured accurately in the Use-Case Priority List. These priorities should reflect the Vision and the current Risk List.
At this point, we have an initial specification of what the system is required to do and what its scope is. The specification has been captured in the Use-Case Model and the Supplementary Specification. Now, we turn our attention to refining this initial system definition to gain a deeper understanding of the requirements. The primary output of this workflow detail is captured in a detailed set of Use Cases, a refined Supplementary Specification, and (possibly) a restructured Use-Case Model. The activities performed in this workflow detail are shown in Figure 6.8.
In the activity Detail a Use Case, the flows of events of a previously identified Use Case are described. Any requirements that are not specific to the Use Case are documented in the Supplementary Specification. The Detail a Use Case activity is performed once for each Use Case in the current iteration. The detailing of the individual Use Cases can occur in parallel, but it is a good idea to hold frequent informal walkthroughs to ensure consistency among the Use Cases.
Once a more detailed understanding of the Use Case flows of events is reached, some refactoring may be done in the Structure the Use-Case Model activity to eliminate redundancy and to reduce the complexity of the Use-Case Model. We recommended that such refactoring be deferred until this activity (as opposed to being done during the activities of the Define the System workflow detail) because an effective and appropriate restructuring effort cannot be undertaken until you have a more in-depth knowledge of the requirements. Before we move on to the analysis and design activities, the requirements artifacts are reviewed in the Review the Requirements activity to verify that they capture the customer's view of the system.
Use Cases are detailed incrementally, with a subset of the Use Cases being de tailed in a particular iteration. Thus, the Refine the System Definition activities are performed multiple times in a project.
In this activity, we start with the use-case description produced in the Find Actors and Use Cases activity, and gradually make it more detailed until all of the stakeholders are happy that it unambiguously expresses their requirements.
We specify the following information when we detail a Use Case:
Name. The name of the Use Case (initially defined in the Find Actors and Use Cases activity)
Brief Description. The goal and purpose of the Use Case (initially defined in the Find Actors and Use Cases activity)
Flows of Events. A textual description of what the system does; it is expressed in terms of interactions between the Actors and the system
Special Requirements. A textual description of requirements not considered in the use-case flows of events, but that need to be taken care of during design or implementation; in other words, nonfunctional requirements specific to the Use Case
Preconditions. The required state of the system in order to execute the Use Case
Postconditions. A list of possible states the system must be in immediately after the Use Case has finished
We capture the detailed textual description of the Use Case in a separate document known as a use-case specification and associate it with the Use Case, as shown in Figure 6.9.
A Use Case may have a number of potential flows through it, as shown symbolically in Figure 6.10. A Use Case has an expected flow, usually referred to as the “basic flow,” as well as a number of alternative flows that may arise due to, for example, exceptional conditions. All of these flows must be captured.
The following information should be included in the detailed use case flows of events:
How and when the Use Case starts
When the Use Case interacts with the Actors, and what information is exchanged
How and when the Use Case uses information stored in the system, or stores information in the system
How and when the Use Case ends
When describing the flows of events of a Use Case, it is important to consider the context of the Use Case. The context of the Use Case is described by the relationships that the Use Case has with Actors and other Use Cases (for more information on relationships between Use Cases, see the Structure the Use-Case Model activity described later). This context can be expressed using a “local” use-case diagram that only contains the Use Case, its Actors, and other Use Cases with which the Use Case interacts. The local use-case diagram for the “Close Auction” Use Case is shown in Figure 6.11.
The use-case specification should refer to the Glossary to ensure that consistent terms are used. Also, all of the Actors that interact with the Use Case (as shown in Figure 6.11) should be explicitly mentioned in the use-case specification.
In Table 6.5, we describe the flows of events we produced for the “Close Auction” Use Case.
We sometimes come across requirements that are associated with a Use Case but that are not associated with any flow of events in particular. Such require ments are often nonfunctional in nature, and are described in the “Special Requirements” section of the use-case specification.
Table 6.5. “Close Auction” Use-Case Flows of Events
| Name | “Close Auction” Use-Case Flow of Events | |
|---|---|---|
| Basic Flow |
| |
| Alternative Flow 1—No Bids Posted for Auction | After marking the auction as closed, if no bids have been posted for this auction, the following steps are performed.
| |
| Alternative Flow 2—Transaction Fee Not Collected | After the system marks the auction as closed, if the system is unable to collect the transaction fee from the Seller's credit card account (for example, the Credit Service Bureau responds to the request with a message such as “insufficient credit”), the following steps are performed.
|
For example, the following are the special requirements of the “Place Bid” Use Case of the Online Auction application:
The system must guarantee that the order of bids processed is strictly the same as the order in which they came in. It must not be possible for two identical bids arriving closely together to be accepted out of order, regardless of network service delays, processing delays or the like.
The Buyer should be able to place a bid on an item within three mouse clicks after accessing the auction catalog.
The Buyer should be able to scroll a list of auction items by pressing a single keyboard button.
Sometimes it is necessary for the system to be in a particular state before the Use Case can start. A common example is the “user is signed in” state. This step ensures that all such preconditions are specified and documented with the Use Case. For example, the “Place Bid” Use Case of our Online Auction application specifies the preconditions shown in Table 6.6.
It may also be necessary to describe what must be true after the Use Case completes. The “Close Auction” Use Case has the postcondition shown in Table 6.7.
Now that we have detailed the Use Cases, we will take another look at the Use-Case Model and refine its structure to eliminate redundant requirements and improve its overall maintainability. This must be done carefully because there is the potential that such restructuring can decrease the overall understandability of the Use-Case Model, since we are spreading flows across multiple Use Cases. Structuring the Use-Case Model should not significantly degrade the comprehension of the requirements. If it does, do not restructure.
Refining the structure of the Use-Case Model involves identifying new elements and relationships or modifying existing ones. With regard to Use Cases, we will focus our discussion on two relationships—include and extend.
The include relationship is where common flows of events are extracted and placed in a separate Use Case. The Use Case containing the common flows of events is “included” in those Use Cases that require the common flows of events. In the UML, the include relationship is modeled as a dependency association with the stereotype «include». It is drawn from the Use Case requiring the common flows of events to the Use Case containing the common flows of events.
An example of the includes relationship from our Online Auction application is shown in Figure 6.12, where the “Create Account” Use Case includes the “Sign In” Use Case. This means that when a new User creates and activates his or her account, the User is automatically signed in to the system.
The extend relationship is where optional or exceptional flows of events are extracted and placed in a separate Use Case. The Use Case containing the optional or exceptional flows of events then “extends” the original Use Case. In the UML, the extend relationship is modeled as a dependency association with the stereotype «extend». It is drawn from the Use Case containing the optional or exceptional flows of events to the Use Case being extended.
An example of the extends relationship from the Online Auction application is shown in Figure 6.13, where the “Place Bid” Use Case extends the “Browse Auction Catalog” Use Case. What this means is, as the Buyer browses the auction catalog, the Buyer has the option to place a bid on an auction item.
As mentioned earlier, we use generalization relationships to model Actors that have common characteristics. Now that we understand the roles a little better and how they interact with the system, we further refine the initial Actor generalization hierarchy shown in Figure 6.7 to include another generalized Actor, “Registered User.” A Registered User is a User that has an account with the Online Auction application. As we show in Figure 6.14, each Actor has a different interaction with the system in terms of the Use Cases he or she is able to initiate.
A general User can browse the auction catalog or create an account (which then makes him or her a Registered User). A Registered User can sign in or out of the system, or make changes to his or her account. A Seller can create auctions, and a Buyer can place bids on those auctions.
In this step, we review the detailed requirements artifacts, especially the detailed descriptions of the Use Cases being considered in the current iteration. We also review the Supplementary Specification.
Once again, the review serves as a “quality gate” that ensures that the requirements artifacts are mature enough to support the analysis activities. It is important that people outside the development team (for example, end users and customers) approve the requirements artifacts at this stage. They should verify that the artifacts capture the detailed requirements accurately.
We document any discovered problems in the artifacts in Change Requests. Once the review is complete, we capture the results of the review, including any action items, in a Review Record.
The following checkpoints describe things that should be kept in mind when reviewing the requirements artifacts at this stage.
The use-case specifications should accurately capture the functional and use-case-specific nonfunctional requirements.
The Supplementary Specification should accurately capture the requirements not specifically tied to a Use Case, as well as any design or implementation constraints.
The use-case specifications should adhere to the Use-Case Modeling Guidelines.
The use-case specifications and the Glossary should be consistent. Terms defined in the Glossary should be used consistently within the Use-Case specifications, and any terms that appear in multiple Use-Case specifications should be included in the Glossary.
If the Use-Case Model was restructured, all the original relationships between Actors and Use Cases should still hold and should be consistent with the refined relationships.
The descriptions of the Actors and Use Cases should be consistent with their relationships.
All relationships between Use Cases and Actors should be required (that is, there is justification for all include-, extend-, and generalization-relationships).
The readability of the Use-Case Model should not be reduced as a result of any restructuring.
In this chapter, we described the process for documenting the requirements of the system, resulting in the following key artifacts: Use-Case Model, Supplementary Specification, and Glossary. These artifacts, most notably the Use Cases in the Use-Case Model, drive the development activities in Chapter 7, Chapter 8, and Chapter 9, Implementation.
[1] A requirement describes a condition or capability to which a system must conform; it is either derived directly from user needs, or stated in a contract, standard, specification, or other formally imposed document.
[2] A stakeholder is someone who is materially affected by the outcome of the project. This includes, among others, the customer, the end user, and the developers.
[3] Iteration planning is not in the scope of the J2EE Developer Roadmap. For more information, see RUP.
[4] In the activity tables, artifacts shown within parentheses are “subartifacts” of the preceding artifact.
[6] In practice, entire Use Cases are usually not developed in a single iteration. In most cases, specific flows, or specific scenarios, are delivered. Thus, the prioritization may need to be done at a granularity that is smaller than an entire Use Case. The granularity should reflect whatever granularity the iteration planning is based on.