Rational Software Corp.

TOC PREV NEXT INDEX


Dividing a Model into Controlled Units

This chapter is organized as follows:

What is a Controlled Unit?

By default, Rational Rose saves a complete model as a single model (.mdl) file. However, when many users are working on a model at the same time, you can reduce contention and enable parallel development by dividing the model into a series of individual files called controlled units.

Controlled units are the configuration elements that a team places under version control. When using controlled units, each team or team member is responsible for maintaining or updating a specific unit.

The lowest level of granularity for a controlled unit is a package in the use case, logical and component views of a model since packages are considered the smallest architecturally significant elements.

Figure 18 Controlled Units

What Can be a Controlled Unit

You can create controlled units for packages in your Use Case, Logical, Component, and Deployment Views, as well as your model properties.

When you create controlled units, you name each new file and use one of these four extensions for the particular type of controlled unit you create:

You can have an unlimited number of .cat and .sub files associated with a Rational Rose model. Because a model supports only one deployment diagram, there is only one .prc file. Similarly, there is a single set of model properties and only one .prp file.

You cannot create controlled units for three of the top-most views, namely the Use Case, Logical, and Component Views.

Figure 19 View from which you cannot create Controlled Units

How Controlled Units are Related and What They Contain

When you create a controlled unit from a package, the contents of the package are moved from the model file or enclosing package, and stored in the new unit file. The new controlled unit file contains:

The original file no longer holds the contents of the package. Instead, the original file now only references the new controlled unit file.

The model file only references the first level of controlled units. Thus, a controlled unit that holds another controlled unit also holds the reference to that unit.

Packages own modeling elements such as other packages. Ownership implies a one-to-one relationship. Therefore, every package is owned by exactly one other package in the model.

When you work on a controlled unit, you can change its contents without affecting the controlled unit it might belong to, or the controlled units it encloses.

Figure 20 Example of a Controlled Unit Hierarchy

In Figure 20, developers can modify the file articles.cat without affecting business_serv.cat, and business_serv.cat can be modified without affecting ordersys.mdl.

You can create a virtually unlimited hierarchy of controlled units where top-level controlled units consist of references to other controlled units.

For example, you could make all packages controlled units with top-level packages that are pointers to nested packages. This enables two developers to check out packages that belong to the same higher level package.

Packages can also be shared. By creating controlled units, multiple models can share the same packages, allowing you to effectively reuse model elements.

How you partition a model and the type of hierarchy you implement will depend on how team members will operate, both physically (who works on which packages) as well as logically (how best to partition the model and preserve its design).

Figure 21 illustrates how controlled unit hierarchies appear in the Rational Rose browser.

Figure 21 Controlled Unit Hierarchies in the Rational Rose Browser

The format that Rational Rose uses for the model (.mdl) and controlled unit files is called petal format. Petal is a text-based format that allows you to open and view the model and controlled unit files in any text editor. The petal format is the same on Windows and Unix platforms, thus enabling teams of developers on different platforms to share models.

Working with Controlled Units

Creating Controlled Units

To designate a package as a controlled unit, you select the package in the browser or diagram then click File > Units > Control. Rational Rose prompts you to provide a location and a filename with the appropriate extension, then it moves the contents of the selected package from the model file (or enclosing controlled unit) into the specified file.

Note: After you create one or more controlled units, you must save your Rose model in order to save the new references in any enclosing controlled units or in the model (.mdl) file.

Because the model file (or the enclosing controlled unit, if the new unit is going to be created inside another unit) is changed when a new controlled unit is created, ensure that the enclosing file is write-enabled. If the file is under version control, you must first check out the file.

Carefully consider the file structure you implement when creating and saving controlled units. If the controlled unit will be under version control, the file structure you use may need to correspond to the version control structure.

Also, in the early stages of analysis and design, the architecture of your model can change, sometimes drastically. During these early stages, modeling elements are often created, moved, and deleted. When a controlled unit is moved in the model, the corresponding controlled unit file is not automatically moved in the directory structure. If there is significant change, the directory structure can become fragmented, resulting in situations where controlled units that are logically grouped in the model will not be physically located in the same directory hierarchy.

