platform-core-home/docs/classloader-properties/classloader_properties.html

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.2 - (download) (as text) (annotate)
Thu Oct 24 22:20:45 2002 UTC (7 years, 1 month ago) by dj
Branch: MAIN
Changes since 1.1: +1 -1 lines 
*** empty log message ***

<html>
<head>
<title>Using the classloader.properties file</title>
</head>
<body>
<h1>Using the classloader.properties file</h1>
Eclipse 2.0.2 includes many performance enhancements, including some in the area 
of classloading. In order to help out with this a classloader properties file 
was created and this file explains its use. 
<p>

<h2>Activation</h2>
To enable the classloader performance enhancements, the user must pass the <code>-classloaderProperties</code>
command-line argument to the Eclipse executable. If the argument is used by itself
the default location (see below) is used for the classloader properties file. 
Alternatively the argument can be followed by a path or URL to the appropriate 
file to use. 
<p>

<h2>Location</h2>
The default location of the classloader properties file is as a sibling of the <code>boot.jar</code>
 in the <code>org.eclipse.core.boot</code> plug-in.
For instance:<br>
&nbsp;&nbsp;&nbsp;&nbsp;<code>/eclipse/plugins/org.eclipse.core.boot/classloader.properties</code>
<p>

If the user specifies the location of the file, it can be either a path or a URL to a file. For instance:<br>
<code>
&nbsp;&nbsp;&nbsp;&nbsp;-classloaderProperties c:/temp/myfile.properties<br>
&nbsp;&nbsp;&nbsp;&nbsp;-classloaderProperties file:/c:/temp/myfile.properties
</code>
<p>

<h2>Format</h2>
The format of the classloader properties file is a <code>java.util.Properties</code> file. The key in the file is the name of the
plug-in and the value is a comma-separated list of the package prefixes for the packages in the plug-in's jar.
<p>

It is quite common for jar files to contain code which reside in multiple packages. For instance, the <code>runtime.jar</code> file
in the <code>org.eclipse.core.runtime</code> plug-in contains code in the following packages:<br>
<code>
&nbsp;&nbsp;&nbsp;&nbsp;org.eclipse.core.runtime<br>
&nbsp;&nbsp;&nbsp;&nbsp;org.eclipse.core.internal.runtime,<br>
&nbsp;&nbsp;&nbsp;&nbsp;org.eclipse.core.internal.plugins<br>
&nbsp;&nbsp;&nbsp;&nbsp;org.eclipse.core.runtime.model</code>.<p>
In this case, in the classloader properties file we put specify the following line:
<p>
&nbsp;&nbsp;&nbsp;&nbsp;<code>org.eclipse.core.runtime=org.eclipse.core</code>
<p> Notice that <code>org.eclipse.core</code> is a common prefix for all packages 
  in the <code>runtime.jar</code>. 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 
  &quot;com.mycompany&quot; in the file. 
<p>

It is also common for plug-ins to contain multiple jar files with code. In this case all package prefixes from all jars
should appear in the classloader properties file.
<p>

Note that not having an entry for your plug-in as a key in the file doesn't mean that your code will not work, it just 
means that you will not be able to take advantage of classloading optimization. And note that missing a package
prefix as a value entry in the file does mean that your code will not work.
<p>

See the file which is shipped with Eclipse for an example.
(<code>/eclipse/plugins/org.eclipse.core.boot/classloader.properties</code>)
<p>

<h2>Future</h2>
As described above, currently one must add all package prefixes to the same properties 
file. Future work in this area includes the ability to add mark-up to your <code>plugin.xml</code> 
file to take advantage of this classloading performance behaviour to make it easier 
for people who are extending the Eclipse platform. 
<p>

<h2>Trouble-shooting</h2>
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 properties file. The file could have the correct syntax, but the package prefixes in the
comma-separated list might be missing some entries. The workaround for this is to comment out the line of the offending plug-in.
<p>

</body>
</html>