Using UML Lab COMP 310 Using UML Lab 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: UML Lab Preferences Settings <<== Do this first! Create the Initial Class Diagram Create Subsequent Class Diagrams Saving Edited Diagrams and Reflecting those Changes in the Code Editing Code and Reflecting those Changes in the Diagram Adding Existing Classes or Interfaces to a Diagram Adding New Classes or Interfaces to a Diagram Adding Inheritance Relationships Between Classes and/or Interfaces Adding Association Relationships Between Classes Adding Fields to Classes Adding Methods to Classes and Interfaces Creating Constructors Force UML Lab to Recreate the Diagram Based on the Current Code Tips and Traps 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/ UML Discussion Forum: http://forum.yatta.de/ UML Product Support Home: http://www.yatta.de/en/support/ 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: Internet Explorer 9: Right-click the page and select "Translate with Bing". Firefox: You will need to install a plugin with translation capability, such as the Google Toolbar, FoxLingo, etc. Chrome: Translation is built-in and you will be automatically prompted for translation. 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: Classdiagram Editor: Default association cardinality Source End = 1..1 Target End = 1..1 This will cause the drawing of an aggregation line to create a single field of the target type rather than a Set of the target type. Code Generator Apply pretty-printer to generated code = checked Generate code automatically on save = checked Layout Manhattan router -- Optional. This is personal preference. This choice will draw all lines neatly using all right angles, creating diagrams that are easier to read. Look and Feel Icon Scheme = No Icons -- this will make UML Lab use standard notations for private and public visibility. Product License This must be done on-campus! Check the "I am an academic user" box Fill in the license key from the course materials, e.g. from a resources page in Canvas. Click the "Activate academic license" button Click the "Apply and Close" button to save the changes. (Click the image for a larger version) 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: Right-click your "src" folder in the Eclipse Package Explorer. Select "New/Other...". Scroll down until you see "UML Lab" and expand it. Select "UML Model and Class Diagram" and click "Next". 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". 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". 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". 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". 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: 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. Select "New/Other...". Scroll down until you see "UML Lab" and expand it. 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". Click the "Browse" button to find the model file you created with yoru initial class diagram (see above). Click "Next". 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". 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: 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: 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. Right-click the root of the displayed tree and select "Close Model". This will close any open diagrams and shut down the modeling engine. UML Lab will no longer check for consistency between the Java code and its internal model. When you re-open a UML diagram, you will be asked (at least the first time) if you want to reverse engineering the existing code -- do this, as this will update the UML Lab internal model with the latest code you've written. Closing a UML Lab diagram is NOT the same as closing its model! Simply closing a diagram will NOT 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. In the palette, click the type of item you want (Class or Interface) and then click on an open spot on the diagram. 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. Don't forget to specify the package for the new class or it will be put into the "default package"! To specify the package in which the new class will reside, set the "Namespace" field in the new class or interface's Properties. The format of the namespace is "[Project Name]::[package name]", e.g. "HW01::view" 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. Be sure that the line is selected in the diagram so its properties show up in the Property editor. In the UML tab, in the Summary, uncheck the two "to-many" check boxes. In the Properties tab: At the "Association end" for the referenced class (the right-hand one probably), set the multiplicity to "1..1" or whatever number you wish. Change the "Name" to the desired field name. Select "Aggregation" under Aggregation. One the diagram, right-click the text box that is at the end near the open diamond (not the arrowhead), and click "Hide Element". 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 Prefacing the name with a minus sign, "-", will set the field's visibility to private instead of the default public. Sometimes you have to press "Enter" twice to get the new field to show up in the class. 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 void returns can be created by simply omitting the colon and return type. Prefacing the name with a minus sign, "-", will set the method's visibility to private instead of the default public. Sometimes you have to press "Enter" twice to get the new method to show up in the class. 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: Click the "Add" button. Type in the name of the parameter and press Enter. Type in the type of the parameter and press Enter. You MUST press Enter after each setting or the values you typed will not be accepted! Repeat for all the desired input parameters. Return types can also be set by changing the "direction" value to "return" instead of "in". Creating Constructors Creating a constructor is very similar to making a method, with one extra step: 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. 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. 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. Close the UML Diagram Save everything. Right-click the model file (XXX.uml) and select "UML Lab/Reparse All Files" 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 Sometimes information gets orphaned in the UML Lab model file (XXX.uml) and removing those orphaned items can sometimes alleviate model errors. 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 model file and fully expand the first section, which should be labelled: "platform/resource/..." Delete the following items: "<
> ..." -- these give the error "This element is not resolved and no code will be generated for it " dangling-refs Delete any sub-entries EXCEPT for the ones labelled "Change Description" "<>" where there is no additonal information associated with the tag. You will want to reload the model at this point. 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 Under "Properties", make sure that For the class end that should have the field: "Navigable" is NOT set "Aggregation" = None For the class end that is being referenced: "Navigable" IS set "Aggregation" = Aggregation "Multiplicity" = 1..1 for a single reference (as opposed to a collection of references) Under "Stereotypes", added "Reference" to the "Applied Stereotypes" Remove any unwanted gettor and settor methods. Missing getters and setters in the UML Diagram and seemingly incorrect field visibility By default, UML Lab does not show the getters and setters for fields in the UML diagram. The visibility shown for the field is the visibility of the getter and setter, not the visibility of the field. Sometimes, if the getter and/or setter was coded by hand, UML Lab may not recognize it as being associated with the field and thus will display it. If you add a field using UML Lab, gettors and settors will automatically be added. Much of the time, you will want to delete these undesired gettors and settors. 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: Right-click the class in the diagram and select "Collapse/Expand" and cycle through Collapse All (not showing any fields or methods) then Expand All (show the fields and methods) Right-click the class and select "Update from classpath" to reload the class from the source code. Highlight the class containing the field and click the little "Show associated" icon that appears on the upper left corner of the class (the 3rd icon from the left, a white box linked to a green box) Right-click the field in the class diagram and select "Refactor/Convert to Reference". 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[], Set or the like, is First create the association as a field that references a single object. Then convert the field into a non-unit multiplicity: Go to the Properties of the association line and open the the UML tab. In the Summary, at the end of the line that best describes the field you made, check the "to-many" box. 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. 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! 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 data = new ArrayList(); 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 data = new ArrayList(); 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
