COMP 310

Using UML Lab

    Current Home  Java Resources  Eclipse Resources

UML Lab is a commercial UML diagramming tool produced by Yatta Solutions in Germany.   UML Lab supports round-trip engineering, i.e. creating diagrams from code as well as creating code from diagrams.

Quick links:

WARNING: KNOWN BUG IN UML LAB

As of 8/29/21, UML Lab Modeling IDE v. 1.24.0: UML Lab is unable to properly parse interfaces that contain static methods. UML Lab will display error messages saying that it cannot parse the files and its code auto-generator will attempt to either remove the methods completely or replace them with invalid Java code.

At the moment, the only work-arounds are:

STRONG RECOMMENDATION:

To prevent UML Lab from attempting to process classes/interfaces that are not part of a diagram and in particular, classes/interfaces that it is unable to parse, a highly recommended practice is to prevent UML Lab from reading the entire codebase when first creating a UML Lab model (.uml file). This occurs when such one is first starting off and one has selected New/UML Model and Class Diagram from the right-click menu in Eclipse's Package Explorer tab.

By default, UML Lab selects the entire source folder to parse into the model file. Unchecking all the boxes when presented with the Populate model and diagram dialog window will prevent UML Lab from reading in unwanted files into the model.

Now, only the classes and interfaces dragged onto a diagram will be parsed into the UML Lab model.

 


Getting Help in UML Lab

In Eclipse: Go to Help/Help Contents/UML Lab User Guide 

 

UML Lab Home page: http://www.uml-lab.com/en/uml-lab/

Unfortunately, most of the discussion postings are in German, so if you cannot read German, you can use the built-in translation capabilities of your browser to get a pretty usable translation of the postings:

 

UML Lab runs slightly differently than many other diagramming tools.   UML Lab creates a "model" which holds all of the relevant relational information about the Java classes and interfaces needed to create UML diagrams.   This is the ".uml" file that is created.   This model is NOT a UML diagram however.    Separately, UML Lab creates a UML class diagram from the model.   There may be many class diagrams created from a single model.   The class diagrams are the ".umlcd" files.

To create a UML diagram using UML Lab, you must have BOTH a model and a class diagram file!    However, only one model file may be needed for multiple class diagrams.

Important Note:  UML Lab does not instantaneously create code when the elements of a diagram are changed.   Changes to code are not created until the diagram is saved.

 

UML Lab Preferences Settings

The UML Lab preferences can be found in the Eclipse preferences, under the main Eclipse menu:   Window/Preferences/UML Lab

It is highly recommended that you make the following changes to the default settings:

 

 

(Click the image for a larger version)
screen shot

 

Tip: If you are having trouble selecting entities in UML Lab, be sure that you have selected the "arrow" pointer at the top of the palette.    The "universal tool", whose icon looks like a little blue gear, can also be used.   This tool uses shortcuts to bypass keystrokes for common tasks.   See the description under Concepts/Class Diagram Editor/Palette/Universal Tool in the UML Lab help topics in Eclipse.

Create the Initial Class Diagram

We need to create both the model file and the class diagram file in this situation:

  1. Right-click your "src" folder in the Eclipse Package Explorer.
  2. Select "New/Other...".   Scroll down until you see "UML Lab" and expand it.
  3. Select "UML Model and Class Diagram" and click "Next".
  4. In the "New UML Model" dialog, select the folder to put the model file in.  The "src" folder is recommended.   By default, the model file name will be "[Eclipse project name].uml".   Click "Next".
  5. In the "Create Diagram" dialog, select "Single Class Diagram", select the folder that best represents the contents of the diagram you wish to create, usually the package you are creating a diagram of.    Change the name of the file to more accurately reflect the contents of the diagram, e.g. "mvc.umlcd" or "strategies.umlcd".    Click "Next".
  6. In the "Populate model and diagram" dialog, by default, the src folder should be "greyed", i.e. have a filled box next to it.   Take this default, which will put all the classes in the model, but none in the diagram yet.  Click "Finish".
  7. When the new, empty class diagram opens initially, a "Configure Class Diagram" dialog should appear.   In this dialog, transfer the desired classes/interfaces from the "Available elements" to the "In diagram" lists.  Click "OK".
  8. An automatically laid-out UML diagram should be created.   Additional classes/interfaces can be added to the diagram simply by dragging them from the Package Explorer.

 

Create Subsequent Class Diagrams