Loading, Reloading, and Unloading Controlled Units

There are three ways to load controlled units:

Figure 22 Controlled Unit File Name

If your model is large, or you are planning to work on a few specific units, you can greatly reduce latency and resource consumption by manually loading individual controlled units, or by creating and then loading a model workspace.

To view or update a unit modified by another developer since you last loaded it, you must reload the unit by using File > Units > Reload.

In Figure 23 Rational Rose uses the icons in its browser to distinguish between loaded and unloaded units.

Figure 23 Loaded and Unloaded Controlled Unit Icons

In diagrams, Rational Rose uses adornments to indicate which model elements are controlled units and whether there are unresolved references to unloaded units. You can enable or suppress adornments by clicking Tools > Options > Diagram > Display.

Figure 24 Adornments Indicating Controlled Units and Unresolved References

To unload a controlled unit, select the controlled unit in a diagram, then click File > Units > Unload.

Creating and Using Model Workspaces

Understanding Workspaces

A workspace is a snapshot of all currently loaded units and open diagrams. By defining one or more workspaces, you can set up your working environment in Rational Rose and return to that environment each time you are ready to work. When you load the workspace, Rational Rose restores the snapshot by loading the specified controlled units and opening the correct diagrams.

If you work with large models that are divided into many controlled units, you will notice even greater productivity gains by using workspaces to load predefined units and diagrams.

How a Saved Model Differs from a Model Workspace

A saved Rational Rose model contains the diagrams, elements, and controlled units that make up the complete model. A model workspace contains the actual state of open diagrams and controlled units for a specific saved model at a given point in time.

It is possible to have multiple workspaces that correspond to only one model. For example, during analysis and design, you can define one model workspace that displays the most important analysis diagrams and controlled units, and another model workspace for important design diagrams and controlled units. Each workspace is different but uses the same model.

Saving a model workspace does not affect how the model is loaded on another computer. If another team member loads a model using a model workspace that you defined on your computer, they must have a copy of the model and the model workspace in the same folder on their computer.

By default, Rational Rose names the workspace <model name>-<Operating System User Name>.wsp. For example, the name of a saved model workspace may be MyModelName-SomeUser.wsp.

Note: Rational Rose stores all workspace files (*.wsp) in the workspaces folder of the Rational Rose installation directory.

Workspace Scenario

The following scenario shows how using model workspaces can benefit a team working on a large model.

A new software developer joins a distributed team working on a very large model containing over two hundred controlled units. Through the course of the next several months, the new developer will model several systems in the Use Case Model and modify the Business Actors and Use Cases (as shown in Figure 25). To help the new developer, the team's project manager creates a model workspace that loads all of the units the software developer is responsible for, as well as some of the more important diagrams.

Figure 25 Example Model Workspace

When the developer loads the model workspace, the Business Actors, Business Use Cases, eCommerce System, POS System, Telesales System, and Warehouse System controlled units load. The workspace configuration also displays some important class and activity diagrams in the diagram window.

The model workspace helps the new developer by:

After working in the model, the developer can easily customize the model workspace the project manager created, or create additional model workspaces for greater efficiency.

Creating and Saving a Model Workspace

To create a model workspace:

1 Load all controlled units that you will want to restore when loading this workspace.

2 Open all diagrams to restore when loading this workspace.

3 Click File > Save Workspace.

Name the model workspace file in the Save As dialog box. The default model workspace name is <model name><Operating System Use Name>.wsp.

Rational Rose stores all model workspace files (*.wsp) in the Rational Rose workspaces folder.

Loading a Model Workspace

To load a model workspace, click File > Load Model Workspace. Select the name of workspace file (*.wsp) to load.

Protecting Controlled Units

When loading a controlled unit into a model, Rational Rose makes the unit write-protected or write-enabled depending on the current status of the file in the file system. A controlled unit, which is read only in the file system, is write-protected in the model and Rational Rose prevents you from modifying it. This means that the toolbox is dimmed on all of its diagrams and you cannot update the Specifications of the contained model elements.

