The whole idea of requirements is about nailing down the problem that the system is intended to solve. You must be able to elicit and explore the root problem with the stakeholders. You must understand the business domain; you must walk through the business scenarios with the stakeholders; you must identify key desirable features of the system with them. You frequently do these activities in parallel, and the goal is to draw out the stakeholders’ real needs.

It is an important stakeholder concern that the system correctly and accurately captures the problem domain. This can be effectively achieved through classes. When being introduced into a new problem domain, you need to quickly grasp its essential concepts that distinguish this new problem domain from another. Classes are excellent tools for you to describe such concepts. For example, if you are ever required to build a hotel management system, you need to understand what constitutes such concepts as Room, Promotion, Reservation, Customer, and Bill. Even if you have built such a system for Hotel Chain ABC, the terms used by Hotel Chain XYZ might be different. It is extremely important that you clarify these concepts. You can capture them in a glossary. You can most certainly depict them visually as classes through a class diagram such as that shown in Figure 7-1, which further shows the relationships between these classes.

Figure 7-1. Domain classes for the Hotel Management System.

Finding these classes constitutes what is known as domain modeling, or business object modeling [Jacobson et al. 1994]. You go through the essential business scenarios that your system will be supporting to identify what information the system needs to keep track of or manipulate. Such information will be modeled as domain classes. It is usually sufficient to identify the essential attributes and relationships between these classes. At this point, you are merely capturing the essential concepts and their relationships. You should not go into too much detail as if you were doing data modeling in database design. You will do that later.

Stakeholders and project sponsors normally justify the need for a new system or an enhancement by emphasizing the benefits and payoffs of specific features. Features are high-level statements of desired system capability, which can either be in terms of functionality (i.e., what the system can do) or some other quality attribute (performance, security, etc.). There are many ways to come up with the features for a system. You can conduct some brainstorming with the stakeholders; you can look at the problems they are facing; you can walk through the business process with them; and so on. But whichever method you use, you end up with a list of key features for the system. As an example, Listing 7-1 itemizes the key features of the Hotel Management System.

Listing 7-1 gives us, in concise terms, an overview of the system’s requirements. However, it definitely does not constitute all the requirements for the system. Listing 7-1 is still a long way from that. From the perspective of the developer, the features are still open to many interpretations, and different acceptance criteria can be proposed for each one. Additional work is necessary to clarify what each feature means. One way to find out more about these features is to refine them one by one, resulting in a long requirement list. But if you do this, you end up with loose bits of information.

A more effective approach is to walk through the use of the system and uncover how the features are put into effect. This is a better approach because it puts the features in the context of the system operation. This is what use-case modeling is all about. The remainder of this chapter describes how to map these features to use cases. We also describe how to explore and uncover requirements surrounding these features and how to capture them through use cases. Through use cases, you clarify stakeholders’ concerns about the system’s functionality and quality.

Most analysts distinguish between two kinds of requirements: functional requirements (FRs) and nonfunctional requirements (NFRs). Typically, functional requirements refer to what users can do with the system, whereas nonfunctional requirements usually refer to qualities of the system. Features 1 through 7 in Listing 7-1 are usually considered functional requirements; whereas features 8 through 13 are considered nonfunctional, or at least cross-functional: that is, they apply to all the functions in features 1 through 7.

Today, most practitioners model functional requirements with use cases, but they tend to leave nonfunctional requirements out of use-case modeling. However, use cases are applicable to nonfunctional requirements too. So long as a requirement requires some observable response to be programmed into the system, you can apply use cases. Always ask yourself, is there something the system must do to meet a particular requirement? If the answer is yes, then use cases can be applied because use cases help you capture desired system behaviors. Also ask if there is a way to test the system for conformance to the requirement. As long as you can define a test, you can indeed define a use case for it. After all, a use case is a set of test cases. Basically, each scenario in the use case is a preliminary test case. To complete the test case, you need to add test data. Making use cases/test cases upfront has been popularized through test-first-design techniques.

