Using proven patterns and strategies when creating UML models in Together can make it much easier to generate required documents. Most of these techniques involve the use of stereotypes and custom properties.

Custom Properties, Stereotypes, and Profiles

UML defines a small number of extension mechanisms. Tagged values or custom properties is one of them, stereotypes is another.

Custom Properties

All UML model elements and diagrams can be given extra tagged values by typing name-value pairs into the Custom tab of the properties view (see Figure 1).



Figure 1: Custom properties or tagged values added to a UML use case

Explicit Ordering of Elements in Generated Documents

One simple application of custom properties is to use them to explicitly specify an order for an element iterator. We specify an OCL (or legacy) expression on the sorting tab of the iterator’s properties dialog (see The Sorting Tab on page 34) that returns the value of a custom property called something like docOrder. Then we add that custom property to the elements we wish to explicitly order and set the value to a character string that will result in the order we need. For example, we might want to do this for a set of UML use case diagrams that do not sort into the order we want by name or any other existing property.

Of course, the OCL (or legacy) expression can be as complex as we need falling back to use the name if the docOrder property is not present or there are multiple elements with the same value for the property.

The following OCL expression, for example, will order by docOrder property first and then by name property.

if getPropertyValue('docOrder').oclIsUndefined() then
    'zzzzzzzz' + name    
else
    getPropertyValue('docOrder') + name
endif

Two other possible applications of custom properties are described in Expanding or Mapping Enumeration Literals and the other in Iterating along a sequence of connected nodes.

UML Stereotypes

UML stereotypes are used to further classify an element in a UML model.

By default, stereotypes are shown as a name surrounded by guillemot characters (quote marks used in some European languages) and are frequently displayed just above the name of the model element they belong to. Because guillemots look like a pair of angle brackets, this is an accepted alternative representation for those of us who do not have easy access to these European characters on our keyboards.

Instead of, or as well as, being displayed between guillemot characters, stereotypes may cause the element to be displayed using an alternative symbol or colour.

When an element has more than one stereotype the default is to display the stereotype names separated by commas.

Stereotypes can be applied to almost anything in the UML, including classes, attributes, operations, and associations in class diagrams. In Together 2006/7, packages are an exception to this rule unfortunately.

Figure 2 shows an actor with a single stereotype, external system, that further indicates that the type of element is some system external to the organisation. The diagram also shows an use case with two stereotypes, system and financial, indicating that the use case is defined at a system level of abstraction and involves financial transactions.



Figure 2: Actor and Use Case with Stereotypes

Profiles

UML profiles group stereotypes and related tagged values, among other things, into a named whole.

Together provides the ability to define profiles, compile them, and deploy them as additional Eclipse plug-ins. Once a profile has been deployed, it may be switched on for a project by ticking its checkbox in the project’s properties dialog.

Figure 3: Applying a Profile to a Project

Once a profile has been switched on, any tagged values (custom properties) associated with stereotypes in the profile become visible in new tabs in the properties view when that stereotype is applied. For example, if the ER Logical Diagram Profile is enabled for the project, then giving a class the stereotype, «erView», causes a new ER tab to appear in the properties inspector for that class (see Figure 4).

Figure 4: New Tab in Properties View

Tips: There are Eclipse CheatSheets available that step through the defining, deploying and applying of a simple profile. These are available from the main Help | Cheat Sheets… menu.

To ensure custom properties defined in profiles have unique names and do not clash with custom properties defined in another profile, under the covers, Together prefixes the properties name with both the name of the profile and the name of the associated stereotype.

The full name is required in OCL getPropertyValue() operations. A quick way to get hold of the full name is to ensure an example of the custom property has a value and turn off the profile. This forces the property to appear in the standard Custom tab of the Properties view with its full name visible.

Deployed profiles can also be exposed to the OCL processor as additional metamodels by ticking the relevant checkbox the OCL | Metamodels preferences. This enables OCL expressions to treat the stereotypes and their associated properties in exactly the same way as UML classes and attributes for example. The only problem is that anyone else using a template that does this needs to have that metamodel turned on too. Otherwise they are presented with an error box full of OCL processing errors. For this reason, it is usually safer to stick with getPropertyValue().

Figure 5: Turning on the metamodel for the ER Logical Diagram profile

Stereotyped Diagrams

Stereotypes can be included in OCL expressions to filter elements out of iterations (see The Scope Tab and OCL Expressions and Metamodels).

A corollary to this technique is that when we needed to distinguish between diagrams of the same sort so that they appear in different parts of a generated document, we can assign different stereotypes to the diagrams. Then we add filter expressions to element  iterator sections of the GenDoc template so that only the diagrams with the relevant stereotype are processed by each iterator.

Frequently, the same sort of UML diagram is used to communicate different aspects of a model. For example, in a typical component design document, class diagrams are often used to specify the details of the interfaces that a component provides. Then other class diagrams are often used to model the classes that comprise the internal structure of the component. Both are UML class diagrams but they are being used for two different purposes.

Together enables UML diagrams to be given one or more stereotypes.. This means we can use stereotypes to give a more specific meaning to a UML diagram.

For example, we can give the class diagrams depicting a component's interfaces a stereotype of <<component-interface>>. In the same way, we can give the class diagrams showing our component's internal structure a stereotype of <<implementation>>.

Diagrams for Documents

Sometimes it is not possible to add stereotypes to diagrams to indicate where in a generated document we want them to appear, or we want to include various different subsets of diagrams in different documents making the stereotype approach too cumbersome.

In these circumstances another option is to create a diagram to represent the document and add the desired diagrams that comprise the contents as shortcuts.

For example, the desired contents of a component design document might include:

• one or more UML deployment diagrams showing the context of the component,
• a class diagram showing supported interfaces,
• a class diagram showing the domain classes of which the component comprises
• sequence diagrams showing typical usage of the component
• sequence diagrams showing the object interactions within the component
• one or more ERD diagrams showing a relational database schema used by the component to persist data.
  

Imagine that these documents are scattered across a package hierarchy according to their type rather than grouped by component. In this case it is not immediately obvious how to set the scope of a template or iterator sections to achieve what we need. Adding a stereotype to each diagram in the model to indicate which component it belongs to is tedious. Fortunately Together diagrams can contain links or, in Together terminology, shortcuts to other diagrams.

Therefore, we can create a new diagram and add to it shortcuts to all the other diagrams we want as part of the document. Our new diagram is acting as a container for links to the contents of the documents. This strategy has an additional benefit. We can use the inspector pane properties of the containing diagram to hold information like the title and short introductory description for the document.

With our document diagram open and selected, the Current Diagram scope in the Generate Documentation Using Template dialog box can be used. However, there is still a slight gotcha. We have to remember that the element iterator iterating over the contained diagrams must have the Include Shortcuts property on the Scope tab switched on otherwise the iterator will ignore all the referenced diagrams in our document diagram.