This is the fourth installment of a multiple-part article (as outlined below) that demonstrates using Rational's tools in a distributed, J2EE-based project.
- Part 1: project introduction; high-level planning
- Part 2: detailed planning; risk management; requirements management
- Part 3: Rational Rose model creation and access control; requirements analysis
- Part 4: use-case refinement; report generation; tool and technology selection
- Part 5: architecture and design
- Part 6: detailed design; early development; round-trip engineering; early unit tests
- Part 7: continued development; early builds; demonstrations
- Part 8: strategies for unit testing; function tests; GUI test scripts
- Part 9: system builds and testing; defect tracking; product acceptance
- Part 10: project results; conclusions; future work
The fictional premise of the article is that we're a software company, Lookoff Technologies Incorporated, and our customer, Audiophile Speaker Design, Inc. (ASDI), has hired us to meet their burgeoning IT requirements. For a more detailed introduction to the project, see Part 1.
This Part 4 installment covers our movement forward in the elaboration phase of the ASDI project, particularly in the areas of use-case analysis (refining our use cases to add traceability to the statement of work (SOW), and standardizing and generating use-case documentation) and selection of tools and technologies.
| Part 4 Snapshot |
|
Tools and technologies demonstrated in Part 4:
Artifacts created or updated:
|
Refining and Documenting the Use Cases
Figure 1 shows the evolution of use cases during Phase 1 (the RUP inception and elaboration phases) of the ASDI project. As discussed in Part 3, we created business use cases during the inception phase and then moved toward use cases for the "as is" system at the beginning of the elaboration phase. Now we were in the thick of the elaboration phase (the upper right in Figure 1) and were ready to refine our use cases, completing their translation into detailed requirements for the system. This evolution was natural, since there was no sense fleshing out the details of use cases until we figured out whether we'd defined the right use cases to begin with. Once the detailed system requirements were completed, we'd pass them by ASDI as a formal deliverable.
|
| Figure 1: Use-case evolution during Phase 1 |
| (click here to enlarge) |
Standardizing Use-Case Documentation
We'd taken notes during meetings at which we'd informally reviewed the use cases with ASDI. The use-case diagrams and packages had also been reviewed periodically by our senior team members, a "sanity check" that resulted in the following:
- feedback to the team lead on weak or missing areas
- useful analysis ideas, patterns, and areas for factoring out functionality
- a consistent view of the system
- communication of the detailed requirements to the engineering team
Our focus now was on recording what we'd learned. We reached an agreement with ASDI on what form the use-case documentation would take, and we were happy they were willing to have textual documentation of each use case directly within the Rational Rose model. This made things a lot easier for us, since it meant lower expectations for document aesthetics.
With multiple team members contributing, we found a need to standardize the documentation associated with each use case. Consequently, we drafted a use-case documentation template that would be applied to each use case within the Rose model. The content shown in Figure 2 was pasted into each use case's documentation window to serve as a template. Note that we used the term "variation" in this template as shorthand for the RUP concept of alternate flow.
|
| Figure 2: Use-case documentation template |
Later on in the project, we realized that having a significant amount of documentation within the model bloated the ASCII "petal" (*.mdl and *.cat) files, slowing down model loads. Thanks to fast computers, this side effect was tolerable, but in later projects we used a more formal method for maintaining use-case contents, in the form of a customized interface (as discussed in the article "Fine Tuning Rose to Complement Your Process"). Another option would have been to use Rose's feature of attaching individual Microsoft Word documents to use cases (by right-clicking the use case and choosing New > File from the context menu).
ASDI's original expectations were that the SOW would grow into a large textual document. Our ongoing discussions with them were finally softening that stance, as they came to appreciate the inefficiencies of such an approach for a vaguely defined system. They were seeing good progress with the use cases and had quickly grasped the related concepts, to the point where they were giving very strong and appropriate feedback without requiring model walkthroughs. However, a good deal of time and energy had gone into the SOW, and ASDI understandably wanted to be sure we weren't missing any ideas that had been captured in it.
To provide this assurance, we used Rational's tools to set up traceability between the SOW requirements and our fairly stable set of use cases. First we associated the Rose model with a requirements document managed by RequisitePro, by choosing Tools > Rational RequisitePro > Associate Model to Project and selecting the SOW. We then mapped each use case to the main SOW requirement it corresponded to, by right-clicking the use case and choosing Requirement Properties > New from the context menu. As shown in Figure 3, we were presented with a list of SOW requirements, from which we selected the appropriate one.
|
| Figure 3: Associating a requirement with a use case |
| (click here to enlarge) |
Having set up these associations in our model, we could trace requirements to use cases and vice versa. It was important that the traceability be bidirectional so that we could find both missed and added requirements. Missing a requirement was unacceptable, and tracing requirements to use cases enabled us to easily detect any we'd missed. Adding requirements without clear justification constituted scope creep and could have a negative impact on our schedule and budget. To prevent that, we traced all use cases to either existing SOW requirements or change requests.
Unlike tracing requirements to use cases, tracing in the reverse direction is often overlooked, but we accomplished this easily in Rose. To view the SOW requirement a use case was associated with, we simply right-clicked the use case in the Rose model and chose View RequisitePro Association from the context menu. This brought up a window indicating which SOW requirement the selected use case traced back to, as shown in Figure 4. If the use case didn't map to a SOW requirement, the bottom two fields showed "NONE." We could also have created a more complex tracing report using Rational SoDA.
|
| Figure 4: SOW requirement for a use case as reported by Rose |
| (click here to enlarge) |
It's important to note that we took a shortcut in this approach. With the method we used, we could associate each use case with only one requirement and vice versa; however, a use case could actually trace back to several requirements, and a requirement could result in multiple use cases. We didn't bother mapping this many-to-many relationship. We associated use cases directly back to the requirements in the SOW, but a better method would be to introduce a use-case specification document, managed by RequisitePro, which contains the bulk of the use-case requirements text and enables a many-to-many mapping. (Details can be found in the Rational whitepaper "Use Case Management with Rational Rose and Rational RequisitePro.") We now feel that the use-case specification document is an important step that we shouldn't have skipped.
Use-Case Documentation Review Cycle
Both we and ASDI were aware that document review cycles frequently become endless and circular rather than focused and convergent. Closing off any document is difficult, since reviewers often come up with new ideas every time they read the document. In an iterative approach, the same challenge of "When are we finished?" arises with documentation as with software and other tasks. To address ASDI's concerns regarding closure, we outlined what our review cycle would be for the use-case documentation, borrowing heavily from concepts described in the RUP (see Figure 5).
|
| Figure 5: Document review cycle diagram |
| (click here to enlarge) |
As you can see, each of our documents would go through a number of iterations. It was important for us to find a tool to support this, and we found such a tool in Rational SoDA, which allowed us to generate documentation out of the Rose model. Although it was tempting to make changes directly to the documents, that posed the risk of having the documents be out of sync with the model. If you're going to invest in one or the other, it's better to invest in the model. Except for the software user manuals you may develop, the model is the most likely artifact to continue to be referenced and maintained after the software is delivered.
With SoDA, report generation was simple. To generate use-case documentation for customer review, we chose SoDA Report from Rose's Report menu, which brought up a list of report templates as shown in Figure 6. From there we selected the template for a RUP use-case model survey.
|
| Figure 6: SoDA report options |
| (click here to enlarge) |
Each template provides a default report (as a Microsoft Word document) with empty sections and a corresponding table of contents (TOC). Figure 7 shows the TOC for the report we selected. We started out by reviewing just the TOC with ASDI, and we looked at our use cases to decide whether anything in the report needed to be tailored to suit our needs.
|
| Figure 7: SoDA use-case survey report (TOC) |
| (click here to enlarge) |
You may wonder why we bothered to review the TOC with ASDI before writing any of the actual content. We found that this was an important step. Sometimes ASDI gave us a DID (data item description) that provided a TOC for formal deliverables, but if not, we found it useful to get buy-in from them (or from internal team reviewers) on the TOC before starting to flesh out the contents. Sometimes we'd fill in lower-level section headings that showed how we were going to elaborate on each section, but there was rarely any paragraph content in the first TOC review.
Later article parts will discuss Rational SoDA and template customization in more detail.
Elaboration: Not Just Use Cases
To make life a little more difficult, ASDI was expecting us to wrap up the use-case documentation before we proceeded with follow-on tasks. We had to remind them that the use-case documentation wouldn't be "finished" until the software was delivered, unless they didn't want us to update the use cases as requirements changed or emerged. We were able to convince them that they weren't interested in a completion milestone so much as a confidence milestone. Nevertheless, they wanted to put a check mark next to the to-do item "detailed use-case document" once it was sufficiently mature, and we agreed that made sense.
The real challenge was to convince ASDI of the need for activities to occur in parallel rather than to have all milestones be sequential. We identified this as a general concern early on in the project, yet it still had not been fully resolved. To fit in some activities alongside use-case analysis, we pitched these two arguments:
- Screen mockups would simplify requirements review and tell a broader story than use cases could achieve on their own.
- Tools procurement, installation, and training could not take place without some up-front prototyping.
We were pleased that ASDI agreed to mockups and prototypes as useful parts of the analysis stage. This enabled us to dive into architectural and tool issues before use-case analysis was completed.
Choosing Tools and Technologies
Tool and technology selection is never a trivial task, although it's frequently rushed. Teams often base their choices on startup costs, "gadget factor," curiosity, or loyalty, when instead they should consider production costs, reliability, available training, team skills, and feature compliance. Adding some formality into the evaluation process can ensure that tool selection is based on project needs rather than subjective criteria.
Formal Off-the-Shelf Evaluation
An area that's only lightly addressed in the RUP is the process by which teams pick off-the-shelf (OTS) -- also called commercial off-the-shelf (COTS) -- tools. One place where some thought has gone into this process is at Carnegie Mellon's Software Engineering Institute (SEI), which has a COTS-Based Systems Initiative that focuses on strategies for selection and adoption of COTS products. Of particular interest is SEI's product feature checklist; although it focuses more on selecting components and frameworks for software systems, many of the principles also apply to selecting development tools, Web servers, databases, and so on.
ASDI presented us with these criteria that they felt should influence our tool selections:
- Their core development and maintenance team that would eventually take over the system would consist of 3 to 5 people.
- The system would be accessed by 4 to 7 in-house users and by 1 to 5 outside users from each of 20 to 30 companies (although a future version of the system could support thousands of online users).
- Cross-platform technology was important, because ASDI expected to stick with this system for many years.
- Training had to be readily available for all technologies.
- They strongly preferred Java-based solutions.
- They preferred an OODB (object-oriented database) for the data store.
- The system would run on Linux in its early versions, although it could later run on Solaris.
- Developers needed to be able to work effectively with the software from Windows NT/2000 machines.
- Performance wouldn't pose a significant challenge because only a few users would be interacting with the system at any one time.
We had some experience with J2EE-based application servers, so it was fortunate that ASDI was interested in a Java-based solution. We nevertheless quickly assessed competing technologies (primarily Microsoft .NET/DNA) after ruling out entry-level Web solutions such as Perl/CGI and PHP.
We consistently found the Orion Application Server to be the friendliest and most cost-effective development environment. The only place where Orion scored low was on vendor stability and support. The company that produces Orion is quite small and simply doesn't carry the same horsepower and credibility as BEA's WebLogic or IBM's WebSphere. However, after discussions and reviews with ASDI, we mutually agreed that the benefit of Orion's J2EE compliance was sufficient to offset this risk. Careful development would ensure we'd have portable code that could migrate to other application server solutions if needed during Phase 2 development. So we went with Orion -- which meant that startup costs were nil, because Orion could be used at no cost.
Orion comes with a high-speed built-in Web server, so the Web server selection process was concluded once Orion was selected. Its primary competitor was Apache. However, benchmarks on Orion's site showed that Orion met and surpassed Apache specifications for certain tests. (Our own benchmark tests confirmed these findings, although our tests weren't overly rigorous.)
The choice of which database to use wasn't an obvious one. The database wouldn't perform at high load very often (if at all), but it needed to have rich feature support. For instance, complex data relationships would require full referential integrity enforcement. Also, the system had to run around the clock, so we wanted hot standby, replication, and other availability and fault tolerance features. Whether we'd use all of these features would be decided later.
We felt that PostgreSQL was the only reasonable open-source candidate. It had good ANSI SQL support, referential integrity, and good performance as long as the number of concurrent accesses didn't grow too large. However, the data store would require more committed support from a vendor than we could find for this database. Furthermore, we felt that PostgreSQL's online support (such as user community discussions) was insufficient for our needs. MySQL was actually a more popular open-source database, but it lacked too many features (for example, foreign keys).
We then turned to the major database players: DB2, Oracle, and Microsoft SQL. We had a fair amount of expertise with Oracle, but the new power units pricing model was too expensive for this application. Oracle essentially charges per MHz per CPU, meaning ASDI would have to bear high production environment costs for the system unless they were willing to install it on a P-133. Microsoft SQL was ruled out because of its proprietary platform dependency. If we were building a DNA-based solution, Microsoft SQL would have been an obvious choice, but it was a much less compelling option for J2EE.
In the end, we went with DB2. Our investigations confirmed that DB2 came with excellent SQL support, strong fault tolerance features, a fair pricing model, and a growing and educated set of online users. IBM's JDBC drivers for DB2 were strong performers, and their personal edition could be used at no cost to the development team. Unfortunately, our lack of knowledge about DB2 meant some training and ramp-up would be required during the prototyping activities.
You may be wondering what happened to the OODB option that ASDI had preferred. After running through prototypes and researching the products, we quickly came to the conclusion that the potential benefits didn't outweigh the risks inherent in using an OODB. For more thoughts about this, see the articles listed under "References and Other Resources."
Integrated Development Environment (IDE) Selection
At this point, we didn't want to commit to any high-end IDEs, for a variety of reasons:
- We weren't convinced that the Phase 1 proof of concept needed to incorporate Enterprise JavaBeans.
- An IDE investment could be expensive.
- The team members already had their own preferences, which were not for an IDE.
- Because Phase 1 was on a tight timeline, the learning curve associated with an IDE such as IBM's VisualAge wasn't something we wanted to tackle.
Instead, we used a mix of the following:
- JCreator -- a low-cost Java-based IDE
- CodeGuide -- a low-cost Java-based IDE
- log4j -- a logging tool that simplifies server-side debugging
- Jikes -- a fast and very strict Java compiler
Naturally, these would be supplemented with Rational's tools for testing, profiling, and code coverage.
During this stage we saw our use cases evolve (through traceability and documentation) and, by getting ASDI involved in use-case reviews, we quickly found ourselves with free subject-matter experts (SMEs). This was always one of the biggest challenges on any software project, so establishing this relationship early and effectively was a real win. Our relationship with ASDI in general was going very well. They were quickly grasping and approving a RUP-based process without much effort on our part. This was surprising, given their preference for waterfall-style development coming into this contract. Many of the iterative and incremental approaches encouraged by the RUP had good justification, and ASDI was seeing the benefits.
We were lucky that tool selection was fairly straightforward and could be accomplished this early in the project. Some of the Rational tools we'd decided to use were already saving us time. On previous projects we'd used Excel to manage requirements, but we found Rational RequisitePro to be a much more elegant and integrated solution. Furthermore, Rational SoDA's reports were significantly reducing our document-generation costs. Since this project was our first exposure to SoDA, we were glad ASDI was pleased with the standard SoDA templates.
Until now, we'd focused on requirements-related artifacts, and had spent a relatively small amount of time on evaluating technologies and creating prototypes to support tool selection. Now it was important for us to explore the more complex areas of the system by creating more challenging prototypes and starting to use the tools in actual development. Would we use XML, and if so, which XML parser? What security mechanisms did we require? Should we incorporate Enterprise JavaBeans? Questions like these would have to be answered soon.
In other words, it was time to shift from analysis into architecture and design -- and sooner rather than later, since most of the technical risks would crop up over the next few weeks. We had a good functional baseline consisting of a number of well-defined use cases. It was important for us to avoid analysis paralysis and maintain momentum going forward.
No new risks were identified; in fact, our risk list was now shorter than ever. Since ASDI had agreed that an OODB wouldn't be prudent for this project, we no longer had that technical risk to manage. They were also easing up on requiring formality and a preconceived structure in our deliverables, and they were approving documentation based on the RUP framework without reservations.
While concerned about the remaining schedule and effort, we were feeling much more comfortable with the budget as a result of our increased understanding of the required functionality and familiarity with the technologies. Further technical exploration would undoubtedly uncover new challenges.
References and Other Resources
- "Fine Tuning Rose to Complement Your Process" by Steve Franklin (Rose Architect, Winter 2000)
- "Use Case Management with Rational Rose and Rational RequisitePro" by Rational Software (Rational whitepaper)
Steven Franklin has an extensive background in software design, architecture, and engineering process, which he usually applies to large, distributed information management and command and control systems. He's been using Rational tools since 1997, and his primary areas of interest include XML, J2EE, wireless, and software engineering methodologies. Steven can be reached via e-mail.
Comments (Undergoing maintenance)
Table of contents
Next steps from IBM
Rational Application Developer features provide the comprehensive Integrated Development Environment (IDE) used to develop J2EE applications requiring Servlets and JavaServer Pages (JSPs).
- Try: Try the free Rational Application Developer, which helps developers quickly design, develop, test, analyze, and deploy high-quality Java, Javaserver pages, and J2EE applications.
- Article: Learn how you can deliver accurate, higher-quality J2EE apps with Rational Application Developer, open source JUnit and JUnitEE test frameworks.
- Tutorial: Build a Facebook application using PHP, the Spring framework, and J2EE.
- Buy: Rational Application Developer
My developerWorks community
Tags
Use the slider bar to see more or fewer tags.
Popular tags shows the top tags for this particular content zone (for example, Java technology, Linux, WebSphere).
My tags shows your tags for this particular content zone (for example, Java technology, Linux, WebSphere).
Popular article tags |
My article tagsSkip to tags list
Popular article tags |
My article tags
