Tutorial

Modeling of software and systems
by using UML Profiles

Tutorial

UML Profiles: Customized Modeling with UML Lab

While the UML provides various generic concepts for software and systems modeling, it cannot cover all imaginable application scenarios out of the box. Instead, it can be extended with Profiles to add custom model elements to suit your needs. This tutorial shows how to create profiles with UML Lab and how to use them for code generation and reverse engineering.

We will extend our UML model with a simple validation mechanism that allows us to narrow down the valid length of string attribute values. We will then adapt the code generation so that the generated code will log a warning whenever a value outside the valid range is set.

Prerequisites

This tutorial assumes basic familiarity with UML Lab. If you have not taken the UML Lab Tour yet, this might be a good time to get familiar with UML Lab's core functionality. You can start the tour by choosing Help > Cheat Sheets… and selecting UML Lab Tour from the list.

Furthermore, code styles and template editing are explained in greater detail in the CodeStyles tutorial. It is recommended to start there if you are not already familiar with these concepts.

Contents

  1. Setting up the example
  2. Editing the UML profile
  3. Applying stereotypes
  4. Profiles and code generation

Setting up the example

This tutorial builds upon the CodeStyles tutorial and refers to the code style created there. If you have not followed that tutorial, you should import the sample solution. Choose File > New > Example… > Logger Code Style - stage 1 to do so.

In addition, we'll need some sample code to best illustrate the effects of our customizations. So import the Code Style Example as explained in the Code Style tutorial. Let UML Lab reverse engineer the code to get an initial model and class diagram out of the box.

Editing the UML profile

For every code style project, a UML Profile containing its CodeStyle Stereotypes is automatically created. To add the custom model elements required for our validation mechanism, we will extend the Logger profile. So please open the Logger.profile.umlcd diagram file in the Logger project's /uml/ folder.

We will start by creating a new Stereotype that will define the length restrictions for string attributes. Stereotypes are used in profiles to extend existing UML elements with additional properties and references or refine their meaning.

To create a Stereotype, right-click into the empty diagram and drag a box as shown in the screenshot below. Release the mouse button and select Stereotype from the context menu. Enter ValueChecked to name the new Stereotype. To specify the length restrictions, we will also need attributes for min and max length. Just type min:int and press Enter twice to create an attribute named min of type int. Repeat for the max attribute.

Next, we need to decide what UML elements the stereotype should be applicable to. Stereotypes cannot be used on their own in a model. Instead, they are always applied to another model element by means of an Extension.

The ValueChecked stereotype is intended to augment our model's attributes. Therefore, we want to apply it to the Property metaclass that represents attributes in the UML. To do so, we first need to add Property to the diagram. Right-click on the editor to bring up the context menu and select Add/Remove metaclass.

In the dialog, double-click Property on the left side to add it to the referenced metaclasses on the right. To find Property more easily, you can enter a prefix such as prop in the textbox above to filter the list. Click OK to close the dialog.

Since the Property metaclass is quite large, collapse the displayed attribute and operation sections by clicking their less labels.

Let's go ahead and associate our ValueChecked stereotype with the metaclass. Using the right mouse button, drag a line from the stereotype to the Property metaclass. Then select Create Stereotype Extension from the context menu.

Yatta! Our profile is already finished. It should look like the screenshot below. Before continuing, please save the diagram to make the changes available in other models.

Applying profiles to new models

Let's see how to use our new stereotype in a model. Start by opening the class diagram of the Code Style example project. To use the ValueChecked stereotype in this model, we need to make sure that the Logger profile is applied. If you followed the CodeStyles tutorial this should already be the case. Click on the diagram background and open the Profiles tab in the Properties View. Make sure that the Logger profile is in the Applied list to the left. Otherwise apply it by double-clicking it in the Available list to the right.

Note that profiles are applied automatically if a code style defined inside is used. So choosing the Logger code style for any element in the diagram will perform the steps above automatically. Additionally, profiles get applied by UML Lab if a matching code style is found in the source code during reverse engineering.

Applying stereotypes

Once the profile is applied, pick a string attribute from the model to apply the ValueChecked stereotype to. Let's go with the companyName attribute in the Company class for instance. After selecting it in the diagram, go to the Properties View again and open the Stereotypes tab. On the right side, the new stereotype shows up as LOGGERStyle::ValueChecked in the Applicable list of stereotypes. Double-click it to apply the stereotype.

To configure the min and max properties of the newly applied stereotype, select it from the left list. The property values will now be displayed below, with both min and max initialized to zero. Edit these numbers to specify length restrictions on the attribute value. Let's change them to 5 and 20 for example.

Profiles and code generation

So far, our newly applied stereotype does not have much effect besides annotating our intent to constrain the attribute value in the model. To use stereotypes to full effect, we want to use them in the code generation, too. So let's adapt our Logger style templates to use the ValueChecked stereotype. Open the Attribute.xpt template file from the Logger project's /templates/ folder. Right above the log.log() line we added in the Code Style tutorial, add the template snippet below.

«FOR ValueChecked»
   «IF type.typeString()=="String"»
         if («value» == null) {
            log.log(Level.SEVERE, "null value: «name»");
         }
     «IF min != 0»
     else if («value».length() < «min») {
            log.log(Level.SEVERE, "value too short: «name»");
         }
         «ENDIF»
         «IF max != 0»
         else if («value».length() > «max») {
            log.log(Level.SEVERE, "value too long: «name»");
         }
         «ENDIF»
      «ENDIF»
«ENDFOR»
  • The entire template block should only be evaluated for properties with the ValueChecked stereotype applied. The FOR block is shorthand for checking whether this is the case. Note that this is a non-standard language construct added by UML Lab's Xpand++ extension.
  • In addition to the stereotype being applied, this template block should only be considered for primitive String attributes. For simplicity, we only check the type name here.
  • The «value» variable identifies the parameter name of the setter method the code is generated for. It is defined as part of a LET block surrounding the current code position and defaults to the name "value". However, for reverse engineered code, the correct parameter name found in the source is detected and used here.
  • Inside a «FOR » block, properties of the block's context type can be accessed without qualification. This way, the «IF» condition can directly refer to the ValueChecked stereotype's min attribute. It ensures that the lower bound check of our length validation is only generated if its value is not 0.
  • The generated Java code checks the parameter value's length against the constraint specified with our ValueChecked stereotype. It will log an error message if the value is shorter than requested.

The final template should look as follows:

Now, let's put it to action in our example model. Make sure that the Company class uses the Logger Code Style. If you are not using a reverse engineered model, you might need to change the code style in the Properties View. Save the diagram to generate source code using the new templates.

Take a look at the source code of the Company class. As you can see in the screenshot below, the sources now contain the additional code for the stereotype applied in the UML model. Note how UML Lab synchronizes model and code - even for our custom stereotype! Edit the length value in the Java file or remove the lower / upper bound checks. When saving the Java file, you will notice that the new bounds are applied in the model as well. Removing all value checks will remove the ValueChecked stereotype from the UML attribute. Likewise, pasting the code into another string attribute's setter will apply the stereotype in the model accordingly.

A sample solution of this tutorial is provided as another example. You can select File > New > Example… > Logger Code Style - stage 2 to import the example code style into the workspace if you want to review it.