platform-core-home/docs/package-prefixes/prefixes.html
Parent Directory
| 
Revision Log
Revision 1.2 - (view) (download) (as text)
| 1 : | dj | 1.1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| 2 : | <HTML><HEAD><TITLE>Using the Class Loader Properties File</TITLE> | ||
| 3 : | <META http-equiv=Content-Type content="text/html; charset=windows-1252"> | ||
| 4 : | <META content="MSHTML 6.00.2800.1126" name=GENERATOR></HEAD> | ||
| 5 : | <BODY> | ||
| 6 : | <H1>Using the Class Loader Enhancements</H1> | ||
| 7 : | <EM>Last update: December 9, 2002</EM> | ||
| 8 : | <P>Eclipse 2.1 includes many performance enhancements, including some in the area | ||
| 9 : | of classloading. In order to help out with this, mark-up has been added to the | ||
| 10 : | plug-in manifest file and this file explains its use. | ||
| 11 : | <P> | ||
| 12 : | <UL> | ||
| 13 : | <LI><A href="#activation">Activation</A> | ||
| 14 : | <LI><A href="#format">Format</A> | ||
| 15 : | <LI><A href="#classloader.properties">Use with the Classloader Properties file</A> | ||
| 16 : | <LI><A href="#trouble">Trouble-Shooting</A> | ||
| 17 : | <LI><A href="#known issues">Known Issues</A> | ||
| 18 : | </UL> | ||
| 19 : | <P> | ||
| 20 : | <H2><A name=activation></A>Activation</H2> | ||
| 21 : | The classloader performance enhancements are automatically enabled by default. | ||
| 22 : | If the user wishes to override this behaviour and disable them, then they may | ||
| 23 : | pass the <CODE>-noPackagePrefixes</CODE> command-line argument to the Eclipse | ||
| 24 : | executable. | ||
| 25 : | <P> | ||
| 26 : | <H2><A name=format></A>Format</H2> | ||
| 27 : | <p>Declaration of the package prefixes in the plug-in manifest file is indicated | ||
| 28 : | by a <code>packages</code> element for each library which is declared in the | ||
| 29 : | johna | 1.2 | file. The <code>packages</code> element has a <code>prefixes</code> attribute |
| 30 : | dj | 1.1 | which lists the package prefixes for that library.</p> |
| 31 : | <p>It is quite common for jar files to contain code which reside in multiple packages. | ||
| 32 : | For instance, the <CODE>org.eclipse.core.runtime</CODE> plug-in contains code | ||
| 33 : | in the following packages:<BR> | ||
| 34 : | <CODE> org.eclipse.core.runtime<BR> | ||
| 35 : | org.eclipse.core.internal.runtime,<BR> | ||
| 36 : | org.eclipse.core.internal.plugins<BR> | ||
| 37 : | org.eclipse.core.runtime.model</CODE>. </p> | ||
| 38 : | <P>In this case, the <code>plugin.xml</code> specifies: | ||
| 39 : | <P> | ||
| 40 : | <code> <runtime><br> | ||
| 41 : | <library name="runtime.jar"><br> | ||
| 42 : | <export name="*"/><br> | ||
| 43 : | <packages | ||
| 44 : | prefixes="org.eclipse.core"/><br> | ||
| 45 : | </library><br> | ||
| 46 : | </runtime> | ||
| 47 : | </code> | ||
| 48 : | |||
| 49 : | <P>Notice that <CODE>org.eclipse.core</CODE> is a common prefix for all packages | ||
| 50 : | in the plug-in. The alternative is to declare all 4 prefixes in the file as a | ||
| 51 : | comma-separated list. In this case one must weigh the trade-off between the | ||
| 52 : | number of checks required against multiple entries and a prefix which may | ||
| 53 : | include false hits. Depending on the way that your code is structured, it might | ||
| 54 : | be best to list as many as 5-10 package prefixes rather than going with a more | ||
| 55 : | general prefix. For instance, if all your code across multiple plug-ins contains | ||
| 56 : | the same prefix (e.g. <CODE>com.mycompany</CODE>) then you will not be taking | ||
| 57 : | full advantage of all benefits if you list only the single prefix | ||
| 58 : | "com.mycompany" in the file. | ||
| 59 : | <P>When a plug-in contains multiple library declarations, each one should account | ||
| 60 : | for the package prefixes from its jar. | ||
| 61 : | <P>If you choose not to include any <code>packages</code> elements in your plug-in | ||
| 62 : | manifest your code will still work but you will not be taking advantage of the | ||
| 63 : | class loading optimization. Note that your list of package prefixes <b>must</b> | ||
| 64 : | be complete for all the packages in all the libraries in your plug-in. If this | ||
| 65 : | list is not complete then your code will not work. | ||
| 66 : | <H2><A name=classloader.properties>Use with the Class Loader Properties file</A></H2> | ||
| 67 : | |||
| 68 : | <p>In Eclipse 2.0.2 and early Eclipse 2.1 Integration builds, a feature was added | ||
| 69 : | which allowed the user to specify a class loader properties file which contained | ||
| 70 : | the package prefixes to enable the classloader enhancements. Use of this file | ||
| 71 : | is specified <a href="http://dev.eclipse.org/viewcvs/index.cgi/%7Echeckout%7E/platform-core-home/docs/classloader-properties/classloader_properties.html">here</a>. | ||
| 72 : | </p> | ||
| 73 : | <p>Eclipse 2.1 is fully backwards compatible with the class loader properties | ||
| 74 : | file and, in fact, it can be used in conjunction with the package prefix declarations | ||
| 75 : | in the plug-in manifest. This section describes the behaviour of the interaction | ||
| 76 : | between these two mechanisms.</p> | ||
| 77 : | <p><em>Default behaviour: </em>(no command-line arguments) The package prefixes | ||
| 78 : | will be read from the <code>plugin.xml</code> file and applied to the class | ||
| 79 : | loading strategy. The <code>classloader.properties</code> file is not accessed | ||
| 80 : | or considered. | ||
| 81 : | <p><em>Using -classloaderProperties: </em>The package prefixes are read from the | ||
| 82 : | <code>plugin.xml</code> file and then the <code>classloader.properties</code> | ||
| 83 : | file is read. If there is an entry in the classloader properties file for a | ||
| 84 : | plug-in which had prefixes defined in the manifest file, the entry in the properties | ||
| 85 : | file will over-ride and take precedence. (the results are NOT merged) If the | ||
| 86 : | entry in the properties file does not contain a value (e.g. <code>org.eclipse.core.runtime=</code>) | ||
| 87 : | then any prefixes declared in the manifest file will be removed and the class | ||
| 88 : | loading strategy will default to not using the enhancements. | ||
| 89 : | <p><em>Using -noPackagePrefixes: </em>Any package prefixes declared in the plug-in | ||
| 90 : | manifest file are ignored and the class loader properties file is also not taken | ||
| 91 : | into consideration. The class loading strategy defaults to not using the prefix | ||
| 92 : | enhancements. | ||
| 93 : | <p><em>Using both -classloaderProperties and -noPackagePrefixes: </em>Any package declarations | ||
| 94 : | in the plug-in manifest file are ignored. The class loader properties file is | ||
| 95 : | read and any declarations defined within it are taken into consideration when | ||
| 96 : | in class loading. | ||
| 97 : | <P><h2><A name=trouble>Trouble-shooting</a></h2> | ||
| 98 : | <p>If you get a <CODE>java.lang.ClassNotFoundException</CODE> then that is an | ||
| 99 : | indication that there might be a problem with your entries in the manifest or | ||
| 100 : | properties files. Try running Eclipse with the <code>-noPackagePrefixes</code> | ||
| 101 : | command-line argument and do NOT use the <code>-classloaderProperties</code> | ||
| 102 : | argument. This will disable all class loading enhancements with respect to the | ||
| 103 : | package prefixes. </p> | ||
| 104 : | <p>If your code runs fine after doing this, then the files could have the correct | ||
| 105 : | syntax, but the package prefixes in the comma-separated list might be missing | ||
| 106 : | some entries. To verify this is the problem, comment out the appropriate lines | ||
| 107 : | in the file. Use a number sign (#) to comment out the line of the offending | ||
| 108 : | plug-in in the properties file or use HTML comment characters (<!-- ... -->) | ||
| 109 : | to comment out the packages declaration in the offending <code>plugin.xml</code> | ||
| 110 : | file. </p> | ||
| 111 : | |||
| 112 : | <H2><A name="known issues">Known Issues</A></H2> | ||
| 113 : | If a plug-in manifest file declares the list of package prefixes, then all fragments | ||
| 114 : | which contribute to it must also list their package prefixes. If they don't then | ||
| 115 : | it will result in a <code>NoClassDefFoundError</code> problem. This can be resolved | ||
| 116 : | either by using the <code>-noPackagePrefixes</code> command-line argument to turn | ||
| 117 : | off the classloader enhancements, or by adding the appropriate package prefix | ||
| 118 : | entries to the plug-in and all its fragments. | ||
| 119 : | </BODY></HTML> |
| help@eclipse.org | ViewVC Help |
| Powered by ViewVC 1.0.3 |