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.
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.
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
Run the Profile Tooling wizard
The Project Explorer is the default way to view resources in the Modeling View.
- 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.)
- Then choose the Generate Profile Tooling action.
Figure 2. Drop-down menu for the Generate Profile Tooling action
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
Figure 4. Example of menu items for a sample profile
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.
Figure 5. Warning message when an unreleased profile is used
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!
After you have completed testing, the plug-in should be deployed like a standard Eclipse plug-in. First, test the generated tooling:
- To perform a quick test in your environment, create a new configuration by choosing Run > Open Run Dialog.
- Double-click Eclipse Application on the left side to create a new Eclipse Application configuration.
- Type a name for your configuration.
- In the Main tab, you can choose a new location (such as C:\my-runtime-workspace).
- 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
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
-eain 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:
- Launch the new instance by clicking Run.
- Now create a new model by choosing File > New > Project > Modeling > New Model Project, as Figure 7 shows.
- Check the Show all templates check box to show the template associated with the tooling for your profile.
- 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
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
Tip:
You can also get the tooling to display by manually applying the
corresponding profile to the model:
- 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.
- 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
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:
- Select the model (not the diagram) in the Project Explorer, and then select the Properties view.
- 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
- To enable the standard UML tooling, enable Components within UML Element Building Blocks.
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:
- 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.
- Ensure that only the required plug-in is checked and, within the Destination tab, enter the directory destination for the JAR output.
- (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.
- Click Finish.
Figure 11. Generating a JAR file for your profile tooling
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:
- Open the manifest.mf file in the generated plug-in project.
- 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
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.
- Create an update site and publish your plug-in on the site.
- 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:
- Select Help > About Eclipse SDK.
- 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
-cleanparameter. - 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.
- If the plug-in is not in the list, restart the application with the
Figure 13. Verifying that the plug-in has been deployed properly
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 method | Pros | Cons |
|---|---|---|
| Manual deployment of the plug-in project |
|
|
| Manual deployment of the JAR file |
|
|
| Copy JAR file into the plug-in folder of the installation (recommended) |
|
|
| Use update site |
|
|
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").
The author thanks Dusko Misic and Maneesh Goyal for reviewing this article.
Learn
- Read Part 2,
Custom domain modeling with UML Profiles: Part 2. Using the Profile Tooling wizard,
by the same author.
- To learn more about UML profiles, read
Authoring UML Profiles: Part 1. Using Rational Software Architect, Rational Systems Developer, and Rational Software Modeler to create and deploy UML Profiles and Authoring UML Profiles: Part 2. Using Rational Software Architect, Rational Systems Developer, and Rational Software Modeler to manage change in UML Profiles
by Dusko Misic (IBM developerWorks, April 2008).
- To learn more about deploying
a plug-in on an update site, read
How to Keep
Up to Date, an Eclipse Corner article on the Eclipse.org Web site.
- Visit the
Rational software area on developerWorks
for technical resources and best practices for Rational Software Delivery Platform
products.
- Explore
Rational computer-based, Web-based, and instructor-led online courses.
Hone your skills and learn more about Rational tools with these courses, which
range from introductory to advanced. The courses on this catalog are available for
purchase through computer-based training or Web-based training. Additionally, some
"Getting Started" courses are available free of charge.
- Subscribe to the
Rational Edge newsletter
for articles on the concepts behind effective software development.
- Subscribe to the
IBM developerWorks newsletter,
a weekly update on the best of developerWorks tutorials, articles, downloads,
community activities, webcasts and events.
- Browse the
technology bookstore
for books on these and other technical topics.
Get products and technologies
- Download
trial versions of IBM Rational software.
- Download these
IBM product evaluation versions
and get your hands on application development tools and middleware products from
DB2®, Lotus®, Tivoli®, and WebSphere®.
Discuss
- Check out
developerWorks blogs and
get involved in the
developerWorks community.
Wayne Diu is a software developer at IBM Rational who worked on designing and implementing the Profile Integration feature. He has developed several other features for the Rational Modeling Platform such as the Browse Diagram infrastructure and was one of the developers responsible for the platformization of the metamodel integration framework. He has also worked on a diverse collection of other features such as printing, find and replace, and refactoring support.
Comments (Undergoing maintenance)
Table of contents
Next steps from IBM
My developerWorks community
Tags
Use the slider bar to see more or fewer tags.
Popular tags shows the top tags for this particular content zone (for example, Java technology, Linux, WebSphere).
My tags shows your tags for this particular content zone (for example, Java technology, Linux, WebSphere).
Popular article tags |
My article tagsSkip to tags list
Popular article tags |
My article tags
