3.2. 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 (see Section 3.4.3, Static plug-in resources, on page 115).

META-INF/MANIFEST.MF A file describing the runtime aspects of the plug-in such as identifier, version, and plug-in dependencies (see Section 2.3.1, The Plug-in manifests, on page 71 and see Section 3.3.2, Plug-in runtime, on page 110).

plugin.xml A file in XML format describing extensions and extension points (see Section 3.3.4, Extensions and extension points, on page 112).

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 (see Section 2.4.1, Building manually, on page 81). 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.

3.2.1. 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 using the steps outlined in Section 2.8.5, Uninstalling the Favorites plug-in, on page 98. 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=
   "${build.temp}/jars/QualityEclipse/Favorites/
      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:

QualityEclipse/Favorites/eclipse/plugins/
   com.qualityeclipse.favorites_1.0.0.jar

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:

C:\QualityEclipse\Favorites\eclipse\plugins\
   com.qualityeclipse.favorites_1.0.0.jar

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 com.qualityeclipse.favorites.link that contains this single line:

path=C:/QualityEclipse/Favorites

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.

3.2.2. 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 described in Section 2.8, Writing Plug-in Tests, on page 92 will still run successfully.