Note: If a write-protected controlled unit contains other controlled units, the write-protection is not extended to the contained controlled units.

A unit's write protection status displays in the Rational Rose Status Bar when selecting the controlled unit in the browser. For example, the status of the controlled units in Figure 26 is write-enabled.

Figure 26 Write-Protected Control Unit

If you use a version control add-in, Rational Rose handles the write-protection of the controlled unit automatically. This means that a checked-in unit is automatically write-protected.

There may be situations when you want to write-protect or write-enable a controlled unit manually from within Rational Rose (even if the controlled unit is under version control). For example, if:

You can change a unit's write-protection manually from within Rational Rose by using File > Units > Write Protect/Write Enable.

Write-Protecting a Controlled Unit

There are three ways to write-protect a controlled unit:

Write-Enabling a Controlled Unit

To write-enable a controlled unit under version control, click Tools > Version Control > Check Out. This will check out the unit and allow you to edit it.

Splitting a Controlled Unit

If a controlled unit becomes too large or if several team members often need to update a unit at the same time, you can split the unit. There are two ways to split a controlled unit:

To split a controlled unit into two units, ensure that the controlled unit is write-enabled. If it is under version control, you must check out the file. If you want the original unit to constitute one of the new units, create one new package at the same level as the controlled unit. Otherwise, create two new packages.

Move the contents that belong to the new package (including the associations) from the unit into the new package by using drag-and-drop in the browser. Or, move the contents by selecting an element in a diagram, copying the element to the Clipboard, pasting it into a diagram that is owned by the new package, and then clicking Relocate on the Edit menu. Designate the new package(s) as a controlled unit.

Note: If you move classes from one package to another, the dependencies and generalizations move; the associations do not move. You must move the associations manually.

To divide the contents of a controlled unit into two sub-units, ensure that the controlled unit is write-enabled. If it is under version control, you must check out the file.

Create two new packages in the package that corresponds to the controlled unit, then move the contents from the unit into the two packages by using drag-and-drop in the browser. You must manually move any associations as well. Designate the new packages as controlled units.

Merging Controlled Units

You can display the differences between, and merge two versions of a controlled unit by using Model Integrator on the Tools menu.

For more information, see Chapter 5, Comparing and Merging Models .

Adding Controlled Units to a Model (Importing/Loading)

The controlled units you create can be imported or loaded into other models. Importing and loading adds a reference to a controlled unit in the model; it does not make a copy of the controlled unit. The imported controlled units can be edited in both models; changes made in one model are visible in the other model. As with any file, the controlled unit cannot be open simultaneously in two different models.

Rational Rose imports controlled units to diagrams that currently have focus control; therefore, ensure you are in the diagram to which you want to import the controlled units. The import will fail if you import to the wrong type of diagram. For example, you cannot import .cat files to a deployment diagram.

When you import a controlled unit, Rational Rose attempts to resolve any references. If an element has a reference that Rational Rose cannot resolve, the problem is logged.

Before you import a controlled unit, ensure that the destination model file or enclosing controlled unit is write-enabled. If under version control, you must check out these files.

To import a controlled unit, click File > Import. In the dialog box, select *.cat or *.sub, or *.* as the file type. Do not import a .ptl file. These are exported model files. When you import them, they replace the contents of your model.

Uncontrolling Controlled Units

Uncontrolling a controlled unit incorporates the contents into the model file or into the enclosing controlled unit if the unit to uncontrol is contained within another unit. After uncontrolling a unit, the enclosing file will no longer reference that unit's file. Instead, the content of the uncontrolled unit's file is inserted into the enclosing file.

Before you uncontrol a unit, ensure that the model file (or the enclosing controlled unit) is write-enabled. If it is under version control, check out the file.

If you use a version control add-in, select the model element and click Tools > Version Control > Remove from Version Control. The contents of the unit are now incorporated into the corresponding package in the model, and the file is removed from version control.

If you do not use version control, right-click on the package in the browser and click Uncontrol on the Units menu. The contents of the unit are incorporated into the corresponding package in the model, but the file continues to exist in the file system.

