In this chapter, we look at turning an Eclipse configuration into a product. When an Eclipse product is created, the anonymous collection of plug-ins takes on application-specific branding, complete with custom images, splash screen, and launcher. In creating your own product, you typically also need to write an installer and uninstaller and consider how your users will obtain and upgrade your product.
Strictly speaking, a product is an extension to the extension point called org.eclipse.core.runtime.products. The purpose of a product is to define application-specific branding on top of a configuration of Eclipse plug-ins. Minimally, a product defines the ID of the application it is associated with and provides a name, description, and unique ID of its own. A product also stores a table of additional properties, where the UI stores information such as the application window icon and the all-important blurb in the Help > About... dialog. It is quite possible to run Eclipse without a product, but if you want to customize the appearance of Eclipse for your particular application, you should define one.
Because more than one product can be installed at a given time, the main product is singled out in a special marker file called .eclipseproduct in the Eclipse install directory. This file denotes the name, ID, and version number of the main product that will be used. The product in turn is a plug-in in the plugins directory, which includes product branding elements, such as the splash screen and workbench window icons.
For more details, see the methods declared by the IProduct interface defined in the org.eclipse.core.runtime plug-in. IProductConstants in the org.eclipse.ui.workbench defines the keys of product properties that are of interest to Eclipse products having user interfaces.
At first glance, the notions of product and application in Eclipse seem similar. Both are contributed via an extension point, and both are used to bring order to the chaos of an otherwise random collection of executing Eclipse plug-ins. However, the two concepts have some important differences. First, whereas an application defines behavior—it has code associated with it—a product is purely declarative. That is, a product provides properties, such as icons and text, that are used to customize the appearance of a running application. A second distinction is that there is typically only one product, but that product may include several applications. For example, the Eclipse Platform is a single product but includes several applications, such as the workbench application and an application for running custom Ant build files. All applications under a given product have the same branding elements associated with them.
That depends. If you just got started and are still testing your plug-ins or if you have few internal customers, you may be happy with simply building a plug-in and providing your users with a Zip file. Once you get more professional and have access to a Web site where people can access your plug-ins, an update site is recommended. To be in full control of how and where your offering is installed, you could use a more traditional form of product installation through a custom installer program.
Most Eclipse-based commercial product offerings ship their own product plug-ins using a professional installation program, such as InstallShield, or using a free one, such as the Install Toolkit for Java (from IBM AlphaWorks). Such installation tools provide the flexibility of user-defined scripts that are run during installation to discover already installed Eclipse installations, to query the registry on Windows, and most important, to provide graceful uninstall capabilities.
For example, IBM’s WebSphere Studio Device Developer is shipped as a set of plug-ins and embedded Java runtimes, together with the latest release of Eclipse, designed to install from a CD-ROM. The product can be installed stand-alone or added to an existing IBM product, such as WebSphere Studio Application Developer. Doing the installation with a product like InstallShield allows for this kind of flexibility during the installation.
Once the product has been installed, it is recommended that the Eclipse Update Manager be used to check for updates and that an update site be used for delivering new features or feature upgrades to users. This is the way users of WebSphere Studio Device Developer can add support for embedded platforms that were added recently or that are provided by third parties.
Note
InstallShield (http://www.installshield.com)
Install Toolkit for Java (free) (http://www.alphaworks.ibm.com)
Yes. A product that adds functionality to another installed product is called a product extension. A product extension is installed in a location separate from the main product, making it cleaner to install, uninstall, and upgrade both the product and any product extensions. The exact format of a product extension is well described in the Platform Plug-in Developer Guide, under Programmer’s Guide > Packaging and delivering Eclipse based products > Product extensions.
The Eclipse Web site contains a list of suitable logos and wordmarks to download for varying use, such as either four-color-process offset printing, desktop publishing, Web sites, and embroidery applications. Users are advised to use the original artwork and not to redraw or redesign it for any purpose.
Writing a plug-in install handler is appropriate for most professional applications. Doing so is not only a comfort that most end users will expect but also allows you to perform custom installation, such as
Moving data to other locations in the file system outside the install directory. This allows data to be shared by multiple applications or by multiple versions of your application.
Reading or saving values in the Windows registry.
Asking the user to confirm licensing terms.
Searching for installed components, such as ActiveX or database drivers, that your application requires and installing them, if necessary.
When creating a feature using the PDE wizard, you get the option to specify an optional feature-specific install handler.
Almost all plug-ins in Eclipse use java.util.ResourceBundle, a messages.properties file, and look up messages by using a key. The MessageFormat class can be used to insert parameters into the translated message. Here is an example:
String translate(String key, String[] parms) {
try {
ResourceBundle bundle =
ResourceBundle.getBundle("messages");
String msg = bundle.getString(key);
return MessageFormat.format(msg, parms);
} catch (MissingResourceException e) {
return key;
}
}
Eclipse includes special support to replace constant strings in your plug-in source code by equivalent Java code that uses key-based lookup. Execute the context menu option Source > Externalize Strings... and follow the instructions. To save memory, we recommend choosing a short prefix for the generated keys.
If you reject translation of a given string, the externalization tool will place comments like //$NON-NLS-1$ at the end of the line that contains the string. Otherwise, it will replace the string by the lookup code.
Caveat: In the current Eclipse distribution, the various plug-ins declare and ship around 30,000 property keys to support multiple languages. The bytes these keys occupy amount to roughly 8 percent of the uncompressed distribution size. But, more important, resource bundles are loaded whole, as in the preceding sample. This happens even when no string is ever loaded from it. Therefore, a large properties file can easily generate a lot of wasted space.
Conservative estimates have shown that a typical Eclipse launch uses upward of 1MB to store the keys in memory. This memory is used by the ResourceBundle implementation, which typically uses a hash table and by the classes that declare and pass a key to the resource bundle to translate the string. The keys are stored in the class files of the plug-in and saved somewhere in the JVM’s data structures. In short, there is a big incentive to keep property keys short. For large offerings delivered on top of Eclipse, one should consider writing specialized ResourceBundle subclasses that use integer constants to lookup string bindings, for instance.
The Eclipse workbench icon is defined by the Eclipse product. This file is specified in the about.ini file in the product plug-in’s install directory, using the key windowImage if only a single 16×16 icon is provided, or windowImages if the product has both 16×16 and 32×32 icons. Note that these about.ini constants are defined by the IProductConstants interface in org.eclipse.ui.workbench.
As a debugging aid, many Eclipse developers hack the icon for their runtime workbench to make it easy to distinguish from the development workbench. This saves you from accidentally deleting your work while you try to reproduce some bug in a test environment. Simply check out the org.eclipse.platform plug-in from the Eclipse repository, and replace eclipse.gif with any other icon. Now, every runtime workbench will have that custom icon in the upper left-hand corner.
Most of the time, it is not necessary to write your own customized native launcher. The default launcher supports a large number of command-line arguments, allowing you to customize the splash screen, plug-in configuration, JVM, and much more. In some cases, you may want to wrap the native launcher in another launcher to prime the set of command-line arguments passed to the default launcher.
If you do need to write your own native launcher, the obvious place to start is by looking at the source code for the Eclipse launcher. This source is found in the Eclipse CVS repository in the platform-launcher project.
The splash screen that appears during start-up is provided by the Eclipse product. On start-up, the platform looks for a file called splash.bmp in the product plug-in’s install directory. The Eclipse launcher, such as eclipse.exe on Windows, specifies the name of the command to run for showing the splash screen using the -showsplash command-line argument. If you are not defining your own custom launcher, all you need to do is place the splash image in the product’s install directory, and the launcher will find and open it.
See the Eclipse Web site (http://eclipse.org) and click Projects > The Eclipse Project > Platform > Update > Development Resources for elaborate documentation on updating Eclipse-based products.