| [eclipse-dev] Classloading enhancements |
In today's integration build some new class loading enhancements were
released.
What does it do?
------------------------
Similar to the classloader.properties file which was released for 2.0.2,
plug-ins are now able to specify the package prefixes for the code which
their plug-in contributes.
What do I have to do?
--------------------------------
Add the <packages prefixes=".."...> lines to your plugin.xml file for each
library you declare in your plug-in. For instance, the Xerces plug-in
declares 2 libraries and its plugin.xml file will look like:
<runtime>
<library name="xmlParserAPIs.jar">
<export name="*"/>
<packages prefixes="javax.xml,org.w3c.dom,org.xml.sax"/>
</library>
<library name="xercesImpl.jar">
<export name="*"/>
<packages prefixes="org.apache,org.w3c.dom"/>
</library>
</runtime>
How do I know what prefixes to use?
-----------------------------------------------------
Look at the attached classloader.properties file for hints for most of the
plug-ins which are included in the SDK.
It doesn't work, what do I do?
------------------------------------------
See the "Troubleshooting" section of the readme file to enable your
plug-in's code and enter a bugzilla bug report against Platform/Core.
Attached Files:
----------------------
classloader.properties for hints on package prefixes
(See attached file: classloader.properties)
readme file
(from
http://dev.eclipse.org/viewcvs/index.cgi/%7Echeckout%7E/platform-core-home/docs/package-prefixes/prefixes.html)
(See attached file: prefixes.html)
Attachment:
classloader.properties
Description: Binary data
Eclipse 2.1 includes many performance enhancements, including some in the area of classloading. In order to help out with this, mark-up has been added to the plug-in manifest file and this file explains its use.
-noPackagePrefixes command-line argument to the Eclipse
executable.
Declaration of the package prefixes in the plug-in manifest file is indicated
by a packages element for each library which is declared in the
file. The packages element has a prefixes attrbute
which lists the package prefixes for that library.
It is quite common for jar files to contain code which reside in multiple packages.
For instance, the org.eclipse.core.runtime plug-in contains code
in the following packages:
org.eclipse.core.runtime.
org.eclipse.core.internal.runtime,
org.eclipse.core.internal.plugins
org.eclipse.core.runtime.model
In this case, the plugin.xml specifies:
<runtime>
<library name="runtime.jar">
<export name="*"/>
<packages
prefixes="org.eclipse.core"/>
</library>
</runtime>
Notice that org.eclipse.core is a common prefix for all packages
in the plug-in. The alternative is to declare all 4 prefixes in the file as a
comma-separated list. In this case one must weigh the trade-off between the
number of checks required against multiple entries and a prefix which may
include false hits. Depending on the way that your code is structured, it might
be best to list as many as 5-10 package prefixes rather than going with a more
general prefix. For instance, if all your code across multiple plug-ins contains
the same prefix (e.g. com.mycompany) then you will not be taking
full advantage of all benefits if you list only the single prefix
"com.mycompany" in the file.
When a plug-in contains multiple library declarations, each one should account for the package prefixes from its jar.
If you choose not to include any packages elements in your plug-in
manifest your code will still work but you will not be taking advantage of the
class loading optimization. Note that your list of package prefixes must
be complete for all the packages in all the libraries in your plug-in. If this
list is not complete then your code will not work.
In Eclipse 2.0.2 and early Eclipse 2.1 Integration builds, a feature was added which allowed the user to specify a class loader properties file which contained the package prefixes to enable the classloader enhancements. Use of this file is specified here.
Eclipse 2.1 is fully backwards compatible with the class loader properties file and, in fact, it can be used in conjunction with the package prefix declarations in the plug-in manifest. This section describes the behaviour of the interaction between these two mechanisms.
Default behaviour: (no command-line arguments) The package prefixes
will be read from the plugin.xml file and applied to the class
loading strategy. The classloader.properties file is not accessed
or considered.
Using -classloaderProperties: The package prefixes are read from the
plugin.xml file and then the classloader.properties
file is read. If there is an entry in the classloader properties file for a
plug-in which had prefixes defined in the manifest file, the entry in the properties
file will over-ride and take precedence. (the results are NOT merged) If the
entry in the properties file does not contain a value (e.g. org.eclipse.core.runtime=)
then any prefixes declared in the manifest file will be removed and the class
loading strategy will default to not using the enhancements.
Using -noPackagePrefixes: Any package prefixes declared in the plug-in manifest file are ignored and the class loader properties file is also not taken into consideration. The class loading strategy defaults to not using the prefix enhancements.
Using both -classloaderProperties and -noPackagePrefixes: Any package declarations in the plug-in manifest file are ignored. The class loader properties file is read and any declarations defined within it are taken into consideration when in class loading.
If you get a java.lang.ClassNotFoundException then that is an
indication that there might be a problem with your entries in the manifest or
properties files. Try running Eclipse with the -noPackagePrefixes
command-line argument and do NOT use the -classloaderProperties
argument. This will disable all class loading enhancements with respect to the
package prefixes.
If your code runs fine after doing this, then the files could have the correct
syntax, but the package prefixes in the comma-separated list might be missing
some entries. To verify this is the problem, comment out the appropriate lines
in the file. Use a number sign (#) to comment out the line of the offending
plug-in in the properties file or use HTML comment characters (<!-- ... -->)
to comment out the packages declaration in the offending plugin.xml
file.
NoClassDefFoundError problem. This can be resolved
either by using the -noPackagePrefixes command-line argument to turn
off the classloader enhancements, or by adding the appropriate package prefix
entries to the plug-in and all its fragments.