Update on UML modeling features in IBM Rational Software Architect Version 8.0: Part 3. API updates

This article highlights some of the new functionality in the UML modeling components of IBM Rational Software Architect Version 8.0 and explains how to take advantage of several recently added features. It also gives a high-level overview of some of the more common pieces of API to programmatically extend the environment's functionality.


Wayne Diu, Software developer, IBM Canada

Wayne DiuWayne 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 the metamodel integration framework platform. Wayne has also developed a diverse collection of other tool features such as printing, validation marker enhancements, and refactoring support.

developerWorks Contributing author

30 November 2010

Also available in Chinese

Programatically extending Rational Software Architect by using Public APIs

Programmatically extending Rational Software Architect is far easier with the addition of Compare Merge code generation wizards and, as mentioned in the previous two articles in this series, the new public APIs in Version 8. The more notable additions to public APIs are for navigation, filtering in the Project Explorer, search, viewpoints, and profile extensibility. In addition, the deprecated OCL API has been removed.

Although the navigation, filtering, viewpoints (UI reduction), and search APIs are technically not part of the UML Modeler component, the UML Modeler uses these functions heavily, so it is worthwhile to describe the API here.

Compare Merge client code-generation wizards

Several Compare Merge wizards have been added so that you can generate custom Compare Merge handlers, called Compare Merge clients, for your EMF models in custom domains.

The primary wizard is the Compare Merge Project wizard (see Figure 1), which is within the New Project wizard.

  1. To show the wizard, choose File > New >Project.
  2. Next, expand the Modeling folder and then the Compare Merge Extensibility subfolder.

If this subfolder is not available, you might need to check the Show all wizards check box or enable the Compare Merge Extensibility capability from the Preferences dialog within General > Capabilities. Click the Advanced button, and expand the Modeling category to find the Compare Merge Extensibility capability.

The Compare Merge Project wizard requires several steps and prompts you to specify parameters such as the file extension, content type, matching strategy (name or ID), diagram support, and custom class names, if desired. The result is an Eclipse plug-in that contains a custom Compare Merge client.

Figure 1. The new Compare Merge code-generation wizard
Select a wizard: Create a Compare Merge project

To further customize your Compare Merge client, you can use additional wizards to generate code and extension point XML automatically:

  1. Select File > New > Other.
  2. Expand the Modeling folder, and then expand the Compare Merge Extensibility folder.

Table 1 shows the uses of the various wizards.

Table 1. The Compare Merge wizard
Wizard Implemented interface, extended class Description
Composite delta strategy com.ibm.xtools.comparemerge.emf.delta.deltagenerator.CompositeDeltaStrategy Groups related deltas logically in the UI tree and enables the selection of a group of deltas at once
Conflict strategy com.ibm.xtools.comparemerge.emf.delta.conflictAnalyzer.ConflictStrategyImpl or com.ibm.xtools.comparemerge.emf.delta.conflictAnalyzer.ConflictStrategy Analyzes the deltas and creates the necessary conflicts
Delta tree filter com.ibm.xtools.comparemerge.emf.deltatree.DeltaTreeFilter, com.ibm.xtools.comparemerge.emf.deltatree.IDeltaTreeFilter, com.ibm.xtools.comparemerge.emf.deltatree.IEditableDeltaTreeFilter, or com.ibm.xtools.comparemerge.emf.deltatree.ICustomDeltaTreeFilter Allows programmatically contributing predefined filters to hide changes (this is in addition to being able to customize filters, using the UI, by clicking the Delta Tree Configuration button)
Delta tree structure builder com.ibm.xtools.comparemerge.emfdeltatree.IDeltaTreeGrouper and com.ibm.xtools.comparemerge.emf.deltatree.DeltaTreeBuilder Allows defining custom structures for the Compare Merge Delta tree, such as variations on the existing hierarchy structure and flat structure
Sub-session merge extender com.ibm.xtools.comparemerge.emf.submerge.EmfTextSubMergeExtender, com.ibm.xtools.comparemerge.ui.submerge.TextSubMergeExtender, com.ibm.xtools.comparemerge.ui.submerge.AbstractSubMergeExtender, or com.ibm.xtools.comparemerge.ui.submerge.ISubMergeExtender Defines custom behavior for individual elements to be merged (for example, it might be desirable to merge text representing code in a specific programming language in a special manner)

Navigation API

It is possible to define navigating from a source element to a destination view by using this API. The navigationProvider, linkProvider, and destinationProvider extension points in com.ibm.xtools.rmp.ui allow defining this behaviour programatically.

  • The destinationProvider defines destinations that you can link to. If you implement your own destinations, they will appear in the Preferences dialog. The preference is the Default navigation destination drop-down menu that you reach by selecting Modeling >General. (As you can see in the preferences, the Project Explorer and Property Dialog destinations have been predefined. If you are reusing those, you do not need to define any destination providers.)
  • The navigationProvider requires the implementation of an INavigationProvider interface, where you must implement the behavior to navigate to the given element in a certain destination. The destination corresponds to one of the destinations defined by a destination provider.
  • The linkProvider requires the implementation of an ILinkProvider interface. Here, you must implement a method to return EObjects related to the context EObject. These related EObjects will show up as hyperlinks, in addition to the context EObject.

Filters API

You can use the com.ibm.xtools.common.ui.navigator.NavigatorNameFilterHelper extension point to define your own name filters that implement the INameFilterHelper interface. As mentioned previously, the Name Filter text box of the Project Explorer will consult registered name filter helpers for filtering and navigation.

Search API

It is possible to contribute your custom element types to the Advanced Search Options dialog from the Model Search page. (To show that dialog window, click the Advanced button on the Search page.) In addition, it is possible to contribute custom search results by using the com.ibm.xtools.rmp.ui.search.rmpSearchService extension point and implementing the IRMPSearchProvider interface.

Viewpoints API

Two new elements were added to the com.ibm.xtools.common.ui.reduction.editingCapabilities extension point.

  • viewpointActivityBinding to bind an activity to a viewpoint
  • viewpointElementDataBinding to bind data to an existing viewpoint element

The first element allows more control over when to show the UI, based on the active viewpoint, while the second element allows better integration with existing viewpoints.

Profile extensibility

A new API method used to obtain the collection of deployed profiles has been added to the public UML Modeler class (com.ibm.xtools.modeler.ui.UMLModeler). The API is called getDeployedProfiles(), and it returns a collection of com.ibm.xtools.uml.msl.profiles.IProfileDescriptor objects. From the profile descriptor interface, you can get details about the profile, including these:

  • Whether or not the profile is visible in the UI
  • The profile's ID
  • The profile's display name
  • The profile's corresponding EMF resource
  • The UML profile itself

In addition, a public API class has been added to supply common utilities for working with profiles. The class is com.ibm.xtools.modeler.ui.UMLProfileUtility, which contains methods for setting and determining whether a stereotype, property, or a stereotype's properties are suppressed or read-only in the UI. Additionally, it contains methods to work with a stereotype's image and provides the ability to define a standard UML 2 profile customized with extensions specific to Rational Software Architect.

The com.ibm.xtools.modeler.ui.UMLExportImportUtility class has been added to allow importing and exporting resources in the following formats: ECore, UML2, UML2 XMI. Each method requires the implementation of a com.ibm.xtools.uml.core.IConverterHandler. If desired, UI code to prompt whether a file should be overwritten, handle errors, or alert that a resource has been loaded can be implemented in the handler.

Object Constraint Language updates

The long-deprecated OCL-related classes and interfaces from com.ibm.xtools.ocl have finally been removed to support the migration to Version 3.0 of org.eclipse.ocl (which actually follows the OMG's OCL 2 standard).

Migrating bundles

To migrate to the new version of org.eclipse.ocl, start by changing the bundles to the correct versions. For example, if the bundles in your MANIFEST.MF file are as Listing 1 shows, change them to what Listing 2 shows.

Listing 1. Old version of MANIFEST.MF file
Listing 2. New version of MANIFEST.MF file

Deprecated classes

In the com.ibm.xtools.uml.ocl package, there is a set of classes and interfaces for each of the following:

  • Metamodel environment
  • User model environment
  • OCL environment

The first two deprecated sets have been removed. You can use the OCL environment set of classes and interfaces instead. The Javadocs™ for the two deprecated classes describe the new API to be used (see Listings 3 and 4).

Listing 3. MetamodelEnvironmentFactory
/*  Use the {@link OCLEnvironmentFactory}, instead, using the
*  {@link OCLHelper#setInstanceContext(Object)},
*  {@link OCLHelper#setInstanceOperationContext(Object, Object)}, and
*  {@link OCLHelper#setInstanceAttributeContext(Object, Object)} 
*  methods to specify the context elements in OCL parsing at the UML
*  meta-model (M2) level. */
Listing 4. UserModelEnvironmentFactory
/*  Use the {@link OCLEnvironmentFactory}, instead, using the
*  {@link OCLHelper#setContext(Object)},
*  {@link OCLHelper#setOperationContext(Object, Object)}, and
*  {@link OCLHelper#setAttributeContext(Object, Object)} methods to
*  specify the context classifiers in OCL parsing at the UML
*  user-model (M1) level. */


If you were constructing org.eclipse.emf.query.ocl.conditions.OCLConstraintCondition objects, you will find that the class has been removed.

This is the replacement to use:

BooleanOCLCondition<EClassifier, EClass, EObject>

To do so, first construct a new OCL object:

OCL ocl = OCL.newInstance();

Then, the first parameter of BooleanOCLCondition can be ocl.getEnv().

Don't forget to dispose of the OCL object that you instantiated.


If you were constructing queries using the org.eclipse.emf.ocl.query.QueryFactory, you will find that the class has now been removed.

The replacement is to construct a query object from an OCL object. For example, if you had code such as this:

QueryFactory.eINSTANCE.createQuery(oclExpression, eClass)

You now need to first construct a new OCL object, a helper, and then the query. You no longer pass in the EClass when constructing the query. Instead, you must set the context in the helper, as Listing 5 shows.

Listing 5. How to set the context in the helper
OCL ocl = OCL.newInstance();
OCLHelper<EClassifier, EOperation, EStructuralFeature, Constraint> 
    helper = ocl.createOCLHelper()

The helper's createQuery() method returns an OCLExpression<EClassifier>, not a Query object.

Different OCLs

Notice that there are three classes called OCL. Be sure to import the correct one for your purpose (EMF, UML, or general). Otherwise, you might run into odd problems.


This article provided an overview of the new and changed API in the UML Modeler and Rational Modeling Platform components of Rational Software Architect Version 8.0. By taking advantage of the public API described here, you will be able to programmatically extend Rational Software Architect and customize it to improve your workflow. Also, the new Compare Merge code-generation wizard provides a handy starting point for extending the Compare Merge functionality without having to start from scratch.


The author expresses his gratitude to Dusko Misic and Michael Hanner for reviewing this article and to Judith Broadhurst for editing.



Get products and technologies



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

ArticleTitle=Update on UML modeling features in IBM Rational Software Architect Version 8.0: Part 3. API updates