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/
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.
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:
-
Select the sub-package in the overview and click with the right mouse button.
-
Select the menu item in the menu that pops up.
-
The overview will expand to add a new class. Enter the name of the class and press enter.
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.
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.
-
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.
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:
-
Select the sub-package in the overview and click with the right mouse button.
-
Select the menu item in the menu that pops up.
-
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]](../../gfx/admonitions/note.png) |
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.
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 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.