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.

Note:
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.

Tip:
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.

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.

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.

org.eclipse.emf.query.ocl;bundle-version="[1.0.0,2.0.0)";visibility:=reexport,
org.eclipse.emf.ocl;bundle-version="[1.1.0,2.0.0)";visibility:=reexport,
org.eclipse.ocl.uml;bundle-version="[2.0.0,3.0.0)";visibility:=reexport

org.eclipse.ocl;bundle-version="[3.0.0,4.0.0)";visibility:=reexport,
org.eclipse.ocl.ecore;bundle-version="[3.0.0,4.0.0)";visibility:=reexport,
org.eclipse.ocl.uml;bundle-version="[3.0.0,4.0.0)";visibility:=reexport,
org.eclipse.emf.query.ocl;bundle-version="[2.0.0,3.0.0)";visibility:=reexport

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).

/*  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. */

/*  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. */

OCLConstraintCondition

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().

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

QueryFactory.eINSTANCE.createQuery()

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.

OCL ocl = OCL.newInstance();
OCLHelper<EClassifier, EOperation, EStructuralFeature, Constraint> 
    helper = ocl.createOCLHelper()
helper.setContext(eClass);
ocl.createQuery(helper.createQuery(oclExpression));
ocl.dispose();

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.

Back to top

Summary

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.

Back to top

Acknowledgements

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

Resources

Learn

• Read this author's related articles to learn more about modeling with Rational Software Architect:
  • Migrating models to the IBM Rational Software Architect 8.0 format, a developerWorks article by the author of this article.
  • Follow the More content in this series link in this article to Parts 1 and 2.
  • Using the new features of the UML Modeler in Rational Software Architect Version 7.5, an IBM developerWorks article by Wayne Diu (September 2008)
  
  
• Learn more about Rational Software Architect versions available.
  
  
• Visit the Rational software area on developerWorks for technical resources and best practices for Rational Software Delivery Platform products.
  • Stay current with developerWorks technical events and webcasts focused on a variety of IBM products and IT industry topics.
  • Attend a free developerWorks Live! briefing to get up to speed quickly on IBM products and tools, as well as IT industry trends.
  • Follow developerWorks on Twitter.
  • Watch developerWorks on-demand demos, ranging from product installation and setup demos for beginners to advanced functionality for experienced developers.
  
  
• 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.
  
  

Get products and technologies

• Download either or both version for a trial:
  • Rational Software Architect Standard Edition
  • Rational Software Architect for WebSphere Software
  
  
• Evaluate IBM software in the way that suits you best: Download it for a trial, try it online, use it in a cloud environment, or spend a few hours in the SOA Sandbox learning how to implement service-oriented architecture efficiently.
  
  

Discuss

• Join the discussion in the Rational Development Tools forum.
  
  
• Get involved in the My developerWorks community. Connect with other developerWorks users while exploring the developer-driven blogs, forums, groups such as the Rational Café, and wikis.
  
  

About the author

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 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.

Rate this article

Comments

Back to top

Table of contents

• Programatically extending Rational Software Architect by using Public APIs
• Summary
• Acknowledgements
• Resources
• About the author
• Comments

Next steps from IBM

• Try: Rational Software Architect
• Buy: Rational Software Architect

Dig deeper into Rational on developerWorks

IBM SmartCloud trial. No charge.

Unleash the power of hybrid cloud computing today!

---

Public and private solutions in one trial.

Special offers