Nonfunctional requirements usually need the support of some underlying infrastructure mechanisms. For example, feature 12 needs some infrastructure mechanism to track user inputs. Feature 13 requires an infrastructure mechanism to utilize some form of caching to meet the 2-second response time requirement. So, these nonfunctional requirements do impose some behaviors on the infrastructure. You can most certainly model these infrastructure mechanisms with use cases. To distinguish such use cases from others, we call them infrastructure use cases. We call the others application use cases. Infrastructure use cases deal with infrastructure concerns, and application use cases deal with application concerns.

Most of you are familiar with writing application use cases. Here, we recommend that you specify the use cases for infrastructure mechanisms as well. The advantages for doing so are many. It helps the development team understand how the infrastructure mechanism will be used. Too frequently, we find that infrastructure mechanisms are poorly described. There might be a bunch of diagrams that attempt to describe the realization of the infrastructure mechanism, but they generally describe only the basic use of it. How exceptions and variations are handled is usually either not considered or poorly described. This leads to obscure defects in the system. You apply the same technique as you do with application use cases to explore the different scenarios that each infrastructure mechanism has to handle. There will be basic and alternate flows and so on in infrastructure use-case specifications just as in typical use-case specifications. We discuss how to model such infrastructure use cases later in this chapter.

Once you have identified the use cases for the system, you have in effect separated the different concerns for a system from the actor or user perspective. Now you can explore the concerns of each use case in greater detail. For each use case, there are many flows of events, each describing how a particular variation is handled through that use case. It is important to have a systematic way to explore variations. Otherwise, you risk missing key requirements of a system. To avoid this risk, you have to identify variables for your system or for each use case. Some of these variables may be critical concerns to your stakeholders. In our example Hotel Management System, they are so important that they appear in the key feature list in Listing 7-1. Features 6 and 7 identify two variables, Customer Types and Reservation Channels. Each variable may take on different values. You may have values for the Customer Types variables such as individual customer, corporate customer, registered customers, and customers from an affiliate hotel. You may have values for different Reservation Channels such as through an agent, a telephone (i.e., an interactive voice response unit), or the Internet. Customer Types and Reservations Channels are not the only variables: as yet another example, you can have a variable for reservation schemes with values such as a single period reservation, reservation over multiple time periods, recurring reservations, and so on.

Identifying variables and their values is important because they help you to understand the complexity of the system you are developing. They identify the universe of your requirements gathering effort—that is, your project scope. Forgetting to deal with a variable or a variable value has negative consequences on the completeness of requirements. Thus, it is important to identify them early in the project.

The domain model shown in Figure 7-1 is quite useful in identifying the variables. The domain class itself and the attributes of the domain class and associations between domain classes are all candidates of use-case variability.

Use-case variables will likely affect multiple use cases. For example, most of the use cases identified earlier in Figure 7-2 will be affected by the Customer Type variable; thus, you might have scenarios describing how corporate customers reserve room, check in, check out, and use their loyalty credits, and those customers may be given higher priorities on the waiting list. In other words, the variables crosscut use cases, and you might consider them “aspects of use cases” (see Sidebar 7-1).

The handling of each variable value tends to be use-case-specific. Hence, while the variables may cut across use cases, it is better to leave them within the use cases and describe how to handle them as alternate flows. In fact, use-case variables help you organize your alternate flows. You can have one section per use-case variable, and within each of these sections, describe how each variable value is handled. This organization is shown in Listing 7-2.

There are two ways to describe the basic flow, either generically and independent of each use-case variable or using a default value. Listing 7-2, shows the use of default values in the basic flow. It assumes that the customer is an individual customer, the reservation is for a single time period, and the reservation is made over the Internet. The variations to this default case are handled in the alternate flows, which are organized according to the use-case variables.

