30.2. Create UML diagrams with MagicDraw

30.2.1. Organisation
30.2.2. Classes
Data layer classes
Core layer classes
30.2.3. Diagrams
Create a new diagram
Visual appearance and style
Save diagram as image

UML or UML-like diagrams are used to document the relationship of classes in the Core API. To create the diagrams we use the community edition (version 12.5) of a program called MagicDraw. This is a Java program and it should be possible to run it on any platform which has at least a Java 1.5 run-time. To get more information about MagicDraw and to download the program go to their website: http://www.magicdraw.com/

30.2.1. Organisation

All classes and diagrams are in a single UML file. It can be found at <base-dir>/doc/src/uml/baseuml.mdzip

Everything in MagicDraw has been organised into packages and modules. At the top we have the Core layer and the Data layer. The Java module is for classes that related to the Java programming language, such as Map and Set that are not pre-defined by MagicDraw.

Figure 30.1. MagicDraw organisation

MagicDraw organisation

30.2.2. Classes

New classes should be added to one of the sub-packages inside the Data layer/Classes or Core layer/Classes modules. It is very simple:

  1. Select the sub-package in the overview and click with the right mouse button.

  2. Select the New elementClass menu item in the menu that pops up.

  3. The overview will expand to add a new class. Enter the name of the class and press enter.

Data layer classes

If you added a class to the data layer you also need to record some important information.

  • The database table the data is stored in

  • If the second-level cache is enabled or not

  • If proxies are enabled or not

  • The superclass

  • Implemented interfaces

  • Simple properties, ie. strings, numbers, dates

  • Associations to other classes

To achieve this we have slightly altered the meaning of some UML symbols. For example we use the access modifier symbols (+, ~ and -) to indicate if a property is updatable or not. Some of the information needed is specified as tagged values that can be attached to a class. Double-click on the new class to bring up it's properties dialog box. Switch to the Tags configuration page.

Figure 30.2. Setting tagged values

Setting tagged values

We have defined the following tags:

table

The name of the database table where the items should be stored.

cache

The number of items to store in the second-level cache of Hibernate. Only specify a value if caching should be enabled.

proxy

A boolean flag to indicate if proxies should be used or not.

extends

Select the superclass of this class.

implements

Specify which interfaces the class implements. To save space we use the following one-letter abbreviations:

  • A = AnnotatableData

  • B = BatchableData

  • D = DiskConsumableData

  • E = ExtendableData

  • F = FileAttachableData

  • G = RegisteredData

  • L = LoggableData

  • N = NameableData

  • O = OwnableData

  • R = RemoveableData

  • S = ShareableData

  • T = SystemData

discriminator-value

Used for classes that share the underlying database table. The discriminator value is used so that Hibernate knows which subclass to create.

Simple properties are strings, numbers, dates, etc. that are part of an object. Properties are entered as attributes of the class. The easiest way to enter properties are by typing directly in a diagram. It can also be done from the Attributes configuration page.

Each attribute must have information about:

  • The name of the attribute, ie. the name of the get/set method without the get or set part and starting with a lowercase letter.

  • The data type: enter or select the Java object type in the Type selection list.

  • If null values are allowed or not. Specify a multiplicity of 1 if a non-null value is required, but only if the underlying datatype can hold null values.

  • If it is modifiable or not. From the Visibility list, select one of the following:

    • public (+): the attribute is modifiable. This translates to public get and set methods.

    • package (~): the attribute can only be set once. This translates to public get and set methods and an update="false" tag in the Hibernate mapping.

    • private (-): the attribute is private (will this ever be used?). This translates to package private get and set methods.

Figure 30.3. Class attributes

Class attributes

Associations to other classes are easiest created from a diagram view by drawing an Association link between the two classes. The ends should be given a name, multiplicity and visibility should be selected. For the visibility we use the same options as for attributes, but with a slightly different interpretation.

  • public (+): the association is modifiable. This translates to public get and set methods for many-to-one associations. Many-to-many associations must have a package private set method since the set or map must never be replaced.

  • package (~): same as public but the association cannot be changed once it has been created. For many-to-one associations an update="false" tag in the Hibernate mapping should be used. For many-to-many association there is no corresponding tag. It will be the responsibility of the core to make sure no modifications are done.

  • private (-): this is the inverse end of an association. Only used for one-to-many and many-to-many associations and translates to package private get and set methods.

If the association involves a join table (many-to-many) the name of that table should be entered as a tagged value to the association.

If the association have values attached to it, use the Association class link type and enter information about the values in the attached class.

A lot more can be said about this, but it is probably better to have a look at already existing diagrams if you have any questions. The authentication overview shown below is one of the most complex diagrams that involves many different links.

Figure 30.4. Authentication UML diagram

Authentication UML diagram

Core layer classes

TODO

30.2.3. Diagrams

Create a new diagram

New diagrams should be added to one of the sub-packages inside the Data layer/Diagrams or Core layer/Diagrams modules. It is very simple:

  1. Select the sub-package in the overview and click with the right mouse button.

  2. Select the New diagramClass diagram menu item in the menu that pops up.

  3. The overview will expand to add a new diagram. A new empty diagram frame is also opened on the right part of the screen. Enter the name of the diagram and press enter.

[Note] Only class diagrams are fully supported

The community edition of MagicDraw only has full support for class diagrams. The other diagram types has limitations, in the number of objects that can be created.

To display a class in a diagram, simply select the class in the overview and drag it into to the diagram.

Visual appearance and style

We have defined several different display style for classes. To set a style for a class right click on it in a diagram and select the Symbol properties menu item. In the bottom of the pop-up, use the Apply style selection list to select one of the predefined styles.

  • Data class: Use this style for all primary data classes in a diagram. It will display all info that we are interested in.

  • External class: Use this style for related classes that are actually part of another diagram. This style will hide all information except the class name. This style can be used for both data layer and core layer classes.

  • Association class: Use this style for classes that hold information related to an association between two other classes. Classes with this style are displayed in a different color. This style can be used for both data layer and core layer classes.

  • Core class: Use this style for all primary core classes in a diagram. It will display all info that we are interested in.

Save diagram as image

When the diagram is complete, save it as a PNG image in the <base-dir>/doc/src/docbook/figures/uml directory.