Save the model (or enclosing controlled unit), which now holds the contents of the unit file.

Creating Virtual Paths to Controlled Units

Understanding Virtual Path Maps

Rational Rose allows you to define symbolic names for file paths. Each user can control how these symbolic or virtual names are defined in their own workspace.

Path maps are essential for working in teams, especially where all users cannot work in exactly the same directory on their local machines. Using path maps allows model files to be distributed and relocated.

When you create controlled units, the enclosing model file or controlled unit stores the reference to the new unit as a file path. In the sample illustration that follows, the classics.mdl file contains the path to analysis.cat, the Analysis Model controlled unit file. In the illustration, the text is actually the contents of the .mdl and .cat files when opened in a text editor. The analysis.cat file contains a path to eCommReal.cat, the controlled unit for the eCommerce System Realizations package which Analysis Model encloses.

Figure 27 Virtual Path Maps

By defining virtual path maps, you substitute absolute paths with virtual paths. This allows you to move models and controlled units between different folder structures, and to update them from different workspaces.

How Virtual Paths Work

When Rational Rose reads from or writes to a model, it attempts to substitute every absolute path with a virtual path. When Rational Rose opens a controlled unit, or uses a path specified in a model property, it converts each virtual path to an absolute path.

For example, if a user has defined a virtual path,

and saves a package as

the model file will refer to the package as

When another user, who has defined $MYPATH as

opens the same model from their "X" drive, Rational Rose resolves the internal reference to the controlled unit and loads the following file:

After you create virtual path maps, when anyone on the team opens or saves a model, Rational Rose attempts to match the longest possible file path to the symbols in the path map, and will continue until you have concatenated path map symbols.

Note: Each user working on a particular model must define the same path map symbols before opening the model. For example, a user with the private workspace called Y:\MyModels, must define $MYPATH=Y:\MyModels. We recommended that you do not use path maps to point to network drives or shared files.

Creating Virtual Path Maps

You use File > Edit Path Map to open the Virtual Path Map dialog box.

Figure 28 Virtual Path Map Dialog Box

Do not enter the $ before the name in the Symbol box; it is automatically added to the name. When you click Add, the new path map is added to the list of existing path maps at the top of the dialog box.

Defining a Path Map Relative to the Location of the Model File

A leading "&" on a path name indicates that the path is relative to the model file or the enclosing controlled unit (if any). For example, if you create a model:

and a controlled unit:

To allow different users to open the model and load the unit in different locations, each user can create a path map:

When the model saves, the reference from the model file to the package is stored as:

When the model opens in another location, $CURDIR is expanded to the physical path to the model in that specific workspace, for example:

Note: The "&" requires that the controlled units be located in the same directory as the model file or in a subdirectory of the model file.

Defining a New Path Map Using Another Path Map Symbol

The actual path in a path map definition can contain existing path map symbols. For example, if there is a path map, $ROOT=X:\model_vob, you can define a path map for the path X:\model_vob\MyModels by adding the path map $MYPATH=$ROOT\MyModels.

Defining a Path Map with Wildcards

You can use a wildcard character (*) in the path map to parameterize a virtual path. For example, if the following virtual path is defined:

and each user working on "project" has their own set of model files within each subsystem, then a controlled unit belonging to the display subsystem can have the following path:

The model file refers to the unit as:

When the model is opened by user "suzanne," who has the following virtual path definition:

the virtual path reference to the unit is converted back to the actual path:

This allows different users to work on the same files with the same contents but in different folders without having to define a virtual path symbol for each such folder.

The slashes you use to define a path map are not literal, meaning that Rational Rose substitutes the correct format for Windows or Unix platforms.

Using Virtual Paths for the Value of a Model Property

Rational Rose does not convert actual paths in model properties to virtual paths. To use a virtual path in the value of a model property, you must manually enter the virtual path map symbol, including the "$" sign (for example, $CURDIR) into the value of the model property.

Using Path Maps for Other Artifacts