When describing the handling of each variable, you walk through the basic flow and identify steps or points that are affected by that variable. You consolidate these points (which we call variability points) as sort of an introduction for that variable. So, each variable becomes a subsection within the alternate flows. Within this subsection, you describe how each variation is handled as an alternate flow. Organizing use-case specifications in this way makes reading use-case specifications a lot easier. This is much better than merely producing a long list of alternate flows. It facilitates reviewing the use case for completeness. It also facilitates the subsequent transition to analysis and design.

When helping the stakeholders to describe how they intend the variations to be handled, you can use a diagram similar to Figure 7-3. The figure presents the variables on each axis, and the markings on each axis represent a particular value.

Figure 7-3. Handling use-case variability.

Using Figure 7-3, you can ask whether the use-case variables are independent of each other. For example, how different reservation channels are handled is independent of the other two variables in the figure. Customer types and reservation periods may have some relationships. For example, only a corporate customer can make reservations over recurring periods, or there may be different pricing between customer types and reservation periods. When there is interplay between use-case variables, you need to supplement your use-case specifications with tables and matrices to summarize how they are handled.

It is not always possible to describe precisely how the variables are handled through use cases. In such cases, you might want to postpone this to analysis or even just list them as test cases.

If the handling of each variable is generic across use cases, you may want to factor them into a generalized use case. In this way, you avoid being repetitive in your use-case specifications.

Sometimes, how variations are dealt with is dependent on the customer site (e.g., for Hotel Chain ABC or Hotel Chain XYZ). In this case, you may wish to describe them in a separate extension use case containing a number of extension flows that describe the desired behaviors to meet the needs of that customer site.

Identifying these variables is extremely important if you want to build an extensible system because the system will likely be extended on the basis of these variables. For the Hotel Management System example, you might wish to introduce a new customer type, a new reservation scheme, a new reservation channel, and so forth. We discuss how you can design your system to be extensible in Part 4 of the book, specifically in Chapter 13, “Separating Functional Requirements with Application Extension Use Cases.”

Our use-case model survey in Figure 7-2 shows several extension use cases. Some of these extension use cases are what we call concrete use cases—they can be instantiated separately from the use cases that they extend. Examples are the Handle Waiting List and the Earn and Redeem Credits use cases. We discussed the Handle Waiting List use case in Chapter 6, “Structuring Use Cases.” In this chapter, we discuss the Earn and Redeem Credits use case. Figure 7-4 provides a visual representation of this use case. With this use case, a customer can view the credit she has accumulated. She can also purchase reward items with the credits. These are achieved through the basic flows listed in Figure 7-4.

Figure 7-4. Outlining an extension use case.

A customer’s credits can be accumulated only when she makes payment for hotel facilities. This is achieved through the extension flow Earn Credits. The customer can also use credits to pay for the hotel facilities she uses. This is achieved through the extension flow Make Payment with Credits. Recall that extension flows are alternate flows that execute in the context of separate use case—the base use case. The base use case is identified through an extension pointcut. The Earn and Redeem Credits use case has an extension pointcut named MakingPayment. It is used in both extension flows and it is defined to refer to the extension point Collect Payment in the Check Out Customer use case.

As you can see, an extension use case itself can be modeled relatively independently from the use case it extends. Its basic flows are separate from the Check Out Customer use case. The extension flows can be described by referencing to MakingPayment pointcut as an indirect reference to some extension point in another use cases.

The details of the extend relationship between the base and extension use cases needs coordination between the authors of the respective use cases. The interface between the extension and the base use case is expressed in terms of extension pointcuts and extension points. So, there is some coordination between the authors of both use cases to define them (i.e., extension pointcuts and extension points). There are basically two methods of coordination. In the first method, the author of the extension use case lists the pointcuts he or she needs. The author of the base provides a suitable extension point. This is exemplified by the Earn and Redeem Credits use case. You want to provide this loyalty credit capability, and you determine where in which use case additional behaviors are required. In the second method, the author of the base provides a list of extension points. This is useful when you want to handle variations in the base use case, as discussed in the previous section. You can also combine both methods. Once you have clarified the interface between the base and extension use case, both authors can work on them separately.