We only need to create the diagram file in this situation because the model file was already made:

  1. Right-click your desired folder in the Eclipse Package Explorer to hold the class diagram.    Usually this is the package folder that holds the bulk of the classes in the diagram.
  2. Select "New/Other...".   Scroll down until you see "UML Lab" and expand it.
  3. In the "New Class Diagram" dialog, select the folder that best represents the contents of the diagram you wish to create, usually the package you are creating a diagram of.    Change the name of the file to more accurately reflect the contents of the diagram, e.g. "mvc.umlcd" or "strategies.umlcd".   
  4. Click the "Browse" button to find the model file you created with yoru initial class diagram (see above).   Click "Next".
  5. In the "Select root package" dialog, select the package that matches the folder in which the class diagram was placed.   This way, any new classes created will, by default, be created at the same location as the diagram.   Click "Finish".
  6. An automatically laid-out UML diagram containing all the classes and interfaces in the selected package should be created.   Additional classes/interfaces can be added to the diagram simply by dragging them from the Package Explorer.

Saving Edited Diagrams and Reflecting those Changes in the Code

When you first save a diagram, UML Lab will ask you if wish to automatically generate the associated code for the diagram.   Check the option to always generate code upon saving.

When UML Lab generates code, existing code in .java files will be modified and new files created if necessary.

You can manually generate code without saving by right-clicking the diagram and selecting "Generate Code".

 

Editing Code and Reflecting those Changes in the Diagram

Any changes to code will automatically be reflected in a diagram when the diagram when the diagram is first opened.   However, sometimes the UML Lab model engine gets confused as to whether to code in the Java file is newer or older than the code in the model and will erroneously try to overwrite the code you just wrote directly into the Java file.

However, you must be a bit careful if you edit the code while the diagram is while UML Lab's automatic code generator is running.   You may get the following warning message:  

confusing warning message

or you may get the following:

You may get a warning dialog like the above that says that the code is open in the diagram editor and asks if you want to overwrite the opened code  and to discard your changes.   Select No or Cancel!   This will cause the code you just edited to be reflected in the diagram.  Otherwise, your code edits will be lost.

Often, you will get the above warnings every time you save your Java code file, even if the UML Lab diagram is not open.   The reason is because the underlying UML Lab model engine is still running, trying to synchronize the code.   If you know you will not be using the class diagram for a while, you should shut down the UML Lab model engine:

  1. Open the UML Lab perspective and click on the "UML Lab Tree" tab on the left.  This tree shows a hierarchal view of all the UML modeling components that are that UML LAb modeling engine knows about.
  2. Right-click the root of the displayed tree and select "Close Model".
  3. This will close any open diagrams and shut down the modeling engine.  

If you accidentally do the wrong thing and UML Lab overwrites/deletes your code, you can almost always get your code back by pressing "Ctrl-Z" (Undo).

Adding Existing Classes or Interfaces to a Diagram

Simply drag and drop the items from the Package Explorer to the diagram.

Adding New Classes or Interfaces to a Diagram

Sometimes the UML Lab component palette is hidden from view because it is collapsed.  If you do not see it, click the small arrowhead at the upper right corner of the diagram to expand the palette. (The arrowhead can be hard to see if Eclipse is running in a "dark theme" mode.)

  1. In the palette, click the type of item you want (Class or Interface) and then click on an open spot on the diagram.
  2. Double-click the resulting class or interface box on the diagram to highlight it so that you can edit the name of the class/interface.
  3. Don't forget to specify the package for the new class or it will be put into the "default package"!

Adding Inheritance Relationships Between Classes and/or Interfaces

Inheritance ("Generalization/Realization") relationships are available on the UML Lab palette.    Simply highlight the "Generalization/Realization" relationship, and drag-and-drop (you need to do a click at the end) a line from the sub-class to the superclass, i.e. in the direction of the inheritance arrow.

 

Adding Association Relationships Between Classes

Association or compositional relationships (collectively, "association", "aggregation", "reference" and "composition") and dependency lines are all available on the UML Lab palette.    Simply highlight the desired relationship, and drag-and-drop  (you need to do a click at the end) a line in the direction of the arrow for that sort of relationship, i.e. from the the class with a field that references the other class to that other class in an aggregation line.

Technically, all association relationships in Java are aggregations.   In other languages, such as C++, there is a distinct difference.  

Use the "Reference" line in the Palette as this will cause the least problems with extraneous code being generated.

