Guide to IBM Rational Synergy for
Eclipse Interface Extension Points |
IBM Corporation |
|
© Copyright IBM Corporation 2005, 2011
U.S. Government Users Restricted Rights - Use, duplication, or disclosure
restricted by GSA ADP Schedule Contract with IBM Corp.
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
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.
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.
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 |
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
IBM Corporation
North Castle Drive
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
Eclipse is a registered trademark of the Eclipse Foundation.
Other company, product or service names may be trademarks or service marks of others.