Model organization

If you share UML models with team members, you should develop a model organization and partitioning strategy. Model organization has two aspects: logical and physical.

Logical organization

Logical model organization should achieve the following goals:

  • Reflect the organization of the system that you are developing and modeling
  • Support strong ownership of packages or components by individual practitioners
  • Identify items that multiple practitioners must share

Physical organization

Physical model organization has two approaches:

  • You can develop a logical model as a single modeling file and then physically reorganize it into multiple modeling files.
  • You can implement multiple physical modeling files based on the logical organization and the expected collaboration or sharing scenarios.

Planning the physical partitioning strategy has advantages, but a more spontaneous approach is also valid and can sometimes address concerns that were overlooked or not anticipated in a planned approach. For example, you might decide to perform physical partitioning when the overall model size or depth of package structure becomes unmanageable because of new requirements or unexpected design complexities.

Model merges

Model merging is an important consideration when you plan the logical and physical organization of models.

Some configuration management policies enable parallel development, where multiple team members work on the same model at the same time. During parallel development, uncoordinated changes can impact the model. You must merge changes before you save the model file in the configuration management system. A trivial merge occurs when changes do not conflict, and a tool merges the changes automatically. A non-trivial merge occurs when changes conflict and you must determine which changes to accept.

Effective model architecture and ownership

An effective model architecture relies heavily on decomposition, which is the ability to break a system into parts. The following principles of decomposition are the same ones that drive object-oriented development, component-based design, and service-oriented architectures:

  • Isolate business functions.
  • Group items that must remain together, and then isolate those groupings.
  • If your decomposition contains too many granular items, group those items into UML packages.
  • Group items that share many units of decomposition into a common package and at the start of each development iteration, focus on stabilizing common items.
  • Plan for a major refactoring activity as you transition between phases, because you better understand how to decompose your model when you move from an abstract to a concrete model.

If your model after decomposition still contains a high number of dependencies, you have two options:

  • Assign the project to a small team that shares a physical space and whose members communicate when they make changes that affect the artifacts of another team member.
  • Plan to regularly perform non-trivial merges.

After you establish an effective architecture, you can assign ownership of architectural components to individuals or small teams. When one person, or a small team in close proximity, works on a logical package or branch in a model, you minimize non-trivial merges with that model, regardless of whether you store the model in a single modeling file or in multiple modeling files.

Types of physical partitioning

Two mechanisms are available for partitioning logical models: creating a separate model and fragmenting.

When you create a separate model, you typically start with many logical model packages that are organized under a common logical model root, or root package. These logical packages occupy the same physical modeling file. You select one package below the root and create a physical model from that package. The package then becomes a new top-level logical model in the Project Explorer view. The new model is no longer logically owned by the model from which it was partitioned. Also, relationships between the elements the new model contains and elements still contained by the model’s former parent logical model become cross-file relationships. Previously, the relationships were in-file, which impact model compare and merge scenarios.

In contrast, with fragmenting a model, you select any classifier-type element of a model and manage it as a fragment. A fragment is a separate physical Eclipse resource file, but a parent logical model owns its content.

When to physically partition a model

You should only partition a model in extreme circumstances, because model partitioning can hinder team collaboration and development if you do not do it properly.

You often physically partition models to try to reduce the number and magnitude of model compare and merge activities. However, you cannot avoid non-trivial merging by partitioning models into multiple modeling files because architectural interdependencies are logical, not physical. If you partition a model into multiple modeling files, the representations of the element interdependencies become cross-file references instead of in-file references. Merge conflicts that involve cross-file references are difficult to resolve because you do not know the logical content of the models in other model files. When you must perform a merge, physical partitioning makes merge sessions more challenging.

Physical model partitioning is appropriate in the following scenarios:

  • When you use IBM® Rational® ClearCase® shared dynamic views on an integration stream with strictly enforced reserved check outs.
  • When the overall size of logical models grow to a point that common configuration management operations, such as check in, check out, rebase, deliver, or other common operations, such as reporting or analysis, become unmanageable.

If you do not physically partition models, focus on logical organization, strong logical package ownership, and physically large model files. If you use Rational ClearCase, use private static or dynamic views and UCM rebase and deliver to maintain model integrity until you complete full integration.

Also, only partition a model after the logical content begins to stabilize, so that the partitioning decisions are less likely to require change. For example, early versions of a model often depict top-level subsystems. You should not partition until you define top-level subsystems that are likely to remain in future iterations. When the top-level subsystems are mature and stable, you can then separate them physically if it improves parallel development workflows or the performance of tasks such as opening or publishing models. Also, focus on logically stabilizing the common highly shared components first, because changes to these components can introduce conflicts that affect all other partitions.

Synchronized workspaces

To avoid data corruption when you work with model partitions, you should always work in a synchronized workspace that contains all the partitions at the same revision level.


The following example shows what can happen if you work with partitions of a model in an unsynchronized workspace.

In a configuration management system, a model has two partitions, model X and model Y. Both models are at version 20. Model X contains one package, called P1. Model Y is empty.

Two users engage in the following workflow:

  1. User A checks out the two models, both at version 20.
  2. User A makes several changes to P1, and moves P1 from model X to model Y.
  3. User A checks in model X and model Y. Both files are now at version 21.
  4. User B has model X, version 20, in his workspace and makes a change to P1.
  5. When User B tries to save his changes, the configuration management system prompts User B to either check out the existing version in the workspace (model X, version 20) or the newer version (model X, version 21).

If User B selects the existing version in the workspace (model X, version 20), he might have to repeat the operation that prompted the checkout.

However, if User B saves his changes with the newer model version (model X, version 21), he overwrites the changes that User A made.