In addition to using path maps for model and controlled unit files, you can use them for any artifacts attached to your model, such as documents, code, and URLs.

It is strongly recommended that you maintain one path map for all model artifacts, including model and controlled unit files. However, if that is not possible, create separate path maps for each directory structure.

The easiest way to use path maps for artifacts other than model and controlled unit files is to create the path map before you attach the artifact. When you do this, Rational Rose automatically converts the absolute path to a virtual path when you attach the artifact and save it.

For example, suppose you created the path map:

When you attach the file test.doc that resides in your E:\Rational directory to the Analysis Model package in a Rose model, the following virtual path is added to the analysis.cat file (the controlled unit for the Analysis Model package): 

    external_docs  (list external_doc_list
      (object external_doc
            external_doc_path "$MYDOCS\\test.doc"))

If you attach an artifact before you create a path map, Rational Rose does not automatically convert the absolute path to a virtual path when you save your model. However, it does automatically do the conversion for controlled units and .mdl files.

Alternatively, you can move the artifact to another part of your model, immediately move it back to its appropriate location, then save the model. There is no need to save the model when the artifact is in its "temporary" location.

Similarly, if you delete or change a path map, you need to perform these same actions for Rational Rose to register the change.

Where Virtual Path Maps are Stored

Virtual path maps are stored in two locations in your system registry: the users area and the system area. A user can typically see and access only the virtual path maps in their specific area of the registry.

There are also system virtual path maps that are in HKEY_LOCAL_MACHINE. You need to be an administrator to edit these virtual path maps on a specific computer.

Checking References and Access Violations

After you create controlled units and unit ownership becomes distributed, it becomes increasingly important to check the integrity of your model. There are two ways to do this:

Check Model

Check Model (Tools > Check Model) scans the entire model looking for unresolved references and places the results into the log. You can use this feature when you save your model to multiple controlled units, to ensure that all the units are consistent with one another. This is especially useful where parallel development occurs in multiple controlled units, since it is possible for different units to get out of synch with one another.

In a model where one item holds a reference to another item, it is possible that a reference exists, no item in the model of the right kind or with the right name. In that instance, the reference is unresolved.

Check Model checks the reference:

Show Access Violations

Show Access Violations (Report > Show Access Violations) provides a list of all access violations between packages in a model.

As projects grow larger, access violations become more important Show Access Violations is the primary tool for verifying that a large project is maintaining its design architecture.

An access violation occurs when a class in one package references a class in another package without an import relationship between the two packages. The import relationship is a dependency between the two packages. The direction of the dependency must be the same as the direction of the relationship between the classes or interfaces.

An access violation will also occur when a package references a class from another package whose export control is not set to Public. In this case, the presence of an import relationship between the two packages has no bearing. All references to non-public classes from different packages are cited as violations.

Import (dependency between packages) is not transitive, so if package A imports package B, which imports package C, then package A is not importing package C. A would have to have import package C separately.

Also, a package that has a nested package automatically gets visibility to the nested package. The inner package does not have visibility to its parent. Any package that imports the parent does not get visibility to the nested packages.

Violations are displayed in a dialog box. You can locate the diagram and element where the violation occurs by selecting the violation from the dialog box and clicking Browse.

Organizing Controlled Units for Teams

When sharing models among teams of developers, it is essential that the model be partitioned so that it can evolve in a controlled manner. To successfully share a model, you need to manage the dependencies between different portions of a model.

Ultimately, how many packages and controlled units to create becomes a question for the project leader or model architect, and the person responsible for configuration management in your project. The level of version control you use may define what becomes a controlled unit. For example, all packages can be controlled units, including nested packages. Doing so, provides the capability for two developers to check out packages that belong to the same higher level package.

Suggested Strategies

The following are strategies to consider when partitioning a model into controlled units:

For more details about model architecture, see Establishing a Model Architecture and Process for Team Development.

Rational Software Corporation  http://www.rational.com
support@rational.com
techpubs@rational.com
Copyright © 1993-2001, Rational Software Corporation. All rights reserved.
TOC PREV NEXT INDEX