Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
[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

Title: Using the Class Loader Properties File

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.

Activation

The classloader performance enhancements are automatically enabled by default. If the user wishes to override this behaviour and disable them, then they may pass the -noPackagePrefixes command-line argument to the Eclipse executable.

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

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

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

Back to the top