Eclipse Corner Article

Eclipse 3.0 Runtime Adoption Guide

Summary

This is a draft document.
This document details the steps required to adopt the new mechanisms found in the Eclipse 3.0 runtime. In most cases, plug-in developers do not need to follow these steps as the 3.0 runtime supports the 2.1-style API. However, the new runtime offers significant new experimental function. It is this function which is detailed here.

By Jeff McAffer, IBM OTI Labs
June 24, 2004

Preamble

This content has been moved to the Migration Guide and the Javadoc deprecations as appropriate.

Plug-ins and bundles

This content has been moved to the Migration Guide and the Javadoc deprecations as appropriate.

Registries and the plug-in model

This content has been moved to the Migration Guide and the Javadoc deprecations as appropriate.

Legacy code

This content has been moved to the Migration Guide and the Javadoc deprecations as appropriate.

Updating plugin/fragment files

The new runtime is based on an implementation of the OSGi framework specification. The OSGi specification mandates the use of MANIFEST.MF files to define the execution of a plug-in. This conflicts with the Eclipse notion of plugin.xml as far as <runtime> and <requires> elements are concerned. The easiest way to update your plugin.xml or fragment.xml is to use the PDE Migration Tool (PDE Tools->Convert to OSGi bundle).

In certain situations the conversion tool is unable to correctly determine all of the packages provided by a plug-in. In particular, if a plug-in declares a library entry for say foo.jar but does not contain foo.jar, the converter is unable to generate the appropriate provides-package entries in the output manifest (this is done by analyzing the supplied jar which, in this case, is not present). Plug-in or fragments which are fully self-contained are converted correctly.

This tool extracts the execution-specific information from your plugin.xml and puts into the OSGi mandated META-INF/MANIFEST.MF file. All extension-related information is left in the plugin.xml. The manifest is a standard Java Jar file manifest. It contains specifications for the execution elements of our plug-in (e.g., classpath, prerequisites, ...). A table of frequent mapping is included below while the full OSGi specification has enumerates all pre-defined manifest headers.

plugin.xml tag/attribute	manifest.mf header
<plugin id=>	Bundle-SymbolicName
<plugin version=>	Bundle-Version
<plugin name=>	Bundle-Name
<plugin provider=>	Bundle-Vendor
<plugin class=>	Bundle-Activator
<fragment plugin-id=>	Fragment-Host
<fragment plugin-version=>	Fragment-Host: <id>; bundle-version=
<requires>, <import>	Require-Bundle
<runtime>, <library>	Bundle-ClassPath

The extension/extension-point related information continues to be detailed in the plugin.xml file however the following aspects of the plugin.xml DTD are being deprecated.

all attributes on the <plugin> tag
<runtime> and its <library> subelement
<requires> and its <import> subelement

This leaves the plugin.xml containing only the <plugin>, <extension> and <extension-point> tags

Note also that the form of this content is not specific to a plug-ins vs. fragments. As a result, the fragment.xml file is being deprecated and renamed to plugin.xml with the outlined DTD changes. In most cases fragments do not supply extensions or extension-points so the bulk of the change required is done while moving to the MANIFEST.MF file and the fragment.xml file can be deleted.

The plugin.properties file continues to supply translations for the extension/extension-point information in plugin.xml and also supplies translations for various keys in the MANIFEST.MF.

The build.properties file remains unchanged.