Custom domain modeling with UML Profiles: Part 1. Generating and deploying tooling

This two-part article series explains how to generate tooling and shapes for UML Profiles to allow custom domain modeling with IBM® Rational® Systems Developer, IBM® Rational® Software Architect, and IBM® Rational® Software Modeler. The steps described in these articles pertain to Rational Software Modeler 7.0.5 and Rational Software Developer 7.0.5.

Share:

Wayne Diu, Software developer, IBM Canada

Wayne Diu is an IBM Rational software developer. He has designed and implemented Unified Modeling Language (UML) features on the Rational Modeling Platform, such as server integration and model search. In addition, Wayne was one of the developers responsible for establishing a platform for the metamodel integration framework platform. Wayne has also delivered developed a diverse collection of other tool features such as printing, validation marker enhancements, and refactoring support.


developerWorks Contributing author
        level

06 May 2008

Also available in Chinese

In this article, you will learn how you can generate tooling for elements from an existing profile or from a profile that you create. Because intermediary files and code will be generated, you will be able to modify these files and customize several aspects:

  • The types of tooling that appear in the drop-down menu or the palette
  • How the tooling appears
  • The elements for which tooling will appear
  • The elements for which custom shapes will appear
  • Whether or not you want custom shapes for the stereotyped elements

If you are willing to write code, you can further customize the generated or default UML shapes. You can also modify the constraints between the shapes. When you are finished, you end up with completely customized tooling to model elements from your own domain, with your custom shapes on the diagram. Because Java code that builds on the open source GMF layer is generated, this article also covers how to modify and extend the code.

Prerequisites

If you have a basic understanding of Eclipse and UML modeling, you will probably be able to follow along with this part and generate and deploy your own custom tooling. A word of warning, though: You will need some knowledge of Java™ technology to do major customization of generated shapes.

Before you start

To generate the tooling, you need a profile first. You have two choices:

  • If you want to start with a new profile, create one now by selecting File > New > Other > Modeling > UML Extensibility > UML Profile.
  • Alternatively, copy an existing profile into a project in your workspace. So that you can follow along, be sure to add several stereotypes with metaclass extensions to your profile, as explained in the article on UML profiles cited in Resources.

If your profile contains non-ASCII characters, or if you anticipate that you will be using non-ASCII characters anywhere in the tooling, be sure that the workspace preferences are set to UTF-8 encoding. You can do this by selecting Window > Preferences > General > Workspace, and choosing UTF-8 as the Text file encoding (see Figure 1). Otherwise, the Java files that are generated will not compile properly.

Figure 1. Setting the text file encoding
Screen capture

Run the Profile Tooling wizard

The Project Explorer is the default way to view resources in the Modeling View.

  1. In the Project Explorer, right-click on the profile. (Alternatively, you may do this from the Package Explorer if you are more familiar with the Java side of things. After all, Java code will be generated.)
  2. Then choose the Generate Profile Tooling action.
Figure 2. Drop-down menu for the Generate Profile Tooling action
Shows Generate Profile Tooling selected

The wizard will try to populate the fields based on the profile that you selected and its location in the workspace. It helps to understand what each of the fields means:

  • The application name is the name of the modeling domain for which tooling will be generated. The name that initially appears in the text box is extracted from the name of the profile that you selected, which may not be the same as the profile's file name. You will not need to change it if the profile was named meaningfully. If it was not, rename it. The default palette entries (Figure 3) and menu name will be derived from this name.
  • Next in the wizard is the project name. You can browse for an existing project or simply type the name of a new project. If the project isn't a Java project (for Eclipse users, this means that it doesn't have the Java nature), it will be automatically converted when the code is generated. You can just accept the default project name for now.
  • Finally, the default generation options are to generate palette entries and menu items (Figure 4), not to generate custom shapes.
Figure 3. Sample palette entry for a sample profile
Screen capture
Figure 4. Example of menu items for a sample profile
Screen capture

When custom shapes are not generated, the standard UML shapes will be used. This is a good choice, because the end users of your tooling (which will be referred to as domain modelers), will be able to generate diagrams by using standard UML notations. Plus, you won't have to modify even a single line of code for shapes that look great.

Working with released and unreleased profiles

The profiles shipped with the Rational modeling products have been released. If you're generating tooling for your own model and, especially, if it will be deployed to other domain modelers, we strongly advise you to release your profile first. Compatibility between unreleased profiles is not guaranteed. To release your profile: Bring up the context menu of the profile in the Project Explorer and choose Release.

Of course, the wizard can successfully generate tooling for an unreleased profile just as if it is a released profile. This can save you time when you are still developing your profile. The wizard will issue a warning message (Figure 5) if you select an unreleased profile to generate.

Figure 5. Warning message when an unreleased profile is used
Screen capture

