The Eclipse plug-in directory for Lotus Notes and Domino

Learn how to work with the Eclipse directory --also known as a JAR file -- in your Lotus Notes and Domino environments.

The following is tip #2 from "Developing Eclipse plug-ins for Lotus Notes and Domino -- 7 tips in 7 minutes," excerpted from Chapter 3 of the book Eclipse: Building Commercial Quality Plug-ins, published by Addison-Wesley Publishing.

Plug-in directory or JAR file

The Favorites plug-in directory (or JAR file, see the first entry below) contains files similar to a typical plug-in, including *.jar files containing code, various images used by the plug-in, and the plug-in manifest.

favorites.jar - A file containing the actual Java classes comprising the plug-in. Typically, the JAR file is named for the last segment in the plug-in's identifier, but it could have any name, as long as that name is declared in the META-INF/MANIFEST.MF file. In this case, since the Favorites plug-in identifier is com.qualityeclipse.favorites, the JAR file is named favorites.jar.

icons - Image files are typically placed in an icons or images subdirectory and referenced in the plugin.xml and by the plug-in's various classes. Image files and other static resource files that are shipped as part of the plug-in can be accessed using methods in the plug-in class.

META-INF/MANIFEST.MF - A file describing the runtime aspects of the plug-in such as identifier, version, and plug-in dependencies.

plugin.xml - A file in XML format describing extensions and extension points.

The plug-in directory must have a specific name and be placed inside a specific directory so that Eclipse can find and load it. The directory name must be a concatenation of the plug-in identifier, an underscore, and the plug-in version in dot-separated form, as in:com.qualityeclipse.favorites_1.0.0

The plug-in directory must be located in the plugins directory as a sibling to all the other Eclipse plug-ins, as is the case for the Favorites plug-in.

As of Eclipse 3.1, the plug-in can be delivered as a single JAR file containing the same files as a plug-in directory. If you wish to deliver the plug-in as a single JAR file rather than a directory of files, then it must be named in exactly the same way with a ".jar" suffix, as in com.qualityeclipse.favorites_1.0.0.jar

Whenever we refer to a "plug-in directory," we are also referring to this alternate JAR file format.

Link files

Alternatively, plug-in directories comprising a product may be placed in a separate product-specific directory, and then a link file can be provided for Eclipse so that the program can find and load these plug-ins. Not only does this approach satisfy Ready for Rational Software (RFRS) requirements, but it also allows for multiple installations of Eclipse to be linked to the same set of plug-ins. You must make several modifications to the Favorites example so that it can use this alternate approach.

To begin, remove the existing Favorites plug-in in its current form from the Development Workbench. Next, modify the Ant-based build-favorites.xml file so that the Favorites plug-in conforms to the new structure by inserting QualityEclipse/Favorites/eclipse in two places; then replace the following:

<property name="plugin.jar" location=
   "${build.temp}/jars/plugins/${plugin.dir}.jar" />

with this (location must be on a single line)

<property name="plugin.jar" location=
      eclipse/plugins/${plugin.dir}.jar" />

Next, replace this:

<mkdir dir="${build.temp}/jars/plugins" />
with this (all on a single line):
<mkdir dir="${build.temp}/jars/QualityEclipse/Favorites/
   eclipse/plugins" />

When making these modifications, be sure that the location string is all on a single line; Ant does not handle paths that span multiple lines. When the modified build-favorites.xml is executed, the resulting zip file contains a new structure:


The zip file can be unzipped to any location, but for this example, assume that the file is unzipped into the root directory of the C drive so that the plug-in directory is:


The locations for the Eclipse product directory and the Quality-Eclipse product directory are determined by the user and thus are not known at build time. Because of this, the link file that points to the Quality-Eclipse product directory must be manually created for now. Create the links subdirectory in the Eclipse product directory (e.g., C:\eclipse\links) and create a new file named that contains this single line:


To do this in Windows, you can use Notepad to create and save the file as a txt file, which you can then rename appropriately. Note that the path in the *.link file must use forward slashes rather than backslashes. The new *.link file will be used by Eclipse once Eclipse has been restarted.

Note: No Relative Paths in Link Files

Eclipse 3.1 does not allow link files to contain relative paths. This restriction may be changed in future versions (see for Bugzilla entry 35037).

Hybrid approach

Some products use a hybrid approach, delivering the product in multiple forms. When installing, the installer places product plug-ins directly in the Eclipse plug-ins directory, whereas when installing into Rational Application Developer or any of the other Rational IDE family of products, the product plug-ins are placed in a separate product directory and a link file is created. In addition, these products are available in various zip file formats, each targeted at a specific type and version of an Eclipse or WebSphere product. This hybrid approach facilitates a simpler and smaller zip-based installation for Eclipse where Ready for Rational Software (RFRS) certification is not required, and a cleaner and easier installer-based installation for the Rational IDE family of products.

After you install the QualityEclipse product and create the link file as just described, the QualityEclipse product is ready for use. Verify that you have correctly installed the QualityEclipse product in its new location by restarting Eclipse and opening the Favorites view. After you have installed and verified the product, be sure to uninstall it by deleting the link file so that the JUnit tests will still run successfully.

Developing Eclipse plug-ins for Lotus Notes and Domino

 Home: Introduction
 Tip 1: The Eclipse plug-in structure for Lotus Notes and Domino
 Tip 2: The Eclipse plug-in directory for Lotus Notes and Domino
 Tip 3: The Eclipse plug-in manifest for Lotus Notes and Domino
 Tip 4: The Eclipse plug-in classes for Lotus Notes and Domino
 Tip 5: The Eclipse plug-in model for Lotus Notes and Domino
 Tip 6: Eclipse logging for Lotus Notes and Domino
 Tip 7: Eclipse plug-in types for Lotus Notes and Domino

This chapter is excerpted from Eclipse: Building Commercial-Quality Plug-ins, 2nd Edition, by Eric Clayberg and Dan Rubel, published by Addison-Wesley Professional in March 2006. Copyright 2006 Pearson Education Inc. ISBN: 032142672X. Reprinted with permissions, all rights reserved. Click here to see a complete Table of Contents for this book. Click here for the chapter download.

Dig Deeper on Eclipse for Lotus Notes Domino



  • Favorite iSeries cheat sheets

    Here you'll find a collection of valuable cheat sheets gathered from across the iSeries/ community. These cheat ...

  • HTML cheat sheet

    This is a really cool cheat sheet if you're looking to learn more about HTML. You'll find just about everything you every wanted ...

  • Carol Woodbury: Security

    Carol Woodbury