Friday, September 25, 2009

Defining static profiles with Eclipse UML2

Having heard about Eclipse UML2's ability to support the definition of static profiles some while ago, when trying to define such a profile by myself recently, I found out that - even while the feature was built in already some while ago - there is not much documentation around.

Taking my own trial-and-error history as an inspiration, I thought it could be useful to post a small step-by-step tutorial, making things easier for successors. Here it is...
  1. Starting point is the creation of a plug-in project (let's call it 'org.example.staticumlprofile'), containing the profile definition.

  2. Creation and editing of the profile are the next steps. You may create and edit the profile nongraphically by means of the respective wizard and editor provided by the Eclipse UML2 project itself. I prefer to edit it graphically using the Profile Definition Diagram, supported by the UML2 Tools project.

    So let's create a new Profile Definition Diagram named 'StaticUmlProfile.umlprofile' and an underlying UML profile named 'StaticUmlProfile.profile.uml' within a 'model' subfolder of the plug-in project.

    To the created profile, let's simply add a single stereotype, named 'ExampleStereotype', which extends the UML meta-class Class and has a single String-valued attribute named 'exampleProperty'. The result should look something like the following:
  3. Next, the profile has to be defined. That is, in contrast to a dynamic UML profile, static profiles are actually not defined, meaning that neither the 'Profile->Define' diagram context menu of the UML2 Tools Profile Definition Diagram editor, nor the 'Profile->Define' menu entry of the UML2 provided tree-editor is meant to be used here.

    Instead, the profile has to be declared as an Ecore EPackage, so that Java code can be generated. To do so, within the Profile Definition Diagram editor, choose to 'Apply Profile->Ecore' from the diagram context menu (right-click on diagram canvas), then 'Apply Stereotype -> Ecore::EPackage' from whithin the profile context menu (right-click on profile).

    Within the properties view ('TaggedValues' section), specify an Ns URI for the profile (here: 'http://org.example.staticumlprofile/StaticUmlProfile/1.0'), under which it gets registered and can be looked up. To ensure that the generated code has a package prefix reflecting the plug-in project's one (i.e. 'org.example.staticumlprofile') the Base Package and Package Name have to be specified to 'org.example' and 'staticumlprofile' accordingly.

  4. Then, an EMF GenModel is to be created by means of the respective 'EMF Generator Model' wizard:
    On the 'UML Import' page, select to 'Load' the profile, then don't bother with the warnings, you are notified about. It is strongly recommended to NOT apply other processing options than those specified by default (if the 'Duplicate Features' option is e.g. set to 'Process', the 'base_Class' property of the stereotype within the 'StaticUmlProfile.profile.uml' file will be renamed to baseClass' within the corresponding StaticUmlProfile.ecore file, with the consequence that the stereotype will not be properly applicable).On the 'Package Selection' page, 'Ecore' and 'UML' have to be specified as referenced generator models, as we do not want to generate code for them. To obtain a consistent naming of model files, one may also convert the .ecore file name to upper case (as done here).
  5. Next, the generator model may be edited, to specify details of how EMF generates code for the profile. As we have already specified all settings relevant in this example, there is nothing to do here.

  6. Now, code can be generated (ensure to select this from the top node, so all required MANIFEST.MF entries, as well as the plugin.xml with all its required extensions get generated as well).

  7. To have a simple confirmation, that the generated code is indeed used when applying the profile (at runtime), we will perform a slight change within the generated code, by changing the default value of the 'example' property (within 'ExampleStereotypeImpl') to "example" instead of 'null':

  8. To publish the profile, a respective extension ('org.eclipse.uml2.uml.generated_package') has to be added to the plugin.xml, additinally to those extensions automatically generated.

    Ensure that the 'uri' property of the extension is set to the NS Uri specified within the profile, i.e. 'http://org.example.staticumlprofile/StaticUmlProfile/1.0'. The 'location' property has to be an uri pointing to the profile within the 'StaticUmlProfile.profile.uml' file.

    To retrieve the location uri, first open the 'StaticUmlProfile.profile.uml' file in a text editor to obtain the xmi:id of the profile object (here it is '_ds47cam3Ed6HIN9NxFlDEw'):

    The location uri can then be easily specified as a platform plug-in uri, which here corresponds to 'platform:/plugin/org.example.staticumlprofile/model/StaticUmlProfile.profile.uml#_ds47cam3Ed6HIN9NxFlDEw'.

  9. And that's it. You may now start a new Eclipse runtime to observe that your profile was correctly exported. Applying the 'StaticUmlProfile' profile to a package, and the 'Example' stereotype to a class within it, one should observe that the tagged value 'exampleProperty' is correctly initialized with the "example" default value we have programatically specified. Thus, if you see something like the following, you have been successful: