Eclipse Tip: Customize Your Feature Installation with Install Handlers
When developing an Eclipse RCP-based application, you get to decide how to install it into the end-user's environment; Eclipse does not force you into using any particular installation method. Ordinarily, a third-party installer is used for the job. The good ones typically let themselves be branded with custom logos and splash images.
Even products packaged as Features, which can be installed into a variety of Eclipse-based applications (such as the Eclipse IDE) may utilize a custom installer. More often, however, software vendors choose to distribute them by means of an Update Site. This way the user can use the Update Manager to install the Feature from within the chosen Eclipse application.
Eclipse users familiar with this process probably know it to be rather straightforward; after connecting to a given Update Site, a list of available Features is displayed, the user then chooses one or more of them, accepts the license, and finally waits for the relevant plug-ins to be downloaded and installed. Other than the familiar progress bar there is not much to look at in the meantime (of course, the user may choose to send the job into background and carry on with what they were doing before).
Feature Installation Process
While the Update Manager itself is currently not easily brandable, there is a sparsely documented API (marked as "experimental" since version 2.0) that allows for limited customization of the Feature installation process. This API allows features to provide their own Install Handlers, which are objects that participate in the installation, configuration, and uninstallation of any Feature that uses them. The primary purpose of this mechanism is to support non-standard installation requirements, such as OS-specific component registration or special handling of the downloaded data. However, a custom Install Handler can also be used to display a simple splash screen while the Feature is downloaded.
An Install Handler bundled with the Feature that uses it must be treated specially by the Eclipse run-time. While it is possible to contribute an Install Handler through an extension point (org.eclipse.update.core.installHandlers) as an ordinary plug-in, this approach would only make it available for subsequent Feature installs. The other option is to bundle a JAR containing the Install Handler code inside the Feature JAR itself. The Feature JAR is downloaded even before the installation process begins. The platform then provisions a special execution environment for the Install Handler code, one that effectively gives it access to plug-ins org.eclipse.core.runtime, org.eclipse.update.core, and optionally (unless running in the headless mode) org.eclipse.ui. This means that the Install Handler code may interact with the Eclipse UI, but must also be prepared to handle a situation in which this is not available.
Developing A Custom Install Handler
Developing a custom Install Handler is little less straightforward. While it is possible to use the New Feature wizard to specify that an Install Handler will be provided, PDE does not currently set up the Feature project with the necessary dependencies. To get around this, you can develop the Install Handler code as a regular plug-in, which will allow you to set it up with the right dependencies. You can then export it into a regular JAR and bundle it with the Feature itself.
The example provided in the Resources section contains a plug-in project named my.installHandler that is set up just this way. The Install Handler implementation (MyInstallHandler) extends BaseInstallHandler and overrides its installInitiated() method, which is where a splash screen is displayed. The splash screen code itself is not the subject of this tip; suffice it to say that it displays a GIF image for three seconds. No dependencies on Eclipse UI code are exposed and all UI classes are accessed carefully to contain linkage errors when the handler happens to be instantiated in a headless environment. Care is also taken to access any widgets in the UI thread (since the installation is likely to be run in a non-UI thread).
Using The Install Handler In A Feature
To use this handler in a Feature, we must first package it as a JAR that will get bundled in the Feature JAR along with feature.xml (and possibly other artifacts). The easiest way to accomplish this is to use the Export JAR wizard and save it as a *.jardesc file in the Feature project. This file can then be used to easily rebuild the JAR whenever there are changes. The bundle manifest need not be included, as the handler code is not going to be deployed as a regular plug-in.
Second, the Feature manifest must be modified to specify the custom Install Handler. This can be done using PDE's Feature Manifest Editor; on its Installation page, section Install Handler, enter the name of the handler JAR in the Library field and its fully qualified class name in the Handler field. Listing 1 shows the resulting feature.xml snippet.
Testing The Result
To see your custom Install Handler in action, you have to actually build and deploy the feature, then install it into an existing Eclipse installation. You can even use the one you use for development –– it is rather easy to remove the feature from your configuration after you've seen the splash screen.
A ZIP archive with the example feature ready to be deployed is provided in the Resources section. Unzip it into a temporary directory, which you can then use to set up a Local Site. In your Eclipse Workbench, click Help –> Software Updates –> Find and Install... Choose Search for new features to install and click Next. Click New Local Site... and select your temporary directory. While the feature and its plugins are downloaded and installed (which will only take a few seconds in this case), you should see a large splash image displayed on your screen.
Alternatively, create a new Remote Site using the URL listed in the Resources section. This will allow you to download and install the example feature from a makeshift update site created specifically for this article.
- Source code (Eclipse projects) for the example (requires Eclipse 3.2 or later)
- Deployable example feature
- Live update site for the example (use this link's URL)
- Eclipse Help: Feature manifest
- Eclipse Help: Updating features with the update manager
About the Author
Peter Nehrer is a software consultant specializing in Eclipse-based enterprise solutions and J2EE applications. He is the founder of Ecliptical Software Inc. and a contributor to several Eclipse-related Open Source projects. He holds an M.S. in Computer Science from the University of Massachusetts at Amherst, MA. Peter can be reached at pnehrer AT eclipticalsoftware DOT com.