| <html> | |
| <head> | |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | |
| <title>Eclipse 3.0 Runtime Adoption Guide</title> | |
| <link rel="stylesheet" href="/default_style.css"> | |
| </head> | |
| <body link="#0000ff" vlink="#800080"> | |
| <p align="right"><img src="file:///D|/equinox/ngibmcpy.gif" alt="Copyright IBM Corporation and others 2000, 2003." border="0" width="324" height="14"></p> | |
| <table border="0" cellspacing="0" cellpadding="2" width="100%"> | |
| <tbody> | |
| <tr> | |
| <td align="Left" valign="Top" colspan="2" bgcolor="#0080c0"><b><font face="Arial,Helvetica"><font color="#ffffff"> | |
| Eclipse Corner Article</font></font></b></td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| <div align="Left"> | |
| <h1><img src="file:///D|/equinox/prototype/plugins/images/Idea.jpg" height="86" width="120" align="Center"> | |
| </h1> | |
| </div> | |
| <h1 align="Center">Eclipse 3.0 Runtime Adoption Guide</h1> | |
| <blockquote> | |
| <p><b>Summary</b><br> | |
| <center> | |
| <b>This is a draft document. </b> | |
| </center> | |
| <br> | |
| This document details the steps required to <b>adopt</b> 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 <i>experimental</i> function. | |
| It is this function which is detailed here. </p> | |
| <p><b> By Jeff McAffer, IBM OTI Labs</b><br> | |
| <font size="-1">June 24, 2004</font></p> | |
| </blockquote> | |
| <hr width="100%"> | |
| <h2>Preamble</h2> | |
| <p>This content has been moved to the Migration Guide and the Javadoc deprecations | |
| as appropriate.</p> | |
| <h3>Plug-ins and bundles</h3> | |
| <p>This content has been moved to the Migration Guide and the Javadoc deprecations | |
| as appropriate.</p> | |
| <h3><a name="registries"></a>Registries and the plug-in model</h3> | |
| <p>This content has been moved to the Migration Guide and the Javadoc deprecations | |
| as appropriate.</p> | |
| <h3>Legacy code</h3> | |
| <p>This content has been moved to the Migration Guide and the Javadoc deprecations | |
| as appropriate.</p> | |
| <h3>Updating plugin/fragment files</h3> | |
| <p>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).</p> | |
| <p>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. </p> | |
| <p>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 <a href="http://www.osgi.org">OSGi specification</a> has | |
| enumerates all pre-defined manifest headers.</p> | |
| <table width="100%" border="1"> | |
| <tr> | |
| <td> | |
| <div align="center"><b>plugin.xml tag/attribute</b></div> | |
| </td> | |
| <td> | |
| <div align="center"><b>manifest.mf header</b></div> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td><plugin id=></td> | |
| <td>Bundle-SymbolicName</td> | |
| </tr> | |
| <tr> | |
| <td><plugin version=></td> | |
| <td>Bundle-Version</td> | |
| </tr> | |
| <tr> | |
| <td><plugin name=></td> | |
| <td>Bundle-Name</td> | |
| </tr> | |
| <tr> | |
| <td><plugin provider=></td> | |
| <td>Bundle-Vendor</td> | |
| </tr> | |
| <tr> | |
| <td><plugin class=></td> | |
| <td>Bundle-Activator</td> | |
| </tr> | |
| <tr> | |
| <td><fragment plugin-id=></td> | |
| <td>Fragment-Host</td> | |
| </tr> | |
| <tr> | |
| <td><fragment plugin-version=></td> | |
| <td>Fragment-Host: <id>; bundle-version=</td> | |
| </tr> | |
| <tr> | |
| <td><requires>, <import></td> | |
| <td>Require-Bundle</td> | |
| </tr> | |
| <tr> | |
| <td><runtime>, <library></td> | |
| <td>Bundle-ClassPath</td> | |
| </tr> | |
| </table> | |
| <p>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.</p> | |
| <ul> | |
| <li>all attributes on the <plugin> tag</li> | |
| <li><runtime> and its <library> subelement</li> | |
| <li><requires> and its <import> subelement</li> | |
| </ul> | |
| <p>This leaves the plugin.xml containing only the <plugin>, <extension> | |
| and <extension-point> tags</p> | |
| <p>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.</p> | |
| <p>The <tt>plugin.properties</tt> 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.</p> | |
| <p>The build.properties file remains unchanged.</p> | |
| <h3> </h3> | |
| </body> | |
| </html> |