Fixing UML Labs defaults:

Unfortunately, the default properties for association type lines are not what we generally want, so we have to fix them up a bit.   The following applies ONLY if the relationship refers to a fixed number of associated objects, i.e. 1 or 2, not a collection of objects.

  1. Be sure that the line is selected in the diagram so its properties show up in the Property editor.
  2. In the UML tab, in the Summary, uncheck the two "to-many" check boxes.
  3. In the Properties tab:
  4. One the diagram, right-click the text box that is at the end near the open diamond (not the arrowhead), and click "Hide Element".
  5. UML Lab will auto-generate gettors and settors for the field.   See below on dealing with this.

 

Adding Fields to Classes

To add a field to a class, click on a class in the diagram to select, but not highlight it.  Then simply type the desired name of the field, followed by a colon, ":", and then the type of the field:  fieldName: FieldType

For example:   -count: int   or   position: Point

The visibility of the field can be modified by clicking the light blue rectangle icon to the left of the field name, which will bring the field up in the Property Editor below.  Click the UML tab and select the desired visibility.

SAVE THE DIAGRAM AND LET IT GENERATE THE NEW CODE BEFORE ATTEMPTING TO DISPLAY ASSOCIATION LINES AND/OR REMOVING GETTERS/SETTERS

Bad practice by UML Lab:

Unfortunately, UML Lab auto-generates "gettor" and "settor" functions for any fields that are created.    These methods only show up in the generated code, not on the diagram itself.   This means that UML Lab defaults to breaking the encapsulation of classes, a practice common in "object-based programming" where objects are treated as dumb data containers.    For our purposes, unless there is a clear need for the gettor or settor, one should always delete those auto-generated methods.  

Before you delete the getter and/or setter, set the stereotype of the association line belonging to the field (if there is one) to "Reference", otherwise UML Lab won't show the association line for that field

If the aggregation line is not displaying or not displaying in the desired manner, see the Tips and Traps section below.

Adding Methods to Classes and Interfaces

Adding methods is similar to adding fields: select the class and type the name of the method followed by a set of parentheses, "()" -- input parameters will be added later --, followed by a colon and the return type:    methodName(): ReturnType

For example:   run(): boolean  or  makeFrame(): JFrame or  -setState(): void

The visibility of the method can be modified by clicking the light blue "gear" icon to the left of the method name, which will bring the method up in the Property Editor below. Click the UML tab and select the desired visibility.

Adding input parameters:

To add input parameters to a method, select the entire method by clicking the light blue "gear" icon to the left of the method name in the class.   The properties of that method will appear in the Property Editor below.

Click the "Parameters" tab to show the input parameters for the method:  

Creating Constructors

Creating a constructor is very similar to making a method, with one extra step:

  1. As in making a normal method of a class, highlight the class and create  a method whose name is the name of the class and whose return type is the name of the class.  
  2. After you have define the above method, highlight the whole method and in the Properties pane, under the UML tab, enter "create" (no quotes) in the Keywords input box.

Create a constructor

 

 

Force UML Lab to Recreate the Diagram Based on the Current Code

Sometimes you need to force UML Lab to rebuild its model and resynchronize its model with the actual code.   

  1. Close the UML Diagram
  2. Save everything.
  3. Right-click the model file (XXX.uml) and select "UML Lab/Reparse All Files"
  4. Reopen the UML Diagram

To reparse a single class in the diagram, simply right-click the class and select "Update from classpath".   Be sure to save all your work before asking UML Lab to reparse the file(s).

 

Cleaning up the UML Lab Model

Editing the model file is risky!  You can easily damage your code if something is done incorrectly.   Always commit your project BEFORE attempting to edit the model file!   Do not generate code if there are large errors occurring!

Open the UML Lab Model file (XXX.uml) from inside of Eclipse. The default system editor for this sort of file should display something like this (you may need to expand some sections):

Removing Unparseable or Undesired Classes/Interfaces

UML Lab will constantly try to process all classes and interfaces that it knows about even if they don't appear in any diagrams. Once a class or interface appears in a diagram, it is known to the UML LAb model even if it subsequently removed from the diagram.

Sometimes one needs to remove a class or interface from the UML Lab model file to keep UML Lab from processing that entity. This could be due to a number of reasons, such as the file containing code that UML Lab does not recognize, UML Lab's auto-generated code isn't correct or desired, a bug in the UML Lab processing, etc.

