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

Document options Document options requiring JavaScript are not displayed Rate this page Help us improve this content

Level: Intermediate

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

22 Jan 2008

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.

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.

Back to top

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.

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.

Back to top

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.

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.

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

Back to top

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.

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.

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.

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.)

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).

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.

Back to top

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.)

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.

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.)

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.

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.)

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.

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.

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.

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).

5. 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.)
   
   
6. Consider using lower case for package names to make them easier to distinguish from class names in a package.
   
   
7. 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.)

8. 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.

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.

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).

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).

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.

Share this... Digg this story Post to del.icio.us Slashdot it!

Back to top

Download

	Information about download methods			Get Adobe® Reader®

Resources

• More context for this series of articles is available at the series summary page.
  
  
• Part 1 of this series, IBM Rational Architecture Management Software model structure guidelines: Part 1. Fundamentals.
  
  

• For tool-neutral information on how to define, develop, and model the contents of the RUP artifacts, see these sources:

  • IBM Rational Unified Process (RUP)
  • Any of the several books on RUP-inspired modeling by authors such as Terry Quatrani, Eric Naiburg and Bob Maksimchuk, or Jim Conallen.

  For information on tool-specific techniques for developing the content of models for the products under discussion, see these for helpful information:

  • Rational product documentation (tutorials, samples, Help)
  • Tool Mentors in the RUP configurations (which include this article)
  • Rational software area and the Software Architecture area on IBM developerWorks
  
  
• Read The New IBM Rational design and construction products for Rational Rose and Rational XDE users by Bill Smith (developerWorks, December 2005). This article is intended to help users of IBM Rational Rose and IBM Rational XDE grasp some of the major new concepts that they will encounter as they migrate to the newer family of IBM Rational model-driven development tools: IBM® Rational® Software Architect, IBM® Rational® Software Modeler, and IBM® Rational® Application Developer.
  
  
• Subscribe to the developerWorks Rational zone newsletter. Keep up with developerWorks Rational content. Every other week, you'll receive updates on the latest technical resources and best practices for the Rational Software Delivery Platform.
  
  
• Subscribe to the Rational Edge newsletter for articles on the concepts behind effective software development.
  
  
• Browse the technology bookstore for books on these and other technical topics.
  
  

• Download trial versions of IBM Rational software.
  
  
• Download IBM product evaluation versions and get your hands on application development tools and middleware products from DB2®, Lotus®, Tivoli®, and WebSphere®.
  
  

• Join the Architecture forum on developerWorks to get connected with others and take advantage of their expertise and experience to get you tips that can help you as a developer or architect to use the principles of service-oriented architecture (SOA).
  
  
• Check out developerWorks blogs and get involved in the developerWorks community.
  
  
• Rational Software Architect, Data Architect, Software Modeler, Application Developer and Web Developer forum: Ask questions about Rational Software Architect and other modeling products.

About the author

		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.

Rate this page

Please take a moment to complete this form to help us better serve you. Did the information help you to achieve your goal? Yes No Don't know   Please provide us with comments to help improve this page:   How useful is the information? 1 2 3 4 5 Not useful Extremely useful

Back to top