Guide to IBM Rational Synergy for Eclipse Interface Extension Points

IBM Corporation
27 January, 2011

 

 

The IBM® Rational® Synergy for Eclipse Interface offers a collection of extension points that can be used to add functionality to the existing plug-in. Use of these extension points is demonstrated in the included Guide plug-in, which uses many of the integration’s available extension points to add new menu items and toolbar buttons. This document will focus on descriptions of the extension points and how to extend them, along with providing an extension point reference guide to the Guide plug-in.

It is divided into the following sections:

·         Overview of extension points

·         Using the extension points

·         Guide plug-in class overview

The Integration’s javadoc is located at: Eclipse Help Contents->IBM Rational Synergy Repository 7.2.0.1->Reference


Overview of Extension Points

This section will outline the extension points available through the integration. Note that some of the features added by the Guide plug-in to the taskbar and Navigator and Package Explorer Team menus use Eclipse® extension points, not the integration’s.

Repository View:

-          com.ibm.rational.synergy.integration.ui.repositorytoolbarmenuaction

o        Can be used to add a toolbar button to the Repository View.

 

-          com.ibm.rational.synergy.integration.ui.repositorycontextmenuaction

o        Can be used to add a context menu to the Repository View.

 

 

History View:

-          com.ibm.rational.synergy.integration.ui.historytoolbarmenuaction

o        Can be used to add a toolbar button to the History View.

 

-          com.ibm.rational.synergy.integration.ui.historycontextmenuaction

o        Can be used to add a context menu to the History View.

 

 

Task View:

-          com.ibm.rational.synergy.integration.ui.tasktoolbarmenuaction

o        Can be used to add a toolbar button to the Task View.

 

 

-          com.ibm.rational.synergy.integration.ui.taskcontextmenuaction

o        Can be used to add a context menu to the Task View.

 

Team Menu:

-          org.eclipse.ui.popupMenus

o        Can be used to add items to the Team context menu in the Navigator or Package Explorer.

Decorators:

-          com.ibm.rational.synergy.integration.ui.teamdecorator

o        Can be used to change the default icon decorators used by the integration.

Task Filter:

-          com.ibm.rational.synergy.integration.ui.taskviewmodelfilter

o        This extension point is not used by the Guide plug-in.

Project Serializer:

-          com.ibm.rational.synergy.integration.team.cmsprojectsetcapability

o        This extension point is not used by the Guide plug-in.

 


Using the Extension Points

This section will explain how to write classes to extend each of the extension points available through the Integration. It is assumed that the reader already has a basic understanding of writing plug-ins.


Adding Actions to the Repository View:

The steps below summarize the process of adding actions to the Repository View

1.       Modify plugin.xml to include an entry similar to one of the following:

Adding a toolbar button:

   <extension

         id="<extensionid>"  ID of the extension

         name="<extensionname>"  Name of the extension

point="com. ibm.rational.synergy.integration.ui.repositorytoolbarmenuaction">  Extension point

<repositoryviewtoolbarmenu

            label="<label>"  Text that is displayed on a menu selection

            image="<image>"  Location of the image relative to the project root that is to be displayed on the toolbar or context menu for this object when the class’ isEnabled method returns true

            disabledimage="<disabledimage>"  Location of the image relative to the project root that is to be displayed on the toolbar or context menu for this object when the class’ isEnabled method returns false

            position=”<position>” Numerical position of the button on the toolbar.

            tooltips="<tooltips>  Message that appears upon mouse hover over selection

            class="<class>"  Location of the class that contains the logic for the toolbar or menu item

           id="<id>">  ID for this object

        </repositoryviewtoolbarmenu> 

</extension>

Adding a context menu item:

   <extension

         id="<extensionid>"  ID of the extension

         name="<extensionname>"  Name of the extension

point="com. ibm.rational.synergy.integration.ui.repositorycontextmenuaction">  Extension point

<repositoryviewcontextmenu

            label="<label>"  Text that is displayed on a menu selection

            image="<image>"  Location of the image relative to the project root that is to be displayed on the toolbar or context menu for this object when the class’ isEnabled method returns true

            disabledimage="<disabledimage>"  Location of the image relative to the project root that is to be displayed on the toolbar or context menu for this object when the class’ isEnabled method returns false

            menugroup="<menugroup>"  This is only necessary if creating a context menu item

            tooltips="<tooltips>  Message that appears upon mouse hover over selection

            class="<class>"  Location of the class that contains the logic for the toolbar or menu item

           id="<id>">  ID for this object

      </repositoryviewcontextmenu> 

</extension>

2.       Create a class that implements the interface ICMSRepositoryAction and have its location specified in the “class” field above. Consult the Javadoc for information about this interface.

Implementing the run(CMSRepositoryAction action) method

Before proceeding with the implementation, first obtain the instance of CMSRepositoryView by using action.getRepositoryView(). After you have obtained this, get the instance of CMSViewModel using the method myView.getModel() (you may have to cast this to a CMSViewModel type when assigning it). Check to see if either of these is equal to null, and return from the method if this is the case.

To retrieve the user’s selections in the Repository View, you will need to obtain the instance of CMSRepositoryViewer by using the method action.getRepositoryViewer(). Once you have the instance of CMSRepositoryViewer, you can retrieve the user’s selections in the Repository View by using the following method:

TreeItem[] sellist = viewer.getTree().getSelection();

As you iterate through this array of TreeItem, you may find it useful to store the element’s data as a CMSViewModel variable. This can be done by calling getData() on the element in the array (again, you may have to cast this to a CMSViewModel type when assigning it).

CMSViewModel mdl = (CMSViewModel)sellist[nm].getData();

In the course of implementing the method, you will probably find it necessary to obtain the name of the database connection that the selected item is associated with. This is needed to obtain the instance of and make calls to the CMApi class. To get the connection name, simply use CMSViewModel’s getConnectionName() method.

String connectionName = mdl.getConnectionName();

Note: You can obtain the current default connection name using CorePlugin.getDefaultConnection();

 

Adding Actions to the History View:

The steps below summarize the process of adding actions to the History View

1.       Modify plugin.xml to include an entry similar to one of the following:

Adding a toolbar button:

   <extension

         id="<extensionid>"  ID of the extension

         name="<extensionname>"  Name of the extension

point="com. ibm.rational.synergy.integration.ui.repositorytoolbarmenuaction">  Extension point

<historyviewtoolbarmenu

            label="<label>"  Text that is displayed on a menu selection

            image="<image>"  Location of the image relative to the project root that is to be displayed on the toolbar or context menu for this object when the class’ isEnabled method returns true

            disabledimage="<disabledimage>"  Location of the image relative to the project root that is to be displayed on the toolbar or context menu for this object when the class’ isEnabled method returns false

            position=”<position>” Numerical position of the button on the toolbar.

            tooltips="<tooltips>  Message that appears upon mouse hover over selection

            class="<class>"  Location of the class that contains the logic for the toolbar or menu item

           id="<id>">  ID for this object

      </historyviewtoolbarmenu> 

</extension>

Adding a context menu item:

   <extension

         id="<extensionid>"  ID of the extension

         name="<extensionname>"  Name of the extension

point="com. ibm.rational.synergy.integration.ui.repositorycontextmenuaction">  Extension point

<historyviewcontextmenu 

            label="<label>"  Text that is displayed on a menu selection

            image="<image>"  Location of the image relative to the project root that is to be displayed on the toolbar or context menu for this object when the class’ isEnabled method returns true

            disabledimage="<disabledimage>"  Location of the image relative to the project root that is to be displayed on the toolbar or context menu for this object when the class’ isEnabled method returns false

            menugroup="<menugroup>"  This is only necessary if creating a context menu item

            tooltips="<tooltips>  Message that appears upon mouse hover over selection

            class="<class>"  Location of the class that contains the logic for the toolbar or menu item

           id="<id>">  ID for this object

      </historyviewcontextmenu> 

</extension>

2.       Create a class that implements the interface ICMSHistoryAction and have its location specified in the “class” field above. Consult the Javadoc for information about this interface.

Implementing the run(CMSHistoryAction action) method

Before proceeding with the implementation, first obtain the instance of CMSHistoryView by using action.getHistoryView(). After you have obtained this, get the instance of CMSViewModel using the method myView.getModel() (you may have to cast this to a CMSViewModel type when assigning it). Check to see if either of these is equal to null, and return from the method if this is the case.

To retrieve the user’s selections in the History View, you will need to obtain the instance of CMSHistoryViewer by using the method action.getHistoryViewer(). Once you have the instance of CMSHistoryViewer, you can retrieve the user’s selections in the History View by using the following method:

TableItem[] sellist = viewer.getTree().getSelection();

As you iterate through this array of TableItem, you may find it useful to store the element’s data as a CMSViewModel variable. This can be done by calling getData() on the element in the array (again, you may have to cast this to a CMSViewModel type when assigning it).

In the course of implementing the method, you will probably find it necessary to obtain the name of the database connection that the selected item is associated with. This is needed to obtain the instance of and make calls to the CMApi class. To get the connection name, simply use CMSViewModel’s getConnectionName() method.

String connectionName = mdl.getConnectionName();

Note: You can obtain the current default connection name using CorePlugin.getDefaultConnection();

 

Adding Actions to the Task View:

The steps below summarize the process of adding actions to the Task View

1.       Modify plugin.xml to include an entry similar to one of the following:

Adding a toolbar button:

   <extension

         id="<extensionid>"  ID of the extension

         name="<extensionname>"  Name of the extension

point="com. ibm.rational.synergy.integration.ui.repositorytoolbarmenuaction">  Extension point

<taskviewtoolbarmenu

            label="<label>"  Text that is displayed on a menu selection

            image="<image>"  Location of the image relative to the project root that is to be displayed on the toolbar or context menu for this object when the class’ isEnabled method returns true

            disabledimage="<disabledimage>"  Location of the image relative to the project root that is to be displayed on the toolbar or context menu for this object when the class’ isEnabled method returns false

            position=”<position>” Numerical position of the button on the toolbar.

            tooltips="<tooltips>  Message that appears upon mouse hover over selection

            class="<class>"  Location of the class that contains the logic for the toolbar or menu item

           id="<id>">  ID for this object

      </taskviewtoolbarmenu> 

</extension>

Adding a context menu item:

   <extension

         id="<extensionid>"  ID of the extension

         name="<extensionname>"  Name of the extension

point="com. ibm.rational.synergy.integration.ui.repositorycontextmenuaction">  Extension point

<taskviewcontextmenu

            label="<label>"  Text that is displayed on a menu selection

            image="<image>"  Location of the image relative to the project root that is to be displayed on the toolbar or context menu for this object when the class’ isEnabled method returns true

            disabledimage="<disabledimage>"  Location of the image relative to the project root that is to be displayed on the toolbar or context menu for this object when the class’ isEnabled method returns false

            menugroup="<menugroup>"  This is only necessary if creating a context menu item

            tooltips="<tooltips>  Message that appears upon mouse hover over selection

            class="<class>"  Location of the class that contains the logic for the toolbar or menu item

           id="<id>">  ID for this object

      </taskviewcontextmenu> 

</extension>

3.       Create a class that implements the interface ICMSTaskAction and have its location specified in the “class” field above. Consult the Javadoc for information about this interface.

Implementing the run(CMSTaskAction action) method

Before proceeding with the implementation, first obtain the instance of CMSTaskView by using action.getTaskView(). After you have obtained this, get the instance of CMSViewModel using the method myView.getModel() (you may have to cast this to a CMSViewModel type when assigning it). Check to see if either of these is equal to null, and return from the method if this is the case.

To retrieve the user’s selections in the Task View, you will need to obtain the instance of CMSTaskViewer by using the method action.getTaskViewer(). Once you have the instance of CMSTaskViewer, you can retrieve the user’s selections in the Task View by using the following method:

TreeItem[] sellist = viewer.getTree().getSelection();

As you iterate through this array of TreeItem, you may find it useful to store the element’s data as a CMSViewModel variable. This can be done by calling getData() on the element in the array (again, you may have to cast this to a CMSViewModel type when assigning it).

In the course of implementing the method, you will probably find it necessary to obtain the name of the database connection that the selected item is associated with. This is needed to obtain the instance of and make calls to the CMApi class. To get the connection name, simply use CMSViewModel’s getConnectionName() method.

String connectionName = mdl.getConnectionName();

Note: You can obtain the current default connection name using CorePlugin.getDefaultConnection();

 

Adding Items to the Team Menu:

The Guide plug-in adds one new function to the Eclipse Team menu: View Task Properties. It does this by using the org.eclipse.ui.popupMenus extension point.

1.       Add the necessary XML tags to plugin.xml for the new Team menu action.

2.       Create a class that extends CCMAction and have its location specified in the “class” field of the XML tags added in step 1.

Implementing the run(IAction action) method

            In order to obtain the user’s selections for the team menu action, use the following code:

 

Hashtable table = getProviderMapping(getSelectedResources());

for (Iterator iter = table.keySet().iterator(); iter.hasNext();) {

CMSRepositoryProvider provider = (CMSRepositoryProvider) iter.next();

if(provider==null) {

UIPlugin.traceMessage("Provider is null", this.getClass().getName());

UIPlugin.reportMessage("The Team provider is null for this project.", Message.ERROR);

continue;

     }                      

List list = (List) table.get(provider);

final IResource[] providerResources = (IResource[]) list.toArray(new IResource[list.size()]);

}

This will first obtain a Hashtable of the providers based on the selected resources. It will then iterate through the table and check if any of the providers are null. If this is the case, then an error message will be outputted onto the console. Any resources that are part of a provider other than Synergy will be ignored. Otherwise, it will retrieve the selected objects associated with the provider and store them as an array of IResource.

 

Adding Items to the Eclipse Toolbar

1.       Add the necessary XML tags to plugin.xml for the new Team menu action.

2.       Create a class that extends SelectedResourceAction and have its location specified in the “class” field of the XML tags specified in step 1.

Implementing the run(IAction action) method

When creating a button in the Eclipse toolbar or a drop-down menu, you may find it necessary to obtain the user’s selections in the Navigator or Package Explorer views. To do this, use the following code:

final ArrayList selectedResources = getSelectedResource();
final IResource[] providerResources = new IResource[ selectedResources.size()];

            This will store the selected objects into an array of IResource.


Guide Plug-in Class Overview

Each Guide plug-in class file extends a different integration extension-point according to the functionality that it adds. The following chart outlines the classes and the extension-points of the integration that they extend.

 

Class Name

Description

Extension-point ID

com..integration.eclipse.guide.decorator.GuideTeamDecorator

Changes the default decorators for checked in, checked out, controlled, and restricted files displayed in the Navigator and Package Explorer views.

com.ibm.rational.synergy.integration.ui.teamdecorator

com.telelogic.integration.eclipse.guide.historyview.ObjectPropertiesButtonAction

Shows users a properties window of the object that is currently being viewed in the History View and is ran through a button the History View's toolbar.

com. ibm.rational.synergy.integration.ui.historytoolbarmenuaction

com.telelogic.integration.eclipse.guide.historyview.ObjectPropertiesContextAction

Shows users a Properties window of the object that is currently being viewed in the History View and is ran through the right-click context menu.

com. ibm.rational.synergy.integration.ui.historycontextmenuaction

com.telelogic.integration.eclipse.guide.repositoryview.RemoveObjectButtonAction

Removes an IBM Rational Synergy managed object from the Repository View via toolbar button.  This action is equivalent to performing a remove controlled files operation.

com. ibm.rational.synergy.integration.ui.repositorytoolbarmenuaction

com.telelogic.integration.eclipse.guide.repositoryview.RemoveObjectContextAction

Removes an IBM Rational Synergy managed object from the Repository View via context menu option. This action is equivalent to performing a remove controlled files operation.

com. ibm.rational.synergy.integration.ui.repositorycontextmenuaction

com.telelogic.integration.eclipse.guide.taskbar.FastCheckIn

Provides functionality to perform a check-in operation without confirmation on selected IBM Rational Synergy files in the Navigator View.

org.eclipse.ui.actionSets

com.telelogic.integration.eclipse.guide.taskbar.FastCheckOut

Provides functionality to perform a checkout operation without confirmation on selected IBM Rational Synergy files in the Navigator View..

org.eclipse.ui.actionSets

com.telelogic.integration.eclipse.guide.taskbar.FastUndoCheckOut

Provides functionality to perform an undo checkout operation without confirmation on selected IBM Rational Synergy files in the Navigator View..

org.eclipse.ui.actionSets

com.telelogic.integration.eclipse.guide.taskbar.QueryProject

Opens a new window that allows the user to input a query to open projects that match this query.

org.eclipse.ui.actionSets

com.telelogic.integration.eclipse.guide.taskview.DeleteObjectButtonAction

Task View toolbar button implementation that removes an object from its associated task. This is equivalent to an undo checkout operation.

com. ibm.rational.synergy.integration.ui.tasktoolbarmenuaction

com.telelogic.integration.eclipse.guide.taskview.DeleteObjectContextAction

Task View context menu implementation that removes an object from its associated task. This is equivalent to an undo checkout operation.

com. ibm.rational.synergy.integration.ui.taskcontextmenuaction

com.telelogic.integration.eclipse.guide.teammenu.ViewTaskProperties

Team menu function that displays a task properties window for every task that is associated with the selected objects.

org. ibm.rational.ui.popupMenus

 


 

Notices

This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. You can send written license inquiries to:

IBM Director of Licensing
IBM Corporation
North Castle Drive

Armonk, NY 10504-1785
U.S.A.


For license inquiries regarding double-byte character set (DBCS) information, contact the IBM Intellectual Property Department in your country or send written inquiries to:

IBM World Trade Asia Corporation
Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106-0032, Japan

The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions. Therefore, this statement may not apply to you.

This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice.

Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you. Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact:

Intellectual Property Dept. for Rational® Software
IBM Corporation
5 Technology Park Drive
Westford, MA 01886
U.S.A.

Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.

The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us.

Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurements may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.

This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental.

If you are viewing this information softcopy, the photographs and color illustrations may not appear.

Trademarks

See copyright notices on the Web at http://www.ibm.com/legal/copytrade.html.

Microsoft, Windows, and/or other Microsoft products referenced herein are either trademarks or registered trademarks of Microsoft Corporation.

UNIX is a registered trademark of The Open Group in the United States and other countries.

Eclipse is a registered trademark of the Eclipse Foundation.

Other company, product or service names may be trademarks or service marks of others.