Revision as of 00:06, 14 October 2011

Copyright © 2004, 2011 International Business Machines Corp. and CEA

Summary

This article describes how to work with profiles using the UML2 plug-ins for Eclipse. In particular, it gives an overview of how to create and apply profiles (and their contents) both programmatically and by using the sample UML editor.

Kenn Hussey and James Bruck
Last Updated: October 13, 2011

Prerequisites

To start using UML2 (and to follow along with the example in this article), you must have Eclipse, EMF, and UML2 installed. You can either download the Modeling Tools Package or follow these steps:

1. Download and run Eclipse.
2. Select the Help > Install New Software… menu item.
3. Select a software site to work with, e.g., Indigo - http://download.eclipse.org/releases/indigo.
4. Expand the Modeling tree item.
5. Select UML2 Extender SDK and press the Next > button.
6. Review the install details and press the Next > button.
7. Accept the terms of the license agreement and press the Finish button.
8. Restart Eclipse when prompted to do so.

At this stage, UML2 and all dependencies should be installed.

Introduction

This article will walk you through the basics of creating and applying profiles using UML2. Using a subset of the Ecore profile (see below) and the model we described in the “Getting Started with UML2” article [1] (the ExtendedPO2 model, shamelessly “borrowed” from the EMF “bible” [2]) as an example, we’ll look at what’s involved in creating some of the more common elements that make up a profile. For each type of element, we’ll first explain the creation process using the sample UML editor and explore how to accomplish the same thing using Java code. Then we’ll look at what’s involved in applying profiles and stereotypes to models. The ExtendedPO2 model is shown below.

Getting Started

Before getting started, you’ll need to create a simple project in your workspace. This project will serve as the container for the profile that we’ll create using the UML editor. To create a simple project for this article, follow these steps:

1. Select the Window > Open Perspective > Other… menu item.
2. Select the Resource perspective and press the OK button.
3. Select the File > New > Project... menu item.
4. Select the Project wizard from the General category and press the Next > button.
5. Enter a project name (i.e., “Introduction to UML2 Profiles”), and press the Finish button.

At this point your workspace should look something like this:

OK, that should be enough to get us going with the UML editor. Now, to follow along with the programmatic approach to creating profiles, we’ll assume that you’ve created a Java class (named, say, “IntroductionToUML2Profiles”) in which you can write some code to construct our sample profile. The code snippets we’ll show assume you’ve defined the following utility methods to give the user information on the program’s status:

     public static boolean DEBUG = true;
 
     protected static void out(String output) {
 
         if (DEBUG) {
             System.out.println(output);
         }
     }
 
     protected static void err(String error) {
         System.err.println(error);
     }

A static debug flag can be used to enable or disable verbose information printed to the system’s output stream. Errors will always be printed to the system’s error stream.

All righty then! In each of the following subsections, we’ll look at how to create or manipulate a different kind of UML element, starting with profiles.

Creating Profiles

At the root of every UML2 profile is a profile element. It defines limited extensions to a reference metamodel (i.e., UML) with the purpose of adapting the metamodel to a specific platform or domain (e.g., EMF). Metaclasses from the reference metamodel are extended via stereotypes, which are defined as part of profiles. To create a profile using the UML editor, follow these steps:

1. Select a project (i.e., Introduction to UML2 Profiles) in the Project Explorer view and select the File > New > Other... menu item.
2. Select the UML Model wizard from the Example EMF Model Creation Wizards category and press the Next > button.
3. Enter a file name (i.e., “Ecore.profile.uml”) and press the Next > button.
4. Select Profile for the model object and press the Finish button.
5. Select the Window > Show View > Properties menu item.
6. Select the <Profile> element in the UML editor.
7. Enter a value (i.e., “ecore”) for the Name property in the Properties view.

By convention, resources that contain profiles end with a .profile.uml file extension in UML2.

At this point your workspace should look something like this:

Let’s look at how to perform the same task using Java code. The code snippet below shows a method that programmatically creates and returns a profile with a specified name.

     protected static Profile createProfile(String name) {
         Profile profile = UMLFactory.eINSTANCE.createProfile();
         profile.setName(name);
 
         out("Profile '" + profile.getQualifiedName() + "' created.");
 
         return profile;
     }

First, we ask the UML factory singleton to create a profile, and we set its name. Then, we output information to the user to let them know that the profile has been successfully created. Finally, we return the profile. You’ll notice most, if not all, of the code snippets in this article will follow this pattern – create the element (and set some properties on it), inform the user, and return it.

OK, let’s see this method in action. For example, we could create a profile named ‘ecore’ as follows:

         Profile ecoreProfile = createProfile("ecore");

Importing Primitive Types

Just like a class, a stereotype may have properties, which may be referred to as tag definitions. The types of these properties may be pre-defined in (domain-specific) libraries referenced by the profile. A profile can be made to reference primitive types from libraries (such as those provided in the org.eclipse.uml2.uml.resources plug-in) by creating an import relationship between the profile and the primitive type. To import a primitive type using the UML editor, follow these steps:

1. Select a package (i.e., <Profile> ecore) in the UML editor.
2. Select the UML Editor > Package > Import Type... menu item.
3. Choose a primitive type (i.e., PrimitiveTypes::Boolean), press the Add button, then press the OK button.

Import the other required primitive type (PrimitiveTypes::String) into the Ecore profile using the UML editor.

At this point your workspace should look something like this:

Let’s look at how to perform the same task using Java code. The code snippet below shows a method that programmatically imports the primitive type with a specified name from the UML primitive types library into a specified package and returns it.

     protected static PrimitiveType importPrimitiveType(org.eclipse.uml2.uml.Package package_, String name) {
         Model umlLibrary = (Model) load(URI.createURI(UMLResource.UML_PRIMITIVE_TYPES_LIBRARY_URI));
 
         PrimitiveType primitiveType = (PrimitiveType) umlLibrary.getOwnedType(name);
 
         package_.createElementImport(primitiveType);
 
         out("Primitive type '" + primitiveType.getQualifiedName() + "' imported.");
 
         return primitiveType;
     }

Here we load the model library containing the UML primitive types (Boolean, Integer, Real, String, and UnlimitedNatural) using a utility method (described later) and a URI defined on the UMLResource interface. Next, we retrieve the desired (owned) primitive type from the model by name using one of the convenience methods defined in the UML2 API. Finally, we invoke another convenience method to create the element import relationship between the package and the element (with default public visibility), notify the user, and return the primitive type.

The UML resources plug-in (org.eclipse.uml2.uml.resources) provides several model libraries (which by convention have a .library.uml file extension) that contain commonly used primitive types, such as those defined by Java and EMF (in addition to those defined by UML™ itself). These libraries can be accessed using URIs defined on the UMLResource interface, as shown above.

In UML2, a method of the form get<feature name>(String) exists for every feature that can contain or reference named elements. In this case, the package has a feature (ownedType) that can contain types, so we pass the unqualified name of the type we are looking for to the getOwnedType(String) convenience method. Behind the scenes, the package will iterate over all of its owned types and return the first one that it finds that has the specified (unqualified) name.

OK, let’s see this method in action. For example, we could import the primitive type named ‘Boolean’ into profile ‘ecore’ as follows:

         PrimitiveType booleanPrimitiveType = importPrimitiveType(ecoreProfile, "Boolean");

Write code to programmatically import the other required primitive type (i.e., ‘String’) into the Ecore profile.

Creating Enumerations

As with packages, profiles can contain enumerations. An enumeration is a kind of data type whose instances may be any of a number of user-defined enumeration literals. To create an enumeration using the UML editor, follow these steps:

1. Select a profile (i.e., <Profile> ecore) in the UML editor.
2. Select the New Child > Owned Type >'Enumeration' option from the context menu.
3. Enter a value (i.e., “VisibilityKind”) for the Name property in the Properties view.

Create the other enumeration (i.e., “FeatureKind”) for the Ecore profile using the UML editor.

At this point your workspace should look something like this:

Let’s look at how to perform the same task using Java code. The code snippet below (from the GettingStartedWithUML2 class) shows a method that programmatically creates and returns an enumeration with a specified name in a specified package.

     protected static Enumeration createEnumeration(org.eclipse.uml2.uml.Package package_, String name) {
         Enumeration enumeration = (Enumeration) package_.createOwnedEnumeraton(name);
 
         out("Enumeration '" + enumeration.getQualifiedName() + "' created.");
 
         return enumeration;
     }

Here we call the createOwnedEnumeration(String) convenience factory method to ask the package to create a primitive type with the specified name as one of its packaged elements.

OK, let’s see this method in action. For example, we could create an enumeration named ‘VisibilityKind’ in profile ‘ecore’ as follows:

         Enumeration visibilityKindEnumeration = GettingStartedWithUML2.createEnumeration(ecoreProfile, "VisibilityKind");

Write code to programmatically create the other enumeration (i.e., ‘FeatureKind’) for the Ecore profile.

Creating Enumeration Literals

An enumeration literal is a user-defined data value for an enumeration. To create an enumeration literal using the UML editor, follow these steps:

1. Select an enumeration (i.e., <Enumeration> VisibilityKind) in the UML editor.
2. Select the New Child > Owned Literal > Enumeration Literal option from the context menu.
3. Enter a value (i.e., “Unspecified”) for the Name property in the Properties view.

Create the remaining enumeration literals for the Ecore profile (i.e. “None”, “ReadOnly”, “ReadWrite”, “ReadOnlyUnsettable”, and “ReadWriteUnsettable” for <Enumeration> VisibilityKind; “Unspecified”, “Simple”, “Attribute”, “Element”, “AttributeWildcard”, “ElementWildcard”, and “Group” for <Enumeration> FeatureKind) using the UML editor.

At this point your workspace should look something like this:

References

[1] K. Hussey and J. Bruck. “Getting Started with UML2”. International Business Machines Corp. and CEA, 2004, 2011.

[2] F. Budinsky, D. Steinberg, E. Merks, R. Ellersick, and T. J. Grose. Eclipse Modeling Framework. Pearson Education, Inc., Boston, MA, 2003.