Using the Class Loader Enhancements

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.

• Activation
• Format
• Use with the Classloader Properties file
• Trouble-Shooting
• Known Issues

Activation

Format

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 attribute 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.

Use with the Class Loader Properties file

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.

Trouble-shooting

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.

Known Issues