Special Edition Using Enterprise JavaBeans 2.0

With the basics of an English auction defined, the remaining task is to come up with a set of software requirements for the example. There's no need to be too rigid or formal here, but it's worth the effort to set your expectations of what the site will be built to do. The fact that you're reading an EJB book makes it relatively safe to assume that you've had some experience with object-oriented (OO) analysis and design. This chapter won't attempt to cover the details of a formal requirements gathering or analysis and design methodology, but it will hit the highlights and use some standard notation to lay the foundation for the auction site.

Software must satisfy both functional and nonfunctional requirements. The distinction between the two is that functional requirements relate directly to the business needs a system must address. As an example, being able to accept and record a bid from a participant is a functional requirement for an auction site because it relates directly to the business at hand. Nonfunctional requirements are equally important but not as directly related . This category often includes needs such as security and system maintenance.

The nonfunctional requirements for the auction site can be left somewhat vague for now while attention is focused on the functional ones. To set a foundation for using J2EE though, several nonfunctional requirements can be assumed for the example. First, the primary reason for building an online auction system is to make it easily accessible as compared to attending a live auction. With this in mind, the site should use standard Web browsers for all its user interfaces so that virtually anyone can access it. Of course, making the site easy to access brings up other issues. The system will be of value only if the winning bids are placed by legitimate participants intent on following through with their purchases. This makes it necessary to provide some level of user authentication and authorization to control access to both the maintenance and bidding functions that are eventually implemented. You should also assume that many bidders are expected and that the scalability and reliability demands placed on the system are enough to require the use of a distributed, multi-tiered architecture.

The operations the auction site will support can be defined by a set of functional requirements. There are different ways to go about capturing these requirements and documenting them, but there are similarities in how most developers do this. When documenting the functional requirements for an OO application, it's accepted practice to start with a set of use cases that define the operations needed from a system. The purpose of a use case is to describe the interaction of a user with a system to perform some tangible operation that satisfies a goal of the user. Use cases are best defined by the eventual users of the system or application developers working with domain experts to capture what is required.

Use cases can vary widely in format and in the level of detail provided, but the idea is to define what a system has to do without any mention of how it might do it. They are not intended to be technical, but should instead be easily understandable to the users. The key criteria are that they avoid implementation details and include only tasks of true benefit to the user. For an auction site, the most obvious use case is that a bidder (one of the eventual user types) must be able to submit a bid for an active auction. Although it's also a requirement, including the capability for the system to prompt the user for a username and password as a use case would likely be inappropriate because that function does nothing to help the user accomplish a business goal.

Two developers looking at the same system would almost certainly come up with two different use-case breakdowns. That might sound discouraging, but all that really matters is that the required functionality is captured by the set as a whole. Crafting a good set of use cases is as much art as it is science. Given that, we'll be careful not to let the possible nuances get in the way of progress. The use cases presented here need to be broken out and defined only to the extent that you understand the scope of the problem to be addressed.

Working from a use-case perspective fits well with our need to limit the scope of the example. Considering a wide range of use cases is important when designing flexibility into a system, but carefully selecting a subset of those to implement initially is an easy way to place limits on what has to be built. Obviously, an auction site will be useful only if bidders can place bids on an auction, so that sets the bar for the minimum amount of functionality to require. To keep the example from being trivial, we'll also include requirements for some of the auction house functionality needed to create and administer an auction. Figures 2.1 and 2.2 illustrate the use cases the auction site will support.

The notation defined by the Unified Modeling Language (UML) developed by Grady Booch, Ivar Jacobson, and James Rumbaugh is used throughout this chapter. UML is not a design methodology, but a modeling language used to communicate a design. Before its introduction, each design methodology tended to use its own notation, forcing developers to learn the differences. The standard provided by UML allows developers to focus on the software they're developing and not on the syntax used to communicate the ideas. You might already be familiar with this notation, but to make sure, quick overviews of the diagram types are included as they're introduced.

Use-case notation is quite simple and consists of only a few elements. The stick figures in Figures 2.1 and 2.2 depict external interfaces to a system and are referred to as actors . An actor usually represents a human user, but it can also depict another system or process that relies on a use case being presented. You should think of an actor as a role and not an individual person; every user that takes on a particular role when accessing a system is represented by the one actor that defines that role.

An actor initiates a use case, and the operations contained within that use case define the system's response. An actor is usually tied to multiple use cases, and a use case can interact with multiple actors as well. For the auction example, Maintenance User and Bidder represent the two user roles defined for the auction site. Any user will either be creating and administering auctions as part of a maintenance role or participating in an auction as a bidder. Figure 2.1 also includes an Auction Timer actor, which represents a process that must be able to end an auction in the same way the human Maintenance User can. This supports the need to automatically close an auction when its time limit has been reached.