REMOVE THE OFFENDING CLASS/INTERFACE FROM ANY DIAGRAMS FIRST!

  1. Open the model file and fully expand the first section, which should be labelled:  "platform/resource/..."  
  2. Expand the desired <Package> heading
  3. Right-click and delete the desired entries.
  4. Save the model file.

Removing Orphaned and Unrecognized Classes/Interfaces

Sometimes information gets orphaned in the UML Lab model file and removing those orphaned items can sometimes alleviate model errors. 

 

 

Tips and Traps

A class diagram does not reflect the underlying code

A class diagram won't always immediately reflect the changes to the underlying code. 

Make sure that you have saved all your changes!   UML Lab will not pick up any changes until the source code file has been saved.

Once the files have been saved, force UML Lab to reparse all or part of the classes in its model.

 

UML Lab generates fields in both classes when drawing an aggregation (or similar) line

The following settings will make a a proper aggregation line with the open arrowhead pointing at the referenced class and an unfilled diamond at the class with the field.    If your association line does not look right, compare it to the settings below.

Unfortunately, this is the default behavior of UML Lab -- by default it assumes that all aggregations are two-way navigations, that is each class can reference the other.   Things to do to get rid of the unwanted field in the referenced class:    Highlight the association line, then

 

Missing getters and setters in the UML Diagram and seemingly incorrect field visibility

 

Fields with no gettor or settor methods do not show up as lines on the diagram.

This is sometimes caused by the diagram not updating to display the new code or its diagram properties are not properly set.   Try the following:

 

Associations that represent collections do not show up properly

The best way to make an association that represents a collection, e.g. a List<Something>, Something[], Set<Something> or the like, is

  1. First create the association as a field that references a single object.
  2. Then convert the field into a non-unit multiplicity: 
    1. Go to the Properties of the association line and open the the UML tab.
    2.  In the Summary, at the end of the line that best describes the field you made, check the "to-many" box.
    3. Save everything in Eclipse to force code generation (assumes you have the preferences set properly from above).  This will change the type of the field to the last collection type you used, by default, java.util.Set.
    4. Edit the code to change the collection type to the desired type and save everything.  Note the warning below about how UML Lab doesn't want to properly display some types.  Also, be careful about a possible misleading warning from UMLLab about out-of-sync code!
    5. In the Properties of the association, under the "Properties" tab, set the desired multiplicity at the referenced class end.

 

Certain types of fields do not show up as association lines

UML Labs only recognizes certain types of fields, a restriction that is particularly apparent when working with generic collections, such as ArrayLists.   For instance, suppose you made a field like such, in perfectly legal Java syntax:

private ArrayList<MyData> data = new ArrayList<MyData>();

If you had a UML diagram that already had the MyData class on it, an association line pointing at MyData would not appear.

The problem is that UML Lab does not recognize the ArrayList as a generic collection type.    The type that UML Lab understands is the top-level interface for array-type collections, List.   Thus the following code works and shows the association line in the UML diagram:

private List<MyData> data = new ArrayList<MyData>();

Ref:  http://forum.yatta.de/discussion/28/reverse-engineering-generics

 

 

Error: "The association "" is defect: At least two member endsa re required"

This error seems to arise when association lines are somehow "orphaned" in UML Lab's model.  

A technique that seems to have some success in getting rid of those errors is to open the model (XXX.uml) file and search through it looking for and deleting Association definitions that don't have any information associated with them.   After you are done, follow the directions above to reload the model.    See the above instructions on cleaning up the model.

A more drastic measure is to delete the model and class diagram and recreate it.

 

Ref: http://forum.yatta.de/discussion/36/error-the-association-is-defect-at-least-two-member-ends-are-required

"Error: "This element is not resolved and no code will be generated for it (depends on the chosen templates). Substitute occurrences with the correct element."

This error seems to come from orphaned fields, etc in the model.

Either remake the model and diagram or see the above instructions on cleaning up the model.

 

"Not enough free memory available to reverse engineer the source code. Increase the available memory or reverse engineer fewer elements."

Try increasing the amount of memory allocated to Eclipse

 

When creating a new diagram and model from scratch, no classes populate either the model or the diagram

This may also manifest itself as an apparent "rejection" of a class from being placed on the diagram where UML Lab refuses, without an error message, to allow the class to be dropped onto the diagram.

This may be due to a corrupted UML Lab installation, so try re-installing it.

 


© 2017 by Stephen Wong