| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| <HTML><HEAD><TITLE>Using the Class Loader Properties File</TITLE> |
| <META http-equiv=Content-Type content="text/html; charset=windows-1252"> |
| <META content="MSHTML 6.00.2800.1126" name=GENERATOR></HEAD> |
| <BODY> |
| <H1>Using the Class Loader Enhancements</H1> |
| <EM>Last update: December 9, 2002</EM> |
| <P>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. |
| <P> |
| <UL> |
| <LI><A href="#activation">Activation</A> |
| <LI><A href="#format">Format</A> |
| <LI><A href="#classloader.properties">Use with the Classloader Properties file</A> |
| <LI><A href="#trouble">Trouble-Shooting</A> |
| <LI><A href="#known issues">Known Issues</A> |
| </UL> |
| <P> |
| <H2><A name=activation></A>Activation</H2> |
| 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 <CODE>-noPackagePrefixes</CODE> command-line argument to the Eclipse |
| executable. |
| <P> |
| <H2><A name=format></A>Format</H2> |
| <p>Declaration of the package prefixes in the plug-in manifest file is indicated |
| by a <code>packages</code> element for each library which is declared in the |
| file. The <code>packages</code> element has a <code>prefixes</code> attribute |
| which lists the package prefixes for that library.</p> |
| <p>It is quite common for jar files to contain code which reside in multiple packages. |
| For instance, the <CODE>org.eclipse.core.runtime</CODE> plug-in contains code |
| in the following packages:<BR> |
| <CODE> org.eclipse.core.runtime<BR> |
| org.eclipse.core.internal.runtime,<BR> |
| org.eclipse.core.internal.plugins<BR> |
| org.eclipse.core.runtime.model</CODE>. </p> |
| <P>In this case, the <code>plugin.xml</code> specifies: |
| <P> |
| <code> <runtime><br> |
| <library name="runtime.jar"><br> |
| <export name="*"/><br> |
| <packages |
| prefixes="org.eclipse.core"/><br> |
| </library><br> |
| </runtime> |
| </code> |
| |
| <P>Notice that <CODE>org.eclipse.core</CODE> 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. <CODE>com.mycompany</CODE>) then you will not be taking |
| full advantage of all benefits if you list only the single prefix |
| "com.mycompany" in the file. |
| <P>When a plug-in contains multiple library declarations, each one should account |
| for the package prefixes from its jar. |
| <P>If you choose not to include any <code>packages</code> 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 <b>must</b> |
| 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. |
| <H2><A name=classloader.properties>Use with the Class Loader Properties file</A></H2> |
| |
| <p>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 <a href="http://dev.eclipse.org/viewcvs/index.cgi/%7Echeckout%7E/platform-core-home/docs/classloader-properties/classloader_properties.html">here</a>. |
| </p> |
| <p>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.</p> |
| <p><em>Default behaviour: </em>(no command-line arguments) The package prefixes |
| will be read from the <code>plugin.xml</code> file and applied to the class |
| loading strategy. The <code>classloader.properties</code> file is not accessed |
| or considered. |
| <p><em>Using -classloaderProperties: </em>The package prefixes are read from the |
| <code>plugin.xml</code> file and then the <code>classloader.properties</code> |
| 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. <code>org.eclipse.core.runtime=</code>) |
| then any prefixes declared in the manifest file will be removed and the class |
| loading strategy will default to not using the enhancements. |
| <p><em>Using -noPackagePrefixes: </em>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. |
| <p><em>Using both -classloaderProperties and -noPackagePrefixes: </em>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. |
| <P><h2><A name=trouble>Trouble-shooting</a></h2> |
| <p>If you get a <CODE>java.lang.ClassNotFoundException</CODE> 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 <code>-noPackagePrefixes</code> |
| command-line argument and do NOT use the <code>-classloaderProperties</code> |
| argument. This will disable all class loading enhancements with respect to the |
| package prefixes. </p> |
| <p>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 <code>plugin.xml</code> |
| file. </p> |
| |
| <H2><A name="known issues">Known Issues</A></H2> |
| 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 <code>NoClassDefFoundError</code> problem. This can be resolved |
| either by using the <code>-noPackagePrefixes</code> 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. |
| </BODY></HTML> |
