[eclipse-dev] Classloading enhancements
In today's integration build some new class loading enhancements were
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:
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.
classloader.properties for hints on package prefixes
(See attached file: classloader.properties)
(See attached file: prefixes.html)
Title: Using the Class Loader Properties File
Description: Binary data
Using the Class Loader Enhancements
Last update: December 9, 2002
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.
The classloader performance enhancements are automatically enabled by default.
If the user wishes to override this behaviour and disable them, then they may
command-line argument to the Eclipse
Declaration of the package prefixes in the plug-in manifest file is indicated
packages element for each library which is declared in the
packages element has a
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:
In this case, the
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
Using -classloaderProperties: The package prefixes are read from the
plugin.xml file and then the
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.
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
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
command-line argument and do NOT use the
argument. This will disable all class loading enhancements with respect to the
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
If a plug-in manifest file declares the list of package prefixes, then all fragments
which contribute to it must also list their package prefixes. If they don't then
it will result in a
problem. This can be resolved
either by using the
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.