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
<feature
id="my.feature"
label="Feature Feature"
version="1.0.0">
<install-handler
library="my.installHandler.jar"
handler="my.installHandler.MyInstallHandler"/>
...
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.
Resources
- 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.