For this example, simply accept the default options and press Finish. (You'll learn about the other wizard pages later.) After a few moments, a new project has been generated and it includes code and a copy of your profile. This newly generated project may now be deployed.

Tip:
If all you want to do is deploy a profile, and you want to do it the easy way, this wizard can also do the job for you. When you use the wizard, you don't have to bother with creating a plug-in, writing all of the XML tags, and copying over your profile. Simply clear all of the check boxes in Generation Options and then click Finish. A simple plug-in project will be created for you, the XML that registers the pathmap and the profile will be written in the plug-in.xml file, and your profile will be copied to a directory called profiles. You now have a plug-in that's ready to be deployed. It can't be much easier than that!

Test the generated plug-in

After you have completed testing, the plug-in should be deployed like a standard Eclipse plug-in. First, test the generated tooling:

  1. To perform a quick test in your environment, create a new configuration by choosing Run > Open Run Dialog.
  2. Double-click Eclipse Application on the left side to create a new Eclipse Application configuration.
  3. Type a name for your configuration.
  4. In the Main tab, you can choose a new location (such as C:\my-runtime-workspace).
  5. For Program to Run, leave the default settings of com.ibm.rational.rxx.product.ide (Figure 6).
Figure 6. Preparing to launch your application with the Run dialog
Screen capture

Tips:

  • When generating a plug-in that is used only to deploy a profile, the plug-in will be created with the standard Eclipse plug-in nature. When generating a plug-in that contains tooling, the Java nature will be added to the standard Eclipse plug-in nature.
  • Under the Plug-ins tab, ensure that Launch with is set to all workspace and enabled plug-ins. If you must choose plug-ins selected below only, ensure that the entry for the plug-in corresponding to the tooling is checked.
  • If you plan to modify the generated code, it is a good idea to include -ea in the VM Arguments box under the Arguments tab. Some of the generated code includes assertions, so you may find that enabling the assertions will help you track down programming errors faster.

Try it now:

  1. Launch the new instance by clicking Run.
  2. Now create a new model by choosing File > New > Project > Modeling > New Model Project, as Figure 7 shows.
  3. Check the Show all templates check box to show the template associated with the tooling for your profile.
  4. Select the corresponding template, and then press Finish.

A model will be created, and a blank diagram editor will open.

Figure 7. The New Model wizard
Screen capture

Observe that tooling corresponding to the profile elements appears in the palette. Bring up the context menu on the diagram surface, and observe there are now menu items that correspond to the profile elements. You will find a palette entry for every metaclass extension defined for every stereotype, as well as for metaclass associations and stereotype associations. The connectors that have been generated all follow live constraints. That is, they can be connected only in a way that follows UML rules and the tooling's rules. For example, you would not be able to add an implements connector to a UML package, nor would you be able to create a stereotype association connector between objects that don't have the expected stereotype applied.

The example in Figure 8 uses a simple example profile. By just clicking on the palette, we created UML Actors stereotyped to Customer, CustServAgent, and Pilot. We also created several use cases and relationships between the elements. Additional UML elements for which we haven't defined tooling may still be added by enabling additional capabilities. You will learn how to do this shortly. Observe that the connector can be added only in the correct direction and that you will be unable to join two nodes with a connector in the reverse direction.

Figure 8. Modeling in the example domain using the palette
Screen capture

Tip:
You can also get the tooling to display by manually applying the corresponding profile to the model:

  1. In the Model Editor, select the Details tab and click the Add button in the Applied Profiles section. Given that the Profile Tooling wizard deploys the profile into the plug-in, the profile will show in the list of deployed profiles.
  2. Select the profile, and then click OK.

This is the path to take when you want to work with an existing model.

Figure 9. Manually applying the profile
Screen capture of the model

Troubleshooting tip:
If the palette entries and menu items do not appear, verify that the capability for your profile tooling has been enabled. Capabilities are used to reduce the unnecessary UI presented to the domain modeler. Typically, the modeler is interested in only one domain, thus to avoid confusion, tools from other domains are hidden by default.

Verify the capabilities:

  1. Select the model (not the diagram) in the Project Explorer, and then select the Properties view.
  2. Click the Capabilities tab, and verify that the capability corresponding to your profile tooling has been checked.

Thus, instead of manually applying the profile, you could also enable the capability to make the tooling show. The tooling generated by default will automatically apply the profile to the model when necessary.

Figure 10. The Capabilities properties
Screen capture
  1. To enable the standard UML tooling, enable Components within UML Element Building Blocks.

Deploy the tooling

When you are satisfied with your tooling, you will probably want to deploy it to domain modelers to use.

The easiest way for the developer is to distribute the generated project to the domain modeler. The modeler must import the project into the workspace by using File > Import > Existing Projects into Workspace, and then launch a new runtime workbench (as we did to test the tooling). This method is the worst of all: one missing file and the plug-in ceases to work. Furthermore, requiring another instance of the runtime workbench to run increases memory consumption; therefore, this is not a recommended approach.

A more reasonable step is to generate a Java Archive (JAR) file for the tooling project. The JAR file includes the generated code in its compiled form:

  1. Select the generated project that contains your tooling from the Package Explorer. Bring up the context menu, and choose Export > Plug-in Development > Deployable plug-ins and fragments.
  2. Ensure that only the required plug-in is checked and, within the Destination tab, enter the directory destination for the JAR output.
  3. (Optional) In the Options tab, you may find it helpful to check the Include source code option if you're planning on customizing the code, so that it will be that much easier to debug.
  4. Click Finish.
Figure 11. Generating a JAR file for your profile tooling
Screen capture

Troubleshooting tip:
If this fails, remove unnecessary plug-ins from your environment if you added any. Likely, another builder is trying to contribute and it is failing, causing the entire process of generating the jar to fail.

There are several ways to go from here. A possible way is to give the modeler your jar. The modeler imports it into the workspace using File, Import, Plug-ins and Fragments, then launches another instance of the workspace. Again, this has memory implications.

A far better way is to the copy the jar file into the product install's plug-ins directory. If the application is installed in the default location, here is where to find the directory, depending on which operating system you are using:

  • Microsoft® Windows®: C:\Program Files\IBM\SDP\plugins
  • Linux®: /home/<username>/eclipse/plugins

If the file is copied as part of the product's installation and the generated tooling is not going to be updated, this is a relatively easy approach. The generated tooling will be available the next time the application is launched.

There may be no plan to update the generated tooling, but assuming that there will be no updates is probably unrealistic. What you can do, however, is anticipate the updates and assign versions to your plug-in. By default, the plug-in version is taken from the profile's version. Therefore, if you make changes to your tooling without making changes to the profile, the version number will remain the same. You can overcome this problem by manually updating the version of your plug-in before generating the JAR file. To do this:

  1. Open the manifest.mf file in the generated plug-in project.
  2. On the Overview page, increment the version in the General Information section (see Figure 12).
Figure 12. The manifest editor allows incrementing the plug-in version
Screen capture

Now, the next time the tooling is updated, it just needs to be copied into the correct location, and the application needs to be relaunched. Updating the version of the manifest prevents naming conflicts when the JAR file is copied into the plug-ins folder.

The final method is the standard Eclipse approach.

  1. Create an update site and publish your plug-in on the site.
  2. Select File > New > Other > Plug-in Development > Update Site Project, and follow the prompts.

This step is far more involved. See Resources for the link to "Deploying a plug-in on an update site."

Troubleshooting tip:
If the JAR file is copied into the plug-in folder of the installation and the tooling fails to appear, first verify that the plug-in and the correct version are there:

  1. Select Help > About Eclipse SDK.
  2. Click Plug-in Details, and verify that the generated plug-in is in the list (see Figure 13).
    • If the plug-in is not in the list, restart the application with the -clean parameter.
    • If the plug-in is in the list, check the Error Log view by selecting Window > Show View > Other > PDE Runtime > Error Log, and checking for errors that pertain to the tooling plug-in.
Figure 13. Verifying that the plug-in has been deployed properly
Screen capture

Table 1 summarizes the methods for deploying your tooling plug-in.

Table 1. Deployment methods for your tooling plug-in

Table 1. Table name
Deployment methodProsCons
Manual deployment of the plug-in project
  • Very easy for the tooling developer
  • User has easy access to source
  • Too easy to miss a file, causing the tooling to not function properly
  • Process to update the tooling may confuse the end user
  • Requires end user to launch another instance of the workspace (which requires more memory)
  • User has easy access to source and easy to modify, thus tooling could be out of sync on multiple users' machines
Manual deployment of the JAR file
  • Very easy for the tooling developer
  • User has easy access to source code if the source is included in JAR file
  • Requires end user to launch another instance of the workspace (which uses more memory)
  • Process to update the tooling may confuse the end user
  • User has easy access to source code if the source is included in the JAR file and easy to modify, so tooling could be out of sync on multiple users' machines
Copy JAR file into the plug-in folder of the installation (recommended)
  • Very easy
  • Updates to the tooling require copying the plug-in into the proper folder again
Use update site
  • Standard Eclipse way of updating
  • End user can get updates for the profile tooling easily
  • More work for the profile developer to maintain the site

Summary and next step

You have now learned how to:

  • Generate tooling for a profile
  • Test the generated tooling
  • Evaluate the different methods for deploying the generated tooling
  • Deploy the generated tooling

If you do not wish to further customize the generated tooling, you may find this an appropriate place to stop reading. More technical users may find it beneficial to continue to Part 2 to learn how to customize the tooling (click "More in this series").

Acknowledgements

The author thanks Dusko Misic and Maneesh Goyal for reviewing this article.

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational
ArticleID=305875
ArticleTitle=Custom domain modeling with UML Profiles: Part 1. Generating and deploying tooling
publish-date=05062008