Extending using plug-ins

Plug-ins are the most flexible way of extending the Rational Modeling Platform. They enable the creation of extension to extension-points as well as providing full debugging support. One of their limitations is that they require the use of a separate workbench for testing during development.

Creating a plug-in

Creating a plug-in requires the creation of a Plug-in Project. Such a project contains one and only one single plug-in. This is accomplished by running the New Plug-in Project wizard accessible from File > New > Project....

New Plug-in Projects Wizard

Choosing Plug-in Project within the Plug-in Development category, and selecting Next will lead to the Plug-in Project page.

New Plug-in Projects Wizard, Plug-in Project Page

The new project name should be entered in the Project name field. Selecting Next will bring the Plug-in Content page.

New Plug-in Projects Wizard, Plug-in Content Page

This page is used to capture the name and provider of the plug-in. Selecting Next results in the Templates page appearing.

New Plug-in Projects Wizard, Plug-in Content Page

Using the templates listed in this page, the new plug-in will be capable of performing a specific task. Selecting Plug-in with a sub-element counter and selecting Next will lead to a page specific to this template.

New Plug-in Projects Wizard, UML Modeler Element Counter Plug-in Project Page

The UML Modeler Element Counter Plug-in is a very simple plug-in that counts the number of elements owned by the selected element. It demonstrates how to add a menu item, how to get the selection, how to access the model, and finally how to setup dependencies to extend the UML Modeler. This wizard page allows users to specify the Java package and class name of the action that will perform the count behaviour. Selecting Finish creates the plug-in project and opens up the plug-in's manifest editor.

Plug-in Manifest Editor

This editor is used to define various aspect of a plug-in. Its information are persisted in three project files: META-INF/MANIFEST.MF, plugin.xml and build.properties. Opening one of the first two files will invoke this editor. The various plug-in parameters are grouped by pages accessible from tabs located at the bottom of the editor:

It is worth noting that the "Sub-element Counter" template chosen initialized the plug-in with a dependency to com.ibm.xtools.modeler.ui, the plug-in owning the UMLModeler class. This plug-in in turn re-exports all of the dependencies visible from its APIs. For instance, when using IUMLDiagramHelper, there is no need to add a dependency to the com.ibm.xtools.uml.ui.diagram plug-in since this dependency is re-exported by com.ibm.xtools.modeler.ui. Conversely, using an indexing API such as IIndexSearchManager requires the addition of a dependency to the com.ibm.xtools.emf.index plug-in.

Another addition by the chosen template is the extension to the org.eclipse.ui.actionSets extension-point that can be appreciated from the Extensions tab. This extension adds a Sample menu to the menubar and inserts in it a Sub-Element Counter Plug-in menu item. Such menu item are associated with a class to be instantiated upon its selection. This class can be discovered by selecting the node named Count Sub-Elements (action) from the All Extensions section and looking at the class property available from the Extension Element Details.

Plug-in Manifest Editor, Extensions Tab

New extensions can be added by selecting the Add... button of the All Extensions section.

Running a plug-in

Running a plug-in is accomplished by selecting Run > Run... from the menu bar. This will bring up the Run dialog, which is used to configure the parameters for the run. Select Eclipse Application and select the New launch configuration button at the top of the tree control.

Run Dialog

The page that appears is used to configure the Eclipse application that will be launched to test the plug-ins developed in the workspace. One of the parameters is the location of the workspace to use for this new Eclipse instance. Selecting the Configuration tab enables further customization of the launch configuration required by the Rational Modeling Platform.

Configuration

The Configuration File settings must be changed so the Use an existing config.ini as a template option is selected and the config.ini file installed with the IBM Rational modeling solution product is used. The latter is accomplished by entering ${target_home}/configuration/config.ini.

Selecting Run starts the new instance.

The new Eclipse instance is launched and contains every plug-ins in the host Eclipse development environment as well as all open plug-in projects developed in the workspace. This behaviour is configurable from the Run dialog. The sample menu item can be exercised by creating a new UML project, by selecting a UML element within the Project Explorer and by selecting Sample > Count Sub-Elements. Closing the new Eclipse instance will terminate the run session.

Deploying a plug-in within an IBM Rational modeling solution product

Plug-ins can be deployed in existing IBM Rational modeling solution products. The easiest way to accomplish this is to create an Eclipse Extension, which is a location where plug-ins can be contributed to an existing Eclipse product installation. As an example, an extension could be located in a folder whose path is c:\eclipse-extension\eclipse.

The first step is to export the plug-in project. This is accomplished by selecting File > Export... and selecting Deployable plug-ins and fragments from the Plug-in Development category.

Export Plug-in Dialog

Selecting Next will present the Deployable plug-ins and fragments page. The Available Plug-ins and Fragment list is used to select the plug-ins to export. The Directory is where the plug-ins will be exported; c:\eclipse-extension\eclipse is an example. Selecting Finish will perform the export operation.

Making an Eclipse extension is as simple as creating a file named ".eclipseextension" within the c:\eclipse-extension\eclipse and put the following contents in it:


name=The Name of your Eclipse Extension
id=the.id.of.your.eclipse.extension
version=1.0.0 

It is worth noting that on Windows, the Windows Explorer will prevent the creation of a file with no name. This can be worked around by launching Notepad and saving with .eclipseextension as the File name field and set Save as type to All Files.

The final step is to help the IBM Rational modeling solution product discover the site. This is accomplished by selecting Help > Software Updates > Manage Configuration, which will launch the Product Configuration dialog.

Product Configuration Dialog

Adding the extension is performed by selecting the IBM Rational modeling solution product, open the context menu by right-clicking, selecting Add > Extension Location..., and locate the extension, c:\eclipse-extension\eclipse in this example. It is recommended to accept the suggestion by Eclipse to restart the workbench.

Once the product is restarted, the plug-ins deployed within the Eclipse extension should be visible. In the current example, this is reflected by the Sample menu appearing on the menu bar.


Legal notices