The indirect reference from the extension pointcut to the actual execution point (the use-case step) in the base use case prevents changes in the base use case to propagate to the extension use case. If at any time the base use case gets modified, it is up to the base author to ensure that the extension point still points to a correct point in the base use case.

You can model the basic transaction through a 〈Perform Transaction〉 use case, as shown in Figure 7-5. This use case is a pattern—a template bounded to each step of an application use case. We use the angle brackets, 〈 〉, to indicate that both the Actor and the 〈Perform Transaction〉 use cases are parameterized elements.

Figure 7-5. 〈Perform Transaction〉 use case.

The 〈Perform Transaction〉 use case collates the infrastructure requirements for the system. This is exemplified in Listing 7-3.

The basic flow in Listing 7-3 usually looks simple. The complexity of the 〈Perform Transaction〉 use case lies in the variations it needs to handle, as exemplified by the alternate flows.

We show only three alternate flows in Listing 7-3. In reality, there can be quite a large number of alternate flows, and an experienced architect will want to explore them and track their implementation. The 〈Perform Transaction〉 use case provides a convenient place to document these variations and the context in which they occur. If the 〈Perform Transaction〉 use case needs to deal with too many variations, you can factor out the different concerns into separate extension use cases, as we demonstrate in the next section.

The 〈Perform Transaction〉 use case is a convenient place to model the behavior required to meet nonfunctional requirements of the system. There are nonfunctional requirements that describe the system-level qualities such as that the response time should not exceed 2 seconds (see feature 13). For the time being, you model and express them using declarative statements in the special requirements section of the 〈Perform Transaction〉 use case. This is shown in the Special Requirements section of Listing 7-3.

The 〈Perform Transaction〉 use case is crucial to the architect. It is from this use case that she describes how infrastructure mechanisms are introduced. Expect that there will be different kinds of transactions, some involving the retrieval and displaying of an entity instance, some involving displaying a list of entity instances, and so on. In order for you to systematically extend them, you need to consider the different kinds of transactions that may occur. The use-case-specification technique itself offers a convenient way to describe the different kinds of transactions you have to handle. During analysis, design, and implementation, the realization of the 〈Perform Transaction〉 use case becomes a pattern that is applied to the realization of each application use-case step. Thus, the 〈Perform Transaction〉 use case also helps achieve consistency during analysis, design, and implementation.

As you explore more variants of the basic flow in the 〈Perform Transaction〉 use case, it will start to grow. For complex systems with many infrastructure considerations, a single 〈Perform Transaction〉 use case will be too large and difficult to manage. You can factor out different alternate flows from the 〈Perform Transaction〉 use case into extension flows in separate extension use cases when they represent a separate, nonfunctional concern. This is depicted in Figure 7-6. These extension use cases—Handle Authorization, Audit Transaction, and Track Preferences—are infrastructure use cases.

Figure 7-6. Structuring infrastructure use cases.

Accordingly, you need to identify extension points in the 〈Perform Transaction〉 use case and define pointcuts for each infrastructure use case in Figure 7-6. Treating infrastructure use cases as extensions of the 〈Perform Transaction〉 use case offers many advantages. It helps you visualize the context of infrastructure mechanisms. It serves as a base from which you identify extension points systematically.

From an application standpoint, the 〈Perform Transaction〉 use case serves as a template for realizing each individual use-case transaction. It greatly improves the consistency in naming conventions, structuring, and so on. This makes specifying extension points and extension pointcuts a lot easier.

Now that you have identified the infrastructure use cases, you can describe them individually. Like application use cases, infrastructure use cases frequently have basic flows. The basic flows can be for several purposes:

As an example, Figure 7-7 depicts the Handle Authorization use case. It has basic flows for the actors to define access permissions. This information is used to check if the actor is authorized to perform any transaction that arises through any application use cases.

Figure 7-7. Handle Authorization use case.

The Check Authorization extension flow executes in the context of some base use-case flows. If the actor has no authorization to perform that request, this extension flow displays some message or notification of possible violations to interested parties.

In Figure 7-7, there is an extension pointcut, PerformingTransactionRequest, which is mapped to the Perform Request extension point in the 〈Perform Transaction〉 use case. This means that you need to identify the extension point in the base 〈Perform Transaction〉 use case. This can be mapped to step 3 of the basic flow in Listing 7-3. However, you need not always define extension points exactly during use-case modeling. The textual description used in use-case specifications is imprecise, and often it is more fruitful to define them during analysis and design. During use-case modeling, you just need to know the existence of the pointcut and roughly where it points to.

Not all infrastructure use cases are as visible to the users as Handling Authorization, Tracking Preference, and Auditing Transactions, as we described earlier. A number of infrastructure use cases work in the background. For example, to meet the 2-second response, you may have an infrastructure mechanism to describe how you Provide Cache Access of frequently accessed data, as depicted in Figure 7-8.

Figure 7-8. Provide Cached Access use case.

This use case has an extension flow that looks up a local cache to see if the requested data is available in the cache. If it is available, it returns the data in the cache. Otherwise, it reads from a back-end data store, updates the cache, and returns the data to the requestor.

In Figure 7-8, there is an extension pointcut, AccessingData, which corresponds to Access Frequently Used Data in the 〈Perform Transaction〉 use case. The question is then, What are the frequently used data? This answer will not be found in the 〈Perform Transaction〉 use case. Instead, it will be found in application use cases such as Reserve Room and Check In Customer that use the 〈Perform Transaction〉 as a template. In these application use cases, you can have a special requirements section that lists the frequently accessed data. For example, room rates can be a frequently accessed data.

You may be wondering why stakeholders may be interested in such low-level infrastructure use cases. There can be several possible reasons. First, the local cache might be on the end user’s machine and may have security implications. The cache may contain valuable information that needs protection and cannot be stored in a local cache. This means that cached access is not a viable option. In addition, the end user’s machine may impose size limitations on the cache. The stakeholder may also be interested in how frequently the cache gets refreshed so that the end user may have access to up-to-date data.

The level of detail you need to get into for these infrastructure use cases is very much dependent on what the stakeholder is concerned with. But please do not assume that they are not interested in such infrastructure details at all. Today’s IT departments are usually concerned about such things. They will be more than happy to tell you their infrastructure concerns. Nevertheless, the description of the infrastructure use cases must be refined during analysis when more details are available.

As you have seen, infrastructure use cases are excellent tools for expressing concerns about underlying infrastructure support. Infrastructure use cases help you keep infrastructure services separate. However, not all nonfunctional requirements can be kept separate this way. You will encounter requirements on the overall system characteristics. An example is feature 13. It requires that each step of an application use case should take no longer than 2 seconds. Although you indeed have an infrastructure use case, Provide Cache Access, to help improve response time, it is not enough. To ascertain whether each use-case step indeed takes 2 seconds or less, you must consider a combination of use cases. Recall that infrastructure use cases extend application use cases at each application use-case step. You need to sum up the time taken by each infrastructure use case to determine the total time taken. The use-case diagram in 7-6 tells you which infrastructure use cases you need to sum up. You add up the time spent in Handling Authorization, Auditing Transactions, and Tracking Preferences. If there are potential bottlenecks, you use the Provide Cache Access to improve the response time.

The summing up of response times can be performed by inspection. But to be certain about whether the response time can be met, you need to run some tests. Yes, you need to execute the system. With iterative development, you get an executable early in the project and you can verify the quality of your system. Once you have the test results, you can determine what additional infrastructure use cases you need.