The labeled ovals in Figures 2.1 and 2.2 are the use cases themselves . An arrow from an actor to a use case identifies the actor as the stimulus that starts the use case or the recipient of information produced by the use case. You can also see that several of the use-case ovals are connected to other use cases by arrows and the text <<uses>> . A uses relationship allows you to indicate reuse of certain operations. You might also see this referred to as an includes relationship. For example, Figure 2.1 indicates that the "Close an Auction" use case defines operations that are needed by both "Cancel an Auction" and "Assign a Winner." Similarly, Figure 2.2 shows that "Browse Auctions" is an activity directly requested by the Bidder actor and also a required part of the "Bid on an Auction" use case. Also notice that "View Auction Detail" is separated out from "Browse Auctions." This isn't strictly necessary because this functionality isn't reused, but sometimes splitting out part of a task this way makes the requirements more clear.

Note

Although not needed in the use cases shown in this chapter, UML also supports the concept of an extends relationship between two use cases. This relationship allows you to show that a variation exists for a use case that is performed when a certain condition occurs. For example, an online ordering site might have a "Submit Order" use case that is extended by a "Submit Order for New Customer" use case. The second use case would likely perform all the operations done by the first, but might also add the processing of a first-time customer survey or a credit check.

A use-case diagram identifies the use cases to be supported by a system and the actors that interact with them, but it doesn't provide any explanation of what the actual operations are. A narrative description of a use case is where you get the actual meat. The rest of this section describes the details of each of the use cases to be implemented by the auction example. Again, the intent is only to give you enough detail to follow the example as it is built throughout the book. With that as a guideline, the use cases are presented using a simple narrative that cuts right to the chase.

Create an Auction

A Maintenance User must be able to define an auction to be held on the site. This includes assigning the item to be sold and defining the parameters that determine how the auction is to be run. In particular, the user must define the starting bid, minimum bid increment, reserve amount (optional), start time, and scheduled end time for an auction. The system must provide the user with an interface for defining this information and must store it so that the site can execute the auction.

Cancel an Auction

A Maintenance User must be able to cancel an auction that either has not started or has started but has not had a winner assigned. The Auction Timer must be able to cancel an auction whose time limit has expired without a winner being declared. No winner should be assigned if either no bids were submitted or no bid that exceeded the auction's reserve amount was submitted.

Assign a Winner

A Maintenance User must be able to select a bid submitted for an active auction and assign the corresponding bidder as the auction winner. The Auction Timer must be able to assign the leading bidder as an auction winner when an auction expires and the leading bid exceeds the reserve amount (if one is defined). When an auction winner is assigned, the system must update the auction status and notify the winner.

Close an Auction

This use case defines functionality shared by "Cancel an Auction" and "Assign a Winner." When an auction is closed, the system shall no longer accept bid submissions. If the closed auction had already started, the system shall set the actual end time of the auction to the time at which it was closed.

View Auctions

A Maintenance User must be able to view a list of auctions defined within the system. The system shall display each auction by name , status, starting bid amount, reserve amount, current leading bid, and time remaining. The user shall have the option to sort the auctions by name, status, or time remaining.

View Bid History

A Maintenance User must be able to view the bids submitted for a particular auction. When the user selects this option for an auction, the system shall display each bid for the auction sorted in descending order of the submission time. The information for each bid shall include the bidder's name, the bid amount, and the submission date and time.

Browse Auctions

A bidder must be able to browse a list of auctions that are currently active or have been started and subsequently closed. This list shall include an entry for each auction that consists of the auction name, status, current leading bid, minimum next bid, and time remaining.

View Auction Detail

A bidder must be able to view the detailed information for an auction. When the user selects an auction from the auction list provided by the "Browse Auctions" use case, the system shall display the auction detail. The detail display shall include the information shown in the auction list plus the auction description and the name, description, and image of the item being auctioned.

Bid on an Auction

A bidder must be able to submit a bid for an active auction. The system shall allow the user to enter and submit a bid price from either the auction list or auction detail display. The system shall only accept bids for auctions that have started but not yet expired. The system shall only accept bids that are greater than or equal to the required next bid amount. The required next bid shall be the starting bid amount until the first bid has been submitted. After the first bid has been submitted, the required next bid shall be the amount of the current leading bid plus the minimum bid increment for the auction.

View Account History

A bidder must be able to view an account history that shows all auctions bid on by the Bidder. The system shall display a list of auctions that includes the auction name, status, current leading bid, time remaining, and the user's bid status. The user's bid status shall be indicated as one of Leader, Trailer, Winner, or Non-Winner (to be polite).