Plug-ins and application classes

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:

Overview

Contains fields for modifying the base attributes of the plug-in, such as such as its plug-in identifier, or ID, and version.

Dependencies

Lists the plug-ins required by this plug-in. If you need to use a function available in another plug-in, use this tab to add a dependency on the plug-in.

Runtime

Displays the list of Java™ packages available for use by plug-ins that depend on this plug-in.

Extensions

Displays the extension points that are extended by this plug-in.

Extension Points

Displays the extension points defined by a HATS rich client plug-in. By default, no extension points are defined in a HATS rich client plug-in.

Build

Enables you to configure which files are included when this plug-in is built during an export operation. If you add other files to this plug-in, you might need to modify this list.

Notes:

1. If you add non-Java source files to a plug-in project, you need to update the build.properties file for the plug-in. The build.properties file controls which files are included when a project is exported as a plug-in (first step of deployment). This file is located at the root of the plug-in project and can be edited using the plug-in manifest editor.
2. If you create a new folder in a plug-in project, the new folder is not included when you export the plug-in unless you add the folder in the Build tab.

MANIFEST.MF

Shows the source view of the plug-in MANIFEST.MF file. You should use the Overview, Dependencies, and Runtime tabs to make changes to this file instead of editing the source directly.

plugin.xml

Shows the source view of the plugin.xml file. You should use the Extensions and Extension Points tabs to make changes to this file.

build.properties

Shows the source of the build.properties file. You should use the Build tab to make changes to this file.

Plug-in project extension points

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.

Allowing only one instance of an application

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:

1. Open the plug-in manifest file for the project by clicking Open the plug-in manifest on the Overview page of the Project Settings editor.
2. Click the Extensions tab.
3. In the All Extensions tree, expand the org.eclipse.ui.views node and select the node corresponding to your project. By default, only one view is listed.
4. In the Extension Element Details section, change the allowMultiple setting from true to false.
5. Save the file.

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.

HATS runtime extension plug-in

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:

• Trace and log settings
• Generated trace and log files
• Registration of key mappings
• Registration of preference pages
• Registration of properties pages

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.

Table 2 lists and describes the files included in this plug-in that are not specific to HATS.

Table 3 lists the extensions contributed by the HATS RCP runtime extension plug-in.

org.eclipse.ui.defaultAcceleratorConfiguration.

com.ibm.workplace.notes.hannoverConfiguration.

Application classes

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.

HostAccessApplication

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:

Windows:

eclipse.exe -application com.ibm.hats.rcp.runtime.extension.application

Linux:

./eclipse -application com.ibm.hats.rcp.runtime.extension.application

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:

Windows:

eclipse.exe -product com.ibm.hats.rcp.runtime.extension.product

Linux:

./eclipse -product com.ibm.hats.rcp.runtime.extension.product

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.

HostAccessWorkbenchAdvisor

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:

Windows:

eclipse.exe -product com.ibm.hats.rcp.runtime.extension.product -perspective myCompany.myCustomPerspective

Linux:

./eclipse -product com.ibm.hats.rcp.runtime.extension.product -perspective myCompany.myCustomPerspective

HostAccessWorkbenchWindowAdvisor

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.

Controlling the size of the workbench window

Follow these steps to change the default size of the workbench window:

1. From the Navigator or Package Explorer view, open the HostAccessWorkbenchWindowAdvisor class located in the hostaccess package of the com.ibm.hats.rcp.runtime.extension plug-in project.
2. Find the preWindowOpen() method and change the parameter passed to the setInitializeSize method of the IWorkbenchWindowConfigurer object. For example, to set the initial window size to 800 pixels wide and 600 pixels tall, update or add the following code:

   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);       
}

Showing the perspective bar

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:

1. From the Navigator or Package Explorer view, open the HostAccessWorkbenchWindowAdvisor class located in the hostaccess package of the com.ibm.hats.rcp.runtime.extension plug-in project.
2. Find the preWindowOpen() method and update it to call the setShowPerspectiveBar method of the IWorkbenchWindowConfigurer object. to true:

   public void preWindowOpen() {
   IWorkbenchWindowConfigurer configurer = getWindowConfigurer();
   configurer.setShowPerspectiveBar(true);
   ... 
   }

HostAccessActionBarAdvisor

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.

 fileMenu.add(printAction);

Customizing the workbench window toolbar

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.

1. Update the HostAccessWorkbenchWindowAdvisor.preOpen() method to show the workbench window's coolbar area. This method has already been implemented, so you only need to add the call to the setShowCoolBar(boolean) method:

       public void preWindowOpen() {
           ...
           configurer.setShowCoolBar(true);
           ...
       }

2. Add a new private member to the HostAccessActionBarAdvisor:

   private LaunchApplicationAction launchAppAction;

3. Add code to the HostAccessActionBarAdvisor.makeActions() method to create a new instance of the LaunchApplicationAction class. The constructor for this class takes two arguments:
   1. The ID of the HATS rich client application
   2. The IWorkbenchWindow object, which is passed into the makeActions() method):

          protected void makeActions(final IWorkbenchWindow window) {
              ...
              launchAppAction = new LaunchApplicationAction("myPlugin", window);
          }

4. Add or update the ApplicationActionBarAdvsior.fillCoolBar() method to create a toolbar, add the new launcher action to the toolbar, and then add the toolbar to the coolbar:

   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"));   
   
   }

5. Launch a new Eclipse workbench. You should have a new toolbar item that, when clicked, will open a new instance of the transformation view associated with this plug-in.

Figure 1. Launching a new workbench