IBM Rational Architecture Management Software model structure guidelines: Part 2. Classic Rational Unified Process

This article is for those who are interested in applying the modeling guidance found in the traditional IBM® Rational Unified Process® (RUP®) to their use of IBM® Rational® Software Modeler, IBM® Rational® Systems Developer, or IBM® Rational® Software Architect. You will learn how these products support the model types defined by RUP; the implications of RUP modeling style for model organization and team modeling; what is worth modeling; and the business value, organization, and content of the RUP Use Case, Analysis, and Design Models.

Bill Smith (smithtw@us.ibm.com), Rational Product Manager, Model-Driven Development, IBM, Software Group

Bill Smith is a product manager for the Architecture Management product line within IBM Rational. He has been active in software development and modeling for 25 years, the past seven with Rational.



22 January 2008

Also available in Chinese Russian

About this article

This article describes how to represent the IBM® Rational Unified Process® (RUP® model artifacts in IBM® Rational® Software Modeler, IBM® Rational® Systems Developer, or IBM® Rational® Software Architect (hereafter referred to collectively as "the products under discussion" or simply "the software"). It also offers guidelines for the internal organizational structures of a subset of those artifacts. To help you understand which artifacts you to invest in, it attempts to explain the specific business values of each product, but it does not attempt to:

  • Restate the conceptual underpinnings of the artifacts
  • Provide extensive descriptions of them
  • Describe the processes or techniques for specifying their detailed semantic or diagrammatic contents

The sections in this article cover these topics:

  • How the products under discussion support the model types defined by RUP
  • The implications of RUP modeling style for model organization and team modeling
  • What is worth modeling
  • The business value, organization, and content of these three RUP models:
    • Use-Case Model (solution)
    • Analysis Model (solution)
    • Design Model

Intended readers

This article (Part 2 of a series) is for those who are interested in applying the modeling guidance found in the classic Rational Unified Process to their use of the products under discussion.

Note:
This RUP-oriented, use case-driven approach to model organization is not the only useful one. Model structure guidelines are also under development for a business-driven development for SOA (service-oriented architecture) style of model organization, sometimes referred to as BDD4SOA, and for Model Driven Systems Development (RUP for MDSD).

Classic RUP model structure guidelines

When IBM acquired Rational Software several years ago, it began the process of aligning RUP with other IBM process frameworks, as well as extending RUP with guidance regarding emerging concerns such as SOA and business process modeling. Before that, the modeling guidance that was provided by the Rational Unified Process (and elaborated upon in books by Terry Quatrani, Jim Conallen, Eric Naiburg, Robert Maksimchuck, and others) had remained fairly static for some time. That guidance describes a set of models such as use-case models, analysis models, and design models that represent well-defined perspectives on the problem and solution domains of systems. That approach is biased toward a process in which use cases are the first modeling artifacts created and where nearly any type of technical architecture might be used. The utility of this set of models has been proven in many real-world projects. We now refer to this modeling approach and style as "generic" or "classic" RUP modeling guidance.


How to realize RUP model types in the Rational Eclipse-based UML modeling tools

In RUP, models are of specific types, such as a UML use-case model, UML analysis model, or data model. The products under discussion do not actually assign types to UML models. Therefore, the mapping of RUP model types into these products is primarily a matter of usage conventions, such as these examples:

  • How you name your model/LUs
  • The profiles that you apply to them
  • The content that you create within them

The products under discussion include a few model templates that you can use when you create model/LUs. Some of these templates suggest a particular model type and model organization approach that conforms to RUP. You encounter these templates when you create new model/LUs, and you can base new models on the templates.

Figure 1 depicts pages of the new model wizard. On the left, you can see some of the standard templates. On the right, you can see that it is also possible to use a model of your own design as a template or starting point.

Figure 1. The New UML Model wizard
The New UML Model wizard

Table 1 shows the commonly used RUP model types and how they can be realized in the products under discussion. Information that follows in this article assumes that you use these mappings and the approaches described hereafter.

Note:
The guidelines for internal organization of the Use-Case, Analysis, and IT Design Models that are presented in the later sections of this article correspond to the organizational structures defined within the standard model templates that are provided by the products under discussion. By no means do these templates represent the only way of organizing such models. Many factors should be considered when deciding how to organize the logical content of your models.

Table 1. Commonly used types of RUP models
RUP modelWays to realize it with the products under discussion
Business Use Case Model Model/LU based on standard Blank Model template, with Business Modeling profile applied. Restrict content per RUP business use-case model guidance

Model/LU based on a user-defined model with Business Modeling profile applied. Restrict content according to RUP business use-case model guidance
Business Object Model Model/LU based on standard Blank Model template, with Business Modeling profile applied. Restrict content according to RUP Business Object model guidance

Model/LU based on a user-defined model with Business Modeling profile applied. Restrict content according to RUP Business Object model guidance
(Solution) Use-Case Model Model/LU based on standard Use-Case Model template. Restrict content according to RUP Use-Case Model guidance.

Model/LU based on user-defined model. Restrict content according to RUP Use-Case Model guidance.

Model/LU based on standard Blank Model template. Restrict content according to RUP Use-Case Model guidance.
(Solution) Analysis Model Model/LU based on standard Analysis Model template. Restrict content according to RUP Analysis Model guidance.

Model/LU based on user-defined model. Restrict content according to RUP Analysis Model guidance.

Model/LU based on standard Blank Model template. Restrict content according to RUP Analysis Model guidance.

Model/LU based on standard Enterprise IT Design Model template. Use <<analysis>>; packages to contain analysis-level content restricted according to RUP Analysis Model guidance.
User Experience Model Model/LU based on standard Blank Model template. Restrict model according to guidance provided with the RUP User Experience Modeling configuration (included in IBM® Rational® Method Composer configuration).

Use the Web Diagram Editor or Java™ Visual Editor in IBM® Rational® Software Architect or IBM® Rational® Application Developer.
Design ModelFor IT: Model/LU based on standard Enterprise IT Design Model template. Restrict content according to RUP Design Model guidance.

For IT or systems: Model/LU based on standard Blank Model template. Restrict content according to RUP Design Model guidance.

For IT or systems: Model/LU based on user-defined model. Restrict content according to RUP Design Model guidance.
Implementation Model Not supported with UML. Use 3GL-specific Code Modeling capability.

Use a UML Design Model, but generate code using a transformation with the "Replace UML elements" option, so that the design model becomes a mixed model, reflecting implementation-level content.
Deployment Model Model/LU based on user-defined model. Restrict content according to RUP Deployment model guidance.

Model based on standard Blank Model template. Restrict content according to RUP Deployment model guidance.
Data Model Use logical and physical data models as supported by IBM® Rational® Data Architect.

Organizing RUP models

In Part 1, we described the concerns of team modeling and the principles of strong architecture and strong ownership. Those principles remain paramount when using a RUP modeling style, but the RUP style introduces some orthogonal concerns that you must deal with, too.

Resorting once again to the use of code bases to illustrate the point, let us consider a three-tiered application architecture. You might partition such a code base into strongly owned modules, based solely upon considerations of application functionality. This is essentially the approach reflected in Figure 1, where the solution is broken down into common utilities and services, applications, and modules of applications.

However, this is not the only way of partitioning, and it may not support strong ownership where developers have specialized skill sets. For instance, it may also be advisable to further partition the application modules according to which artifacts correspond to which tiers of the three-tiered architecture. (As a practical matter, when developers specialize in client-side vs. server-side development, ownership may come to depend more upon tier than upon application functionality, yet the principle of strong architecture would still say that you must pay attention to both concerns when partitioning).

RUP introduces a similar set of concerns regarding model organization, but the various RUP model artifacts do not correspond to the tiers of a solution architecture. Instead, they correspond to the different levels of abstraction that you might need to represent as you progress through development. It turns out that the OMG Model-Driven Architectures (MDA) initiative suggests a similar stratification of models at different levels of abstraction. Table 2 shows a rough comparison of the RUP and MDA approaches.

Table 2. Comparison of RUP model types to MDA model types
RUP model typesMDA model typesPurpose and comments
Business Use-Case Model Business Analysis ModelCIM To show business-driven requirements and compute-independent representations of solutions.
Solution Use-Case Model Solution Analysis Model User Experience model Logical Data modelPIMTo show compute-dependent but platform-independent solution requirements and representations of solutions.
Solution Design ModelPIM or PSMTo show either a platform-independent representation of solution design or a representation that is marked with some platform-specific concerns. The solution Design Model might evolve from PIM to PSM in situ.
Implementation model Physical Data model Deployment model PSMTo introduce platform-specific concerns to the solution design.

Just as the people who develop implementation code might specialize in client-side or server-side development, those who develop models might specialize in business requirements analysis, solution requirements engineering, solution analysis, solution design, information design, and so forth. Yet when working at the detailed design level of abstraction, there may be a strong need to align the organization of design models to the organization of code bases (particularly if code generation is being used). Table 3 suggests how you might prioritize various concerns when planning a model partitioning strategy for a RUP modeling practice.

Table 3. Model content ownership strategies
For these RUP model types Base ownership strategy on these concerns
Business Use-Case Model Business Analysis Model Segregation of shared and common content

Skills specialization

Business-oriented organizational breakdown of the problem space (departments, workflows, strategic initiatives, for example)
Solution Use-Case Model Solution Analysis Model User Experience Model Domain Model (also called Reference Information Model or Logical Data Model Segregation of shared and common content

Skills specialization

Solution-oriented breakdown of the functionality (applications, workflows, modules, and so forth)
Solution Design Model Physical Data Model Implementation Model Segregation of shared and common content

After that, it depends:
  • For teams of developers with multiple skills, focus on breakdown of functionality plus principles of strong cohesion and loose coupling.
  • For teams of developers with specialized skills, it may be necessary to focus first on architectural layers, targeted implementation technologies, and so forth, thus making good functional decomposition a secondary ownership consideration (yet still a primary architectural consideration). In the products under discussion, unlike earlier Rational modeling products, the implementation model consists of a code base and diagrams of the code.
Deployment Model Alignment with Design Model

Alignment with ownership of infrastructure assets (machines, networks, and so on)

Yet another concern is volatility, which is usually a function of where you are in a development plan. Especially in the early iterations of "green field" development projects, you are likely to do frequent refactoring as you work through the process of understanding how things should be named and what the best functional groupings are.

In a RUP-oriented modeling process, there tends to be a very strong relationship between the organization of Use-Case Models and analysis models (at least in the early in the process), because RUP suggests a fairly mechanical process for populating the content of an Analysis Model based upon the content of a Use-Case model. Thus, you use these to seed the Analysis Model:

  • A <<Use-Case Realization>> Collaboration (that owns one or more Interactions) and a <<Control>> class for each use case
  • A <<Boundary>> class for each use case and Actor relationship
  • Any number of <<Entity>> classes derived, perhaps, from an analysis of the nouns in use-case descriptions, or perhaps, instead, from development of a Domain Model

Advantages: This suggests keeping the analysis content in the same packages with the use cases (which implies that they reside within the same model) for these reasons, for example:

  • This can make it easier to complete certain use-case refactoring tasks (such as renaming packages or regrouping use cases)
  • This can make it easier to see how analysis content might need to change to reflect other kinds of use-case refactoring (for instance, it is easier to see when the name of a use-case realization [UML Collaboration] or <<Control>> class should be changed to reflect that a use case was renamed).

Tradeoff: This does not lend itself to strong ownership of use cases by a business analyst plus strong ownership of analysis content by a systems analyst or software architect. Therefore, you might decide to collocate the use cases and analysis content through a couple of iterations until things stabilize, and then refactor the analysis content into its own Model/LU (with a package structure that mirrors that of the Use-Case Model) to accommodate stronger ownership by the software architect. Then later, you might move the analysis content into its own Model/LU with a package structure that mirrors that of the use case content.

Advantages and tradeoffs of the RUP models

In Part 1, we gave this advice: "The best modeling guidance of all is model something only if doing so has recognized business value." As you have seen in this article, RUP proposes quite a number of different types of models that represent different aspects and levels of abstraction of a problem domain and proposed solution. These are proposed by RUP because they have been proven to add value in at least some situations. The question is: "Does each add value in every situation?" The answer is: "No."

The follow-on question is: "How do I know if one will be valuable in my situation?" The answer cannot be predicted with certainty. Although it is not in the scope of this article to discuss either the value of modeling in general or the value of each RUP model in detail, we will attempt to shed light on when a RUP model type should be used. Table 4 suggests what some of the potential value points are for each RUP model type, some of the costs of their creation and maintenance, and what you could use instead. Generally, the statements of added value are straightforward, but it's important to consider that traceability represents potential business value in at least two different ways::

  • Compliance
  • Impact analysis
Table 4. Advantages, tradeoffs, and alternatives of various RUP models
RUP model typeAdvantages, tradeoffs, and alternatives
Business Use-Case ModelAdvantages:
  • Better understanding of business problems, requirements, and potential for improvement
  • Effective communication of business problems and potential solutions to stakeholders within and across lines of business
  • Possibly, downstream traceability (for example, to repository-based requirements or Business Analysis Model or both)

Tradeoffs:

  • Development and maintenance of model
  • Possibly, synchronization of Business Use-Case Model content to downstream requirements and models
  • Possibly, creation and maintenance of downstream traceability linkages

Alternatives:

  • Business documents (reports, presentations)
  • Business Process models
Business Analysis ModelAdvantages:
  • Better understanding of requirements, characteristics, and costs of business solutions
  • Possibly, downstream traceability (to repository-based requirements and Solution Use-Case Model)

Tradeoffs:

  • Development and maintenance of model
  • Possibly, synchronization of Business Analysis Model to upstream and downstream requirements and models
  • Possibly, creation and maintenance of traceability linkages

Alternatives:

  • Business documents (reports, presentations)
  • Business Process Models
Solution Use-Case ModelAdvantages:
  • Better understanding of solution requirements
  • Effective communication of solution scope and requirements to project stakeholders
  • Possibly, upstream traceability (to repository-based requirements or Business Analysis Model, for example)
  • Possibly, lateral traceability to other models and artifacts (User Experience models, prototype code, test cases) Possibly, downstream traceability to other models (including code)
  • Possibly, automated generation of downstream model content (involves custom tooling development)
  • Possibly, automated generation of test case outlines

Tradeoffs:

  • Development and maintenance of model
  • Possibly, synchronization of Solution Use-Case Model content with upstream (Business Analysis, for example) and downstream models (such as Solution Analysis Model)
  • Possibly, creation and maintenance of upstream and downstream or lateral traceability linkages
  • Possibly, custom tooling development

Alternatives:

  • Specification documents
  • Prototypes
Solution Analysis ModelAdvantages:
  • Better understanding of solution requirements and characteristics leading to better architectural choices before committing to code
  • Possibly, upstream traceability (to Solution Use-Case Model, for example)
  • Possibly, downstream traceability to other models (including code)
  • Possibly, automated generation of downstream model content (involves custom tooling development); alternatively, evolves into Design Model

Tradeoffs:

  • Development and maintenance of model
  • Possibly, synchronization to upstream (Solution Use-case model, for example) and downstream (such as Design Model or Implementation model)
  • Possibly, creation and maintenance of upstream and downstream traceability linkages
  • Possibly, custom tooling development

Alternatives:

  • Spec documents
  • Prototypes
User Experience ModelAdvantages:
  • Better understanding of solution requirements
  • Effective communication of solution scope, requirements, and user experience characteristics to project stakeholders
  • Possibly upstream traceability (for example, to repository-based requirements and/or Business Analysis Model)
  • Possibly lateral traceability to other models and artifacts (Use-Case or Solution Analysis Models, prototype code, test cases)
  • Possibly downstream traceability to other models (including code)
  • Possibly automated generation of downstream model content, including code (involves custom tooling development)
  • Possibly automated generation of test case outlines (involves custom tooling development)

Tradeoffs:

  • Design, development. and maintenance of UX modeling style and (likely) UML profile
  • Development and maintenance of UX model
  • Possibly synchronization of Solution Use-case model content to upstream (for example, Business Analysis) and downstream (for example, Solution Analysis) models
  • Possibly creation and maintenance of upstream and downstream and lateral traceability linkages
  • Possibly custom tooling development

Alternatives:

  • Spec documents
  • UX sketches (Rational business partner tools)
  • Prototypes
Domain Model (also called Reference Information model or Logical Data ModelAdvantages:
  • Better understanding of real-world business domain
  • Training aid for teach others about the business domain
  • Improve database designs
  • Possibly, downstream traceability (for example, to Solution Analysis or Design Models)
  • Possibly, seed downstream models, such as Solution Analysis or Design models (involves custom tooling development)
  • Possibly, seed Logical Data models (exiting tooling in Rational Data Architect) from domain models (or vice versa)
  • Effective communication of business problems and potential solutions to stakeholders within and across lines of business
  • Effective communication of information integration and alignment problems, supports data mastering efforts

Tradeoffs:

  • Development and maintenance of domain model
  • Possibly, synchronization of domain model to logical data models or downstream software models (Solution Analysis or Design)
  • Solution Use-Case Model content to upstream (Business Analysis, for example) and downstream models (such as Solution Analysis Model)
  • Possibly, creation and maintenance of upstream and downstream and lateral traceability linkages
  • Possibly, custom tooling development

Alternatives:

Spec documents

Solution Design ModelAdvantages:
  • Opportunity to describe and evaluate alternative design approaches without committing to code
  • Better understanding of solution requirements and characteristics leading to better architectural choices before committing to code
  • Possibly, upstream traceability (for example, to Solution Use-Case model or Solution Analysis Model)
  • Possibly, downstream traceability to code
  • Possibly, automated generation of code (using custom transformations or the standard transformations that are provided in the products under discussion)

Tradeoffs:

  • Development and maintenance of model
  • Possibly, synchronization to upstream models or requirements
  • Possibly, synchronization to code
  • Possibly, creation and maintenance of upstream and downstream traceability linkages
  • Possibly, custom tooling development

Alternatives:

  • Spec documents
  • Prototypes
  • Code models and code
Physical Data ModelAdvantages:

Diagrammatic modes of exploring and examining a solution implementation and help with understanding that implementation (of particular value in maintenance phases and as project members come and go)

Tradeoffs:

Maintenance of diagrams

Solution Implementation ModelAdvantages:

Diagrammatic modes of exploring and examining a solution implementation and help with understanding that implementation (of particular value in maintenance phases and as project members come and go)

Tradeoffs:

Maintenance of diagrams (although Browse diagrams can provide much of the value and require no maintenance)

Solution Deployment ModelAdvantages:

Aids understanding of requirements and costs to deploy solutions, which is useful in requirements, design, and implementation phases

Tradeoffs:

Maintenance of models

All model types Advantages:

More effective communication with a variety of project stakeholders

Basis for solution governance frameworks

Compliance-related documentation (particularly regarding traceability of refinements from requirements through implementations)


Guidelines for internal organization of a RUP Use-Case Model

The products under discussion provide the option to create a new model/LU based upon a Use-Case Model templates. (You can also create your own model/LU for use as templates.)

Standard Use-Case Model template

These templates may define a specific subset of UML capabilities that are typically used when doing use-case modeling (in other words, when working with models based upon the template, the drawing palettes and drop-down menus would only contain those UML elements commonly used by someone who is focused on use-case modeling). The templates also contribute a set of default content, as depicted in Figure 2. It is beyond the scope of this article to explain how the Use-Case Building Blocks content and search strings are used, but notes included in the templates provide these instructions.

Figure 2. Default content of Use Case Model Template as included in the products under discussion
Default content of Use Case Model Template

The template is biased toward logical partitioning of functionality as the technique that drives model organization. (This bias manifests as the use of the ${functional.area} package template as the primary building block of a Use-Case Model.) Figure 3 depicts a trivial example of the kind of Use-Case Model organization that is encouraged by this bias.

Figure 3. Example of Use Case model organized according to partitioning of functionality
Example of Use Case model organized according to partitioning of functionality

As discussed in the section on Organizing RUP models, this is not the only possible approach to logical partitioning. It was chosen for use with the template for these reasons:

  • It generally maps well to division of labor concerns when a team of people will be working on the Use Case model.
  • This approach has the best chance of yielding a Use-Case Model organization that will map well to Design and Implementation models when organizations adopt strong ownership of functional modules (although they may also reflect layering considerations, the organization of design and implementation models will most often also reflect functional decomposition and component concerns). This could prove particularly important if you expect to use transformations to seed each successive lower level of abstraction. If you will be generating seed content into an Analysis Model or Design Model based upon the Use-Case Model, having aligned packaging structures (or at least similar structures) in those models can simplify transformation development and configuration.

The template also suggests the use of these other organizational techniques:

  • Use of a top-level package to capture broadly empowered or versatile Actors (those who participate in a set of use cases that reside in multiple, functionally oriented packages)
  • Use of <<perspective>> packages to capture diagrams depicting views that cut across functional areas (but semantic elements of the model remain organized by functional area)

Rational XDE and Rational Rose migration

This use-case model organization guidance somewhat revises earlier RUP guidance, which was to create a top-level package for Actors and another for use cases. Then, as the size and complexity of the model demanded, you would use lower-level packages to establish functionally oriented groupings as shown in the XDE-based example shown in Figure 4.

Figure 4. XDE-based example (per sidebar)
XDE-based example (per sidebar)

Use-Case Model content

It beyond the scope of this article to provide a detailed tutorial on how to write good use cases or on the dos and don'ts of good use case modeling. However, what follows is a brief discussion of what could be included in a Use-Case Model in addition to the Actors and the use cases.

Recommended:Create a Main diagram at the model root that depicts the other packages of the model and supports drill-down into those packages and their respective Main diagrams.

Recommended: In each use-case package, include a diagram that depicts the package's use cases, any relationships among them, and the Actors that participate in them. If the number of cases is large, more than one diagram may be appropriate.

Recommended: Describe each use case's main and alternative flows in the Documentation field, as Figure 5 shows. (The formatting in the example was accomplished by creating the text template for a use case description using a rich text format (RTF) editor, and then copying and pasting the template into the use case Description field.)

Figure 5. Capturing use case flow descriptions in Documentation property of a Use Case
Capturing use case flow descriptions in Documentation property of a Use Case

Optional: When the complexity of a use case warrants it, add an Activity diagram and compose it to reflect the overall activity flows of the use case (see Figure 6). Rationale: This helps show the conditions that correspond to each of the flows (Main, Alternative, or Exceptional) and helps ensure that all of the various flows ultimately reconverge. (Semantically, adding an Activity diagram will result in addition of an Activity element owned by the Use-Case element, with the diagram under the activity).

Optional: Model a black box realization of each of the named flows (Main, Alternative, and Exceptional) of the use case:

  1. Add an Opaque Behavior to the use case and give it the name of the flow.
  2. Add to that a Sequence Diagram (semantically, adding a Sequence Diagram will result in addition of an Interaction element owned by the Opaque Behavior, with the diagram under the Interaction).
  3. Compose a Sequence Diagram (or a Communication diagram) for each interaction instance.

Rational XDE and Rational Rose migration

In UML 1, you would have used a Collaboration instance rather than Opaque Behavior for this purpose.

These Opaque Behavior instances should not be confused with analysis-level or design-level use-case realizations that we describe in following sections. The latter are white box realizations of the use case and describe interactions among the internal elements of a solution. The Opaque Behaviors proposed here (see Figure 6) are strictly black box interactions between Actors and the system. They give nontechnical stakeholders a high-level picture of how the users interact with the system. These Opaque Behaviors may help you identify the various views (screens or pages) that will be required as part of the implementation. They also formally establish the naming of the use case's various flows (scenarios) by assigning those names to semantic model elements (the Opaque Behaviors).

Figure 6. Example of Use Case that owns an Activity
Example of Use Case that owns an Activity

Optional: If you are following the RUP guidance to identify architecturally significant views of your architecture, and, especially, if you will be maintaining a Software Architecture Document, add a top-level <<perspective>> package to contain use-case diagrams that depict the architecturally significant use cases. You may want to name the package Use-Case View of Architecture. Alternatively, this is something that you could put in an Architecture Overview model.


Guidelines for internal organization of a RUP Analysis Model

An Analysis Model represents a first pass at a solution. It is a stepping stone to get from requirements to final design, focusing on capturing information about the business domain and showing candidate solution elements at a high level of abstraction that is close to the business. It is where analysis classes and analysis-level use-case realizations reside. It is through the process of modeling use-case realizations (primarily using Sequence Diagrams) that you begin to discover the actual design classes that you need for the solution. In particular, these will be classes that correspond to the lifelines that you discover that you need in the Sequence Diagrams. There are also rules-of-thumb (general guidelines) that can be applied to suggest Analysis Model content, based upon the content of the Use-Case Model. (We explain those briefly later in this section.)

In RUP, whether or not an Analysis Model should be maintained independently of the Design Model is a project-specific decision. It is a decision that you make on the basis of whether you believe the value of maintaining the separate Analysis model will warrant the time invested. There are several options that you might consider:

  1. As discussed in the earlier section on Organizing RUP models, during early phases of projects when content is highly volatile (or any time that use-case and analysis modeling are performed by the same people), maintain analysis content within the same model/LU as the Use-Case Model. Apply the RUPAnalysis profile to the models and use packages with the <<analysis>> keyword to segregate the analysis content from the use-case content. Later, you might extract the analysis-level content into a separate model/LU, which itself might be managed in any of the ways that we describe here.
  2. Create an Analysis Model independent of the Use-Case Model (one that resides in its own logical models, based on the Analysis Model template). Then use a manual process or model-to-model transformations to create refined versions of the analysis elements in a separate Design Model. This leaves you the option of maintaining the separate Analysis Model ongoing or discarding it.
  3. Do the same thing, but then just let the Analysis Model evolve into a Design model in place. (RUP, in fact, mentions the option of creating analysis classes and analysis-level use-case realizations in the Design Model and then evolving them directly into their design forms from there.) Here, you start modeling the use-case realizations by using analysis classes and then, over time, refine them so that true design interfaces take on the roles in the modeled behaviors.
  4. A hybrid of the second and third options is to maintain an Analysis Model of sorts within the same model as the Design Model. With this approach, as the Design Model is discovered, you create packages along the way, in which you preserve some of the pure analysis perspectives. To do this, you segregate the analysis content into packages to which you apply the keyword <<analysis>>.

Standard Analysis Model template

The products under discussion provide the option to create a new model/LU based on Analysis model templates. (You can also create your own model/LUs for use as templates.) These templates may define a specific subset of UML capabilities that are typically used when doing analysis modeling. In other words, when working with models based upon the template, the drawing palettes and drop-down menus contain only those UML elements commonly used by someone who is focused on analysis.

In addition, a RUPAnalysis profile is applied to model/LUs that are created from these templates, and the templates contribute a set of default content, as shown in Figure 7. (It is not within the scope of this article to explain how the Analysis Building Blocks content and search strings are used, but notes included in the templates provide those instructions.)

Figure 7. Default content of an Analysis Model Template as included in the products under discussion
Default content of an Analysis Model Template

Like the Use-Case Model template, the Analysis Model template is biased toward logical partitioning of functionality as the technique that drives model organization. (This bias manifests as the use of the ${functional.area} package template as the primary building block of a Use-Case Model.) Figure 8, which follows, depicts a trivial example of the kind of Analysis Model organization that is encouraged by this bias.

Figure 8. Example of high-level organization of an Analysis Model
Example of high-level organization of an Analysis Model

As discussed in the section on Organizing RUP models, this is not the only possible approach to logical partitioning. It was chosen for use with the template for these reasons:

  • It generally maps well to division-of-labor concerns when a team of people will be working on the Analysis Model.
  • It maps upstream to the template-inspired Use-Case Model organization if you want to use custom transformations to seed analysis models from Use-Case models.
  • It has the best chance of yielding an Analysis Model organization that will map well to Design and Implementation models when used in organizations that foster strong ownership of functional modules. (Although it may also reflect layering considerations, the organization of design and implementation models will most often also reflect functional decomposition or component concerns.) This could prove particularly important if you expect to use transformations to seed lower levels of abstraction.

The template also suggests the use of other organizational techniques:

  • Segregation of analysis elements (stereotyped classes) into a sub-package of each functional-area package
  • Use of <<perspective>> packages to capture diagrams depicting views that cut across functional areas (while semantic elements of the model remain organized by functional area).

Figure 8, shown previously, illustrated some techniques for structuring Analysis Models, based on the general approach encouraged by the Analysis Model template. A slight variation of this approach is depicted in Figure 9, which follows. (This illustration is based on Version 6 of the products under discussion, which used different icons in its Project Explorer view. The difference is that a top-level package has been used to segregate the use-case realizations from the analysis classes. Within that top-level package, you see a set of sub-packages that matches the functionally oriented top-level packages. The potential advantage of isolating the use-case realizations is that it lets you refactor the top-level package structure without necessarily affecting the organization of the use-case realizations. The reason that this might prove worthwhile (particularly if the Analysis Model will evolve to Design in situ) is that the package organization for classes will probably need to evolve so that it no longer matches the one that was originally established for the use cases.)

Figure 9. Variation of the Analysis Model high-level organization
Variation of the Analysis Model high-level organization

Depending on your situation, there could be reasons to introduce the use of a naming convention that anticipates merging and reuse of model content created by multiple independent groups, even including groups in different (partner) businesses. If this is a concern, consider using an inverted Internet domain namespace convention as depicted in Figure 10 (also based on Version 6 of the products under discussion). Note that this is probably not a big concern for analysis modeling per se, but if you are taking the approach of letting your Analysis Model evolve into your Design Model in situ, and you anticipate reuse or business integration at the design level, you might want to plan ahead in this manner. Another potential advantage of adopting this approach is that, because it may map well to the organization of code generated from the analysis and design, it may simplify subsequent configuration of the model-to-text (code) transformations.

Figure 10. Example of using a using an inverted Internet domain namespace convention
Example of using a using an inverted Internet domain namespace convention

Analysis Model content

There are several ways to discover analysis classes. One way is to start drawing the Sequence Diagrams that suggest use-case realizations. As you do, you will discover what lifelines you need. Generally, each lifeline represents a candidate analysis class. When you discover classes this way, you might create them in the use-case realization packages of the Analysis Model but might not leave them there (for instance, you might withdraw them into functionally oriented packages as depicted in the earlier illustrations).

Another useful approach for discovering analysis classes: Seed the analysis model with classes based on these guidelines:

  • For each use case (in the Use-Case Model), add a <<control>> class to the analysis model. Control classes represent the business logic associated with the use case. (Later, in design, they will also map to concerns such as session management.)
  • For each Actor-use case relationship (in the Use-Case Model), add a <<boundary>> class to the Analysis Model. The <<boundary>> classes represent interfaces between the solution and a human actor, or between the solution and some external system. The <<boundary>> classes that correspond to a human actor are likely to eventually map to one or more user interface artifacts in the design and implementation; whereas, the <<boundary>> classes that correspond to an external system might eventually map to some sort of adapter layer in the design and implementation.
  • Through a process such as CRC card analysis, or a word analysis of use case descriptions, identify additional <<control>> classes (verbs) and <<entity>> classes (nouns)
  • Other potential sources of <<entity>> classes include Domain models, Logical Data models, Master Data models, and business glossaries

No matter how you discover analysis classes, you are almost sure to recognize that changes to your original functional package organization are needed. Suggestions follow regarding analysis model content and the evolution of analysis model organization:

Recommended: The Analysis Model should contain analysis-level use-case realizations that describe how the use cases are performed in terms of collaborations of the analysis classes. Each use-case realization (represented by a UML Collaboration) corresponds to a UML Use Case in the Use-Case Model. It probably should have the same name as that Use Case, as well as a derivation or realization relationship to the Use Case (see Figure 8, shown previously).

Recommended: For any named use case flow (as previously established in the Use-Case Model) that you feel should be modeled as an analysis-level realization, add a Sequence Diagram to the Collaboration to represent the realization of that flow. This will automatically add a UML Interaction as the owner of the Sequence Diagram. See Figure 11. (Notice that, in Figure 11, some preferences have been set to filter out much of the detailed UML semantic content, such as properties. By default, this content appears in the Project Explorer. You might have to adjust your Preference settings to produce a view similar to this one.)

Figure 11. Collaborations (use case realizations) that own Sequence Diagrams
Collaborations (use case realizations) that own Sequence Diagrams

Suggested: After you have created the Sequence Diagram for a use case flow, you can select its owning UML Interaction in the Project Explorer and add a Communication Diagram to it. The new Communication Diagram will be automatically populated with the analysis class instances that are in the Sequence Diagram.

Suggested: Create a realization dependency relationship from each use-case realization (UML Collaboration) and the corresponding use case from the use case model (see Figure 12, which follows). Because you can use features such as Topic Diagrams and Traceability Analysis to understand the traceability relationships in your model, you don'' really need to retain permanent diagrams to depict the traceability relationships. Therefore, you can create the relationships using some kind of throw-away diagram. For example:

  1. Add a freeform diagram to the Collaboration.
  2. Drag the Collaboration onto that diagram.
  3. Drag the use case onto it, too (perhaps from a different model).
  4. Draw the dependency relationship.
  5. Finally, in the Project Explorer, delete the diagram from the Collaboration.

Suggested: Include a Participants diagram for each use case realization to show the analysis classes that participate in the realization (that is, the analysis class instances that appear on the interaction diagrams that describe the realization of the use case) and the relationships among those classes that support the collaboration described in the interaction diagrams. This may include both entity classes and data transfer object classes. See Figure 12.

Figure 12. Example of a use case realization Participants Diagram
Example of a use case realization Participants Diagram

Guidelines for internal organization of a RUP Design Model

The products under discussion provide the option to create a new model/LU based on Enterprise IT Design Model templates. These are templates that you can use for design (and, optionally, for analysis) when targeting business applications. You can also create your own model/LUs for use as templates

Standard Enterprise IT Design Model template

These templates may define a specific subset of UML capabilities that are typically used when doing design modeling (in other words, when working with models based on the template, the drawing palettes and drop-down menus contain only those UML elements commonly used by someone who is focused on design). In addition, an Enterprise Java™Beans (EJB) Transformation profile is applied to model/LUs that are created from these templates, and the templates contribute default content (see Figure 13). It is beyond the scope of this article to explain how the Design Building Blocks content and search strings are used, but notes included in the templates provide those instructions.

Figure 13. Default content of an Enterprise IT Designer Model template as included in the products under discussion
Default content of an Enterprise IT Designer Model template

As previously discussed in the section called Organizing RUP models, the approaches described here are not the only ones to consider. For instance, the nature of resource specialization within your development teams might suggest that you put more emphasis on architectural layers (and less on functional decomposition) as drivers of model organization.

Figure 14 illustrates techniques for structuring design models, based on the general approach encouraged by the Enterprise IT Design Model template.

Figure 14. Design Model high-level organization
Design Model high-level organization

These are the techniques and variations:

  1. Separate the specifications from the implementation designs (things such as interfaces and supported patterns of interaction). The illustration shows the use of top-level packages, named Design Contracts and Implementation Designs, as a way to accomplish this. An alternative to this technique is to place the specifications and implementation designs into separate model/LUs.
  2. Use lower-level packages to establish functionally oriented groupings.
  3. Within the packages that group semantic model elements, place diagrams that provide views specific to that grouping but that do not depict elements from outside of the grouping. This guideline pertains whether that grouping is based upon functionally oriented subsets of the business domain, upon an architectural layer, or something else. Give the default diagram the same name as the package or component itself, and compose it to show an overview of the contents of the package. This keeps some diagrams close to what they depict, making it easier to navigate and understand the model.
  4. Consider using inverted Internet domain namespaces in the Design Model. The rationale is two-fold:
    1. Basically, the same reasons that doing so is important with respect to language-specific implementations:
      • Scenarios involving integration work where there are multiple model-driven applications involved (especially with partner companies)
      • Re-use scenarios
    2. This will likely simplify subsequent configuration of transformations to implementation (source-to-destination location and name mapping).
  1. Consider using package names that will be valid in the target implementation platforms to avoid the burden and potential confusion of namespace mapping. (For the most part, this simply means: Do not use spaces or punctuation other than underscores in the names.)
  2. Consider using lower case for package names to make them easier to distinguish from class names in a package.
  3. Consider using different names for Interfaces and the Components or classes that realize them. Use either ILoan and Loan or Loan and LoanImpl for interface and implementation names. This is not actually necessary in the model, but is often a good idea in generated code. Therefore, this is another area where you can spare yourself subsequent transformation configuration work.

If you choose not to maintain a separate Analysis Model but do wish to maintain some content at the analysis level of abstraction within the design model, and you will be using model-to-text (code) transformations on the design model, then consider segregating the analysis-level content (from which code is presumably not meant to be generated) within packages stereotyped as <<analysis>> (Such packages will be bypassed by transformations.)

  1. Use diagrams in <<perspective>> packages to capture high-level, cross-cutting views of the design elements. Rationale: Provide cross-cutting views, views of architecturally significant content, and views that appeal to different types of stakeholders while keeping the semantic elements of the model organized into functionally oriented groupings.

Tip:
It is important to recognize that the packaging structures of design models will evolve over time.

The initial organization of the Design Model in a RUP practice will usually correspond more or less directly to that of any upstream Use-Case or Analysis model. (The packaging of the analysis classes is often refactored significantly as it is discovered to better support reuse and unanticipated functional requirements.) Ultimately, however, the organization should evolve to reflect how you structure your architecture into components and services. because this approach to the end game organization of the design will then generally offer the best potential for packaging reusable assets. It is also the most straightforward mapping from the design to the set of projects and folders that will hold implementation artifacts generated from that design (code, metadata, documentation).

Of course, alternative approaches such as these are possible (and in some cases advisable) as an end-game organization. For example, if you are targeting Web applications based on Java™ Enterprise platform, the organization of the design might anticipate the conventions of Rational Software Architect and Rational Application Developer regarding J2EE projects (see sidebar).

Rational conventions

Loosely speaking, these Rational conventions have been:

  • An Enterprise Project per application or service or major subsystem
  • For each Enterprise Project, a Web project for the presentation tier and multiple EJB projects (where the EJB projects correspond generally to components, services, or minor subsystems, and where typically separate EJB projects are used for the session EJBs and domain entity EJBs layer for each component or subsystem)
  • Additional Web projects for any services exposed as Web services
  • Optionally: Any number of Java projects that hold utility classes, proprietary framework components, and the like

In particular, you might choose to define top-level design packages that correspond to the architectural layers (Presentation and Business, with Business sub-layered into Session and Domain). This obviously is not a platform-neutral approach, thus it advisable only if you know that the solution you are designing will not be implemented on a platform other than J2EE.

This obviously is not a platform-neutral approach to organization, thus advisable only if you know that the solution you are designing will be implemented on Enterprise Java. But more generally, when building n-tier applications, it is often the case that developer expertise and the division of labor correspond to Presentation and Business layers. Thus again, you could choose to use top-level packages that correspond to those architectural layers, and you should still be able to map the organization of the design to a set of target projects and folders by investing additional effort in configuring the code-generation transformations. (You can use a special type of companion model referred to as a mapping model to define particularly complex mappings.) But, in general, use caution when you consider organizing the model around a particular architecture as opposed to organizing around functional cohesion, loose coupling, and an eye toward strong ownership.

Design Model content

There are no hard-and-fast rules for what should reside in the Design Model. The way that you model a particular aspect of a design (or for that matter, whether you even bother to model a particular aspect) should be a function of how much business value that modeling approach will add. For some, getting the biggest benefit from modeling means defining guidelines (and maybe UML profiles) for using a small but highly expressive set of representations that are fed into customized transformations that generate most of the implementation. For others, whose objectives are oriented more toward clear expression of a design contract to support the (manual) offshore development of an implementation, a more detailed representation at the UML level might be more appropriate.

With that said, some of the approaches that are suggested by the following illustrations may prove useful for those who plan to model substantial amounts of design detail. Figure 15 depicts an in-process design model for an online auction service, showing an overview of its content at a high level. This design model is an in-place evolution of an analysis model.

Figure 15. Partially completed design model for an online auction service
Partially completed design model for an online auction service

In Figure 16, notice that the use contract for a ListingService is expressed as a single Interface. (The packaging of the analysis classes is often refactored significantly, as it is discovered, to better support reuse and unanticipated functional requirements.) The corresponding realization contract is specified by a set of design-level use-case realizations. (Other components might participate in just one system use case, and their realization contracts might reside in single use-case realizations.) Note here that, whereas analysis-level use-case realizations show collaborations among analysis classes, the design-level realizations show collaborations among less abstract design elements.

Figure 16. Design contract modeled as an interface and design-level use case realizations
Design contract modeled as an interface and design-level use case realizations

In Figures 16 and 17, notice that the data transfer objects (DTOs) have been included as part of the implementation design. These DTOs serve as the types of parameters of the provided operations and might also map to implementation constructs, such as an XML schema or service data objects (SDOs). For components that are not designed to be distributable, you may choose to use only implementation-specific data transfer objects (actual Java classes, for instance) as the specifications of the types used as operation parameters. However, for distributable services (Web services) like this ListingService, it is mandatory that the service's operations not reference objects in a local address space, which means that DTOs defined in the specification must be used to represent message payloads. In the case of this ListingService example, the DTOs are actually defined to conform to a set of message specifications defined as part of a hypothetical industry standard (as called out previously in Figure 16).

Figure 17. An approach to representing implementation design using Classes with Methods
An approach to representing implementation design using Classes with Methods

Rational XDE and Rational Rose migration

In prior versions of UML, guidance for use-case realizations was to use a Collaboration Instance for each use case and an interaction and Sequence Diagram for each of the significant flows of the realization. In the products under discussion, you should often be able to use just one interaction and diagram, because UML 2 Sequence Diagrams now support notations for alternative execution paths.

Also, in UML 2, there is no longer a Collaboration Instance. Instead, there is Collaboration Use, which requires a Collaboration as its type. Therefore, in the products under discussion, use Collaborations to represent use-case realizations.

One possible approach to specifying implementation designs is shown previously in Figure 17, where the implementation structure is defined using simple classes that contain operations. This approach is quite typical of design models created using UML 1.

A second possible approach that may be more in keeping with the goals of UML 2 is shown in Figure 18, where you see that Components are used and that the Components do not own Operations but, instead, own behaviors (in this case, an Interaction).

Figure 18. Alternate approach to representing implementation design using Components with owned Behaviors
Alternate approach to representing implementation design using Components with owned Behaviors

Guidelines for other RUP models

In comparison to the Solution Use-Case, Solution Analysis, and Design Models, far less needs to be said about these other RUP models:

  • Business Use Case
  • Business Analysis
  • Deployment
  • Information
  • Implementation

Rational architecture management software does not include model templates for these. Generally, the same guiding principle of strong ownership should drive the organization of such models.

  • The organization of Business Use-Case and Business Analysis Models is likely to be quite similar to the solution-level counterparts.
  • Implementation models in the products under discussion consist of Eclipse projects and code and metadata artifacts, plus diagrams that reflect those artifacts. Therefore, the implementation architecture will directly determine the shape of implementation model organization.
  • The organization of Deployment models will typically have very few upstream or downstream implications. Just do what makes the most sense in your situation. For example:
    • Specifications of production configurations have been separated from those of test configurations.
    • Overviews (of clusters, data centers, or enterprises) are maintained in <<perspective>> packages.
    • The products under discussion use a combination of packaging and keywords as a lightweight approach to specializing and classifying nodes and artifacts. A more sophisticated approach would be to develop a specialized UML profile that defines specialized stereotypes and properties that are appropriate for describing and documenting the types of resources used in your own environment.

Download

DescriptionNameSize
English(v7)ArchtMgt_SW_series_Part2.pdf3233KB

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational, Architecture
ArticleID=282326
ArticleTitle=IBM Rational Architecture Management Software model structure guidelines: Part 2. Classic Rational Unified Process
publish-date=01222008