Revision as of 21:51, 16 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:

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 literal with a specified name in a specified enumeration.

     protected static EnumerationLiteral createEnumerationLiteral(Enumeration enumeration, String name) {
         EnumerationLiteral enumerationLiteral = enumeration.createOwnedLiteral(name);
 
         out("Enumeration literal '" + enumerationLiteral.getQualifiedName() + "' created.");
 
         return enumerationLiteral;
     }

Here we call the createOwnedLiteral(String) convenience factory method to ask the enumeration to create an enumeration literal with the specified name as one of its owned literals.

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

         GettingStartedWithUML2.createEnumerationLiteral(visibilityKindEnumeration, "Unspecified");

Write code to programmatically create the remaining enumeration literals (i.e., ‘None’, ‘ReadOnly’, ‘ReadWrite’, ‘ReadOnlyUnsettable’, and ‘ReadWriteUnsettable’ in enumeration ‘VisibilityKind’; ‘Unspecified’, ‘Simple’, ‘Attribute’, ‘Element’, ‘AttributeWildcard’, ‘ElementWildcard’, and ‘Group’ in enumeration ‘FeatureKind’) for the Ecore profile.

Creating Stereotypes

A stereotype defines how an existing metaclass may be extended, and enables the use of platform- or domain-specific terminology or notation in place of, or in addition to, the ones used for the extended metaclass. Each stereotype may extend one or more classes through extensions as part of a profile. To create a stereotype 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 Stereotype > Stereotype option from the context menu.
3. Enter a value (i.e., “EStructuralFeature”) for the Name property in the Properties view.
4. Select a value (i.e., true) for the Is Abstract property in the Properties view.

Create the remaining stereotypes for the Ecore profile (i.e., “EAttribute” and “EReference”) 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 creates and returns a(n) (abstract) stereotype with a specified name in a specified profile.

     protected static Stereotype createStereotype(Profile profile, String name, boolean isAbstract) {
         Stereotype stereotype = profile.createOwnedStereotype(name, isAbstract);
 
         out("Stereotype '" + stereotype.getQualifiedName() + "' created.");
 
         return stereotype;
     }

Here we call the createOwnedStereotype(String, boolean) convenience factory method to ask the profile to create a stereotype with the specified name as one of its owned members, and set the isAbstract attribute of the stereotype based on the specified boolean argument.

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

         Stereotype eStructuralFeatureStereotype = createStereotype(ecoreProfile, "EStructuralFeature", true);

Write code to programmatically create the remaining (non-abstract) stereotypes (i.e., ‘EAttribute’ and ‘EReference’) for the Ecore profile.

Creating Stereotype Generalizations

Just like classes, stereotypes may be involved in generalizations. A generalization is a taxonomic relationship between a specific classifier and a more general classifier whereby each instance of the specific classifier is also an indirect instance of, and inherits the features of, the general classifier. To create a stereotype generalization using the UML editor, follow these steps:

1. Select a stereotype (i.e., <Stereotype> EAttribute) in the UML editor.
2. Select the New Child > Generalization > Generalization option from the context menu.
3. Select a value (i.e., ecore::EStructuralFeature) for the General property in the Properties view.

Create the other generalization (i.e., between EReference and EStructuralFeature) for the Ecore profile using the UML editor.

Be sure to pick the first ecore::EStructuralFeature item (with a lowercase "ecore") instead of the second one (with an uppercase "Ecore"), which comes from the built-in Ecore profile provided by 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 (from the GettingStartedWithUML2 class) shows a method that programmatically creates and returns generalization between specified specific and general classifiers.

     protected static Generalization createGeneralization(Classifier specificClassifier, Classifier generalClassifier) {
         Generalization generalization = specificClassifier.createGeneralization(generalClassifier);
 
         out("Generalization " + specificClassifier.getQualifiedName() + " ->> " + generalClassifier.getQualifiedName() + " created.");
 
         return generalization;
     }

Here we call a convenience factory method on the specific classifier that creates a generalization as one of its children and sets the general classifier to the specified argument.

OK, let’s see this method in action. For example, we could create a generalization between specific stereotype ‘EAttribute’ and general stereotype ‘EStructuralFeature’ as follows:

         GettingStartedWithUML2.createGeneralization(eAttributeStereotype, eStructuralFeatureStereotype);

Write code to programmatically create the other generalization (i.e., between ‘EReference’ and ‘EStructuralFeature’) for the Ecore profile.

Creating Stereotype Properties

Again just like classes, stereotypes may have properties (attributes). When a stereotype is applied to a model element, the values of the properties may be referred to as tagged values. To create a stereotype property using the UML editor, follow these steps:

1. Select a stereotype (i.e., <Stereotype> EStructuralFeature) in the UML editor.
2. Select the New Child > Owned Attribute > Property option from the context menu.
3. Enter a value (i.e., "isTransient”) for the Name property in the Properties view.
4. Select a value (i.e., PrimitiveTypes::Boolean) for the Type property in the Properties view.
5. Enter a value (i.e., 0) for the Lower property in the Properties view.
6. Select the property (i.e., <Property> isTransient) in the UML editor.
7. Select the New Child > Default Value > Literal Boolean option from the context menu.

Default values for properties (and parameters) are represented as value specifications (first-class objects) in UML™ 2.x. Here we have selected a literal Boolean (whose default value is false) as the default value of our property since its type is Boolean. If the type of the property were String, we’d have used a literal string instead. Once a default value specification has been created, its value can alternatively be set with the owning property selected via the Default property in the Properties view.

Create the remaining stereotype properties for the Ecore profile (i.e., “isUnsettable”, “isVolatile”, “visibility”, “xmlName”, “xmlNamespace”, and “xmlFeatureKind” for <Stereotype> EStructuralFeature; “attributeName” for <Stereotype> EAttribute; “referenceName” and “isResolveProxies” for <Stereotype> EReference) using the UML editor.

Be sure to set the appropriate default value for each stereotype property so that it is consistent with the corresponding property in Ecore. In particular, the default value for the “isResolveProxies” should be a literal Boolean with a value of true instead of the default (!) default value of false. Note also that the types of the “visibility” and “xmlFeatureKind” properties should be the enumerations we created earlier (i.e., ecore::Visibility and ecore::FeatureKind, respectively).

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.