A plug-in is a structured component that describes itself to the Eclipse platform using an OSGi manifest (MANIFEST.MF) file and a plug-in manifest (plugin.xml) file. A HATS rich client project is an Eclipse plug-in project that contains artifacts needed for generating a plug-in that runs in an Eclipse environment, such as Lotus Notes® or Lotus® Expeditor Client. Plug-in projects are developed using the Eclipse Plug-in Development Environment (PDE), which is a component of the Eclipse Software Development Kit (SDK). The Rational® Software Delivery Platform (SDP) extends the Eclipse SDK, and HATS further extends the Rational SDP. For more information on the Eclipse PDE, go to http://www.eclipse.org/pde/.
One tool provided by the Eclipse PDE is the plug-in manifest editor. This editor is used to modify the files that describe the plug-in to the Eclipse environment where it is running. Plug-ins generally have two manifest files: plugin.xml and MANIFEST.MF (plugin.xml is optional if the plug-in is not extending another plug-in). If you open either file in the workbench, the same editor is opened, but fields in the editor are tied to different files. The plugin.xml describes how the plug-in extends the platform, what extensions it publishes itself, and how it implements its functionality. The MANIFEST.MF file indicates the ID, version, vendor, and the other plug-ins required by this plug-in.
To edit the plug-in manifest for a HATS rich client project, click the Open the plug-in manifest link on the Overview page of the Project Settings editor. The editor will have the following tabs:
When a plug-in wants to allow other plug-ins to extend or customize portions of its functionality, it will declare an extension point. The extension point declares a contract, typically a combination of XML markup and Java interfaces, that extensions must conform to. Plug-ins that want to connect to that extension point must implement that contract in their extension. The key attribute is that the plug-in being extended knows nothing about the plug-in that is connecting to it beyond the scope of that extension point contract. This allows plug-ins built by different individuals or companies to interact seamlessly, even without their knowing much about one another.
The com.ibm.hats.rcp.runtime.rcpApplications extension registers your HATS rich client plug-in plug-in with the HATS runtime. This is how the HATS runtime knows which plug-ins are HATS application plug-ins. The Applications view is populated based on plug-ins that implement this extension point. This extension point also indicates which view (by default, your transformation view) is opened when an instance of your application is launched.
The HATS RCP project uses the Eclipse org.eclipse.ui.views extension to register the transformation view class in this plug-in with the Eclipse platform.
By default, a user can work with multiple instances of a HATS rich client application at one time by opening multiple instances of the application's transformation view. To restrict a user from starting multiple instances of an application, you can set a flag in the plug-in manifest file, plugin.xml, for the plug-in project. This flag tells Eclipse to allow only one instance of the application's view. To set this flag:
At runtime, if a user attempts to open a second instance of the application, the view corresponding to the first application instance receives the focus.
When you create a HATS rich client plug-in project, a HATS rich client runtime extension plug-in project is also created if one does not already exist in the workspace. This plug-in contains files and settings that are common between all HATS rich client plug-ins running in an environment. This includes, but is not limited to:
The default name and ID of this plug-in is com.ibm.hats.rcp.runtime.extension, and its initial version is 1.0.0.
This plug-in is similar to a HATS EAR project in that it contains files that are common between multiple HATS applications. Unlike a HATS EAR project, only one of these plug-ins can run in an Eclipse environment at one time. This means that trace settings, keyboard mappings, and so forth apply to the entire rich client environment and cannot be configured at the plug-in project level.
Table 1 lists and describes the files included in this plug-in.
File or folder | Description |
---|---|
images (folder) | Contains images for the Applications and Print
Jobs views, and an image for an Expeditor application.
Note:
If an image is only used by a single HATS
application plug-in, for example, to include an image with a template,
consider including it in the application plug-in rather than the runtime
extension plug-in. |
logs (folder) | Contains HATS trace and messages files. |
product.xml | Indicates the version of HATS used to generate this plug-in project. This file is updated when service packs are applied. |
runtime.properties | HATS runtime settings, including settings to enable tracing. |
runtime-debug.properties | Same settings as runtime.properties, but only used when an Eclipse runtime workbench is launched in debug mode. |
Table 2 lists and describes the files included in this plug-in that are not specific to HATS.
File or Folder | Description |
---|---|
build.properties | Indicates which files should be packaged in the plug-in when it is exported from the development environment. |
MANIFEST.MF | Plug-in descriptor. Indicates ID, name, version of the plug-in, and plug-in dependencies. |
plugin.xml | Plug-in descriptor. Indicates the extensions contributed by this plug-in. |
plugin_xx.properties | Contains translated strings used by plugin.xml and MANIFEST.MF. |
Table 3 lists the extensions contributed by the HATS RCP runtime extension plug-in.
Extension Point ID | Description |
---|---|
org.eclipse.core.runtime.applications | Registers the application class provided in the HATS RCP runtime extension plug-in with the Eclipse platform. See Application classes for more information. |
org.eclipse.core.runtime.products | Defines a product that references the application registered with the org.eclipse.core.runtime.applications extension point. See Application classes for more information. |
org.eclipse.ui.perspectives | Registers the Host Access perspective class provided in the HATS RCP runtime extension plug-in with the Eclipse platform. See Perspectives and views. |
org.eclipse.ui.views | Registers the Applications and Print Jobs views with the Eclipse platform. |
org.eclipse.ui.propertyPages | Registers the application
properties pages with the Eclipse platform. These pages are displayed
when a user right-clicks on an application in the Applications view
and selects Properties. You can prevent a page from being available
to your users by removing or commenting out its declaration.
Note:
The Connection Parameters Overrides page only appears if
connection parameter overriding is enabled in your project. The Variables
Override page only appears if global variable overriding is enabled
in your project. |
org.eclipse.ui.actionSets | Registers the print action used to print what is being displayed on the transformation view. |
org.eclipse.ui.preferencePages | Registers the preferences pages provided by HATS. Preferences are usually available by selecting File > Preferences or Window > Preferences (depending on the Eclipse environment). You can prevent a page from being available to your users by removing or commenting out its declaration. For example, to prevent a user from modifying trace or service settings, you can remove the declared extension for the Troubleshooting page. |
org.eclipse.ui.contexts | Registers the Host Access keyboard context. A context defines a group of related commands. |
org.eclipse.ui.commands | Registers commands for each of the available actions. A command represents a request from an end user that can be handled by an action. |
org.eclipse.ui.bindings | Registers the default keyboard shortcut for a specific command.
You can change the default shortcut for a command by modifying the sequence attribute
of the declaration. A user can override the shortcut for a command
using the Keys preferences pages.
The key mappings are defined per scheme ID based on the intended runtime client. The schemeId for both Eclipse RCP and Lotus Expeditor Client is:
The schemeId for Lotus Notes is:
Note:
For examples, see the section, Remapping keys for HATS rich client applications in
the HATS User's and Administrator's Guide. |
com.ibm.eswe.workbench.WctApplication | Registers the Host Access perspective with Lotus Expeditor Client and Lotus Notes. This extension point is used by Lotus Expeditor Client and Lotus Notes to populate the list of applications
displayed on the Open menu. See Applications in the Lotus Expeditor documentation for more information.
Note:
This declaration does not appear if there are no projects
in your workspace targeted for deployment to Lotus Expeditor Client or Lotus Notes. |
The classes described in this section are responsible for starting and configuring the Eclipse rich client platform environment. For more information on the function and default implementations of these classes, see the Eclipse documentation at http://www.eclipse.org/documentation/, select your version of Eclipse, and search for the section named Building a Rich Client Platform application.
An Eclipse Application class is the main entry point in an Eclipse environment. When the Eclipse platform starts, it finds and loads the specified application.
A default application class, HostAccessApplication, is provided in the HATS RCP runtime extension plug-in project. This class creates a new workbench window configured by the HostAccessWorkbenchWindowAdvisor class, which is also provided.
To use the provided application as the main entry point for an Eclipse environment instance, specify the application's ID in the application argument:
An Eclipse product is responsible for branding an Eclipse environment. Branding includes defining an "About" dialog, setting window icons, defining default preferences, and specifying a splash screen which is displayed when the platform starts. For more information on branding, see the Eclipse documentation at http://www.eclipse.org/documentation/, select your version of Eclipse, and search for the section named Customizing a product. A default product is defined in the HATS runtime extension plug-in (com.ibm.hats.rcp.runtime.extension.product). To start the Eclipse platform using this product, specify the product's ID in the product argument:
Because the product extension point indicates which application to use, specifying an application is not required when a product is specified. In the case of the HATS runtime extension plug-in product, the HATS runtime extension plug-in application is used by default.
An Eclipse WorkbenchAdvisor class is responsible for specifying the default perspective and constructing a WorkbenchWindowAdvisor object, which is in turn responsible for configuring the workbench window. An implementation of this class is provided for you in the HATS RCP runtime extension plug-in. This class, HostAccessWorkbenchAdvisor, returns a new instance of an HostAccessWorkbenchWindowAdvisor object and specifies hostaccess.perspectives.main as the default perspective. This is why the Host Access perspective is displayed by default when a new workbench window is opened. If you have created a custom perspective, you can update the getInitialWindowPerspectiveId() method to return the ID of this perspective. Alternatively, you can specify the perspective when Eclipse is launched using the -perspective argument:
An Eclipse WorkbenchWindowAdvisor class is responsible for configuring an Eclipse workbench window, including its size, location, and style. An implementation of this class is provided for you in the HATS RCP runtime extension plug-in. This class, HostAccessWorkbenchWindowAdvisor, specifies the initial size of the workbench window and hides the coolbar and status line areas since HATS does not contribute to these areas by default.
This class is also responsible for creating the action bar advisor. An action bar advisor is primarily responsible for configuring the menu bar of the workbench window. See HostAccessActionBarAdvisor for more information on customizing the menu bar and toolbar of the workbench window.
Follow these steps to change the default size of the workbench window:
public void preWindowOpen() {
IWorkbenchWindowConfigurer configurer = getWindowConfigurer();
configurer.setInitialSize(new Point(800, 600));
...
}
To automatically maximize the workbench window by default when it is opened, implement the postWindowCreate() method of the HostAccessWorkbenchWindowAdvisor class:
public void postWindowCreate() {
PlatformUI.getWorkbench().getActiveWorkbenchWindow().
getShell().setMaximized(true);
}
The perspective bar, which resides near the top of the workbench window, provides quick access to perspectives that are already open, and provides the ability for end users to open a new perspective. Showing the perspective bar is a quick and easy way to allow your end users to work with different perspectives. To show the perspective bar:
public void preWindowOpen() {
IWorkbenchWindowConfigurer configurer = getWindowConfigurer();
configurer.setShowPerspectiveBar(true);
...
}
An Eclipse ActionBarAdvisor class is responsible for configuring the action bars (toolbar, coolbar, menu bar, status line) for a workbench window. An implementation of this class is provided for you in the HATS RCP runtime extension plug-in. This class, HostAccessActionBarAdvisor, creates the actions on the menu bar, including the items under the File menu.
Table 4 lists the methods can be implemented or extended by the HostAccessActionBarAdvisor class.
Method | Description |
---|---|
makeActions(IWorkbenchWindow window) | Action objects should be created and initialized in this method. |
fillMenuBar(IMenuManager) | Populates the workbench window's menu bar with
menus and submenus. The current implementation of this method creates
and populates File, Window, and Help menus. To
hide an action that is already showing on the menu, avoid adding it
to the MenuManager. For example, to hide the Print action, remove
the following line from fillMenuBar() method:
Note:
The fillMenuBar() method is only applicable if
the workbench's IWorkbenchWindowConfigurer indicates that the menu
bar should be shown. |
fillCoolBar(ICoolBarManager) | Populates the workbench window's cool bar with
items.
Note:
The fillCoolBar() method is only
applicable if the workbench's IWorkbenchWindowConfigurer indicates
that the cool bar should be shown. |
To demonstrate how the HostAccessActionBarAdvisor class can be extended, the following steps show how to add a toolbar item to the main coolbar area of the workbench window. When clicked, a new instance of a specified HATS rich client application opens.
public void preWindowOpen() {
...
configurer.setShowCoolBar(true);
...
}
private LaunchApplicationAction launchAppAction;
protected void makeActions(final IWorkbenchWindow window) {
...
launchAppAction = new LaunchApplicationAction("myPlugin", window);
}
protected void fillCoolBar(ICoolBarManager coolBar) {
// Create toolbar manager
IToolBarManager mainToolbar = new ToolBarManager(SWT.FLAT | SWT.RIGHT);
// Add the launch action to the toolbar manager
mainToolbar.add(launchAppAction);
// Add the main toolbar to the window coolbar
coolBar.add(new ToolBarContributionItem(mainToolbar, "main"));
}