Jetty/Reference/Jetty Classloading

Jetty Classloading

Class loading in a web container is slightly more complex than a normal java application.

The normal configuration is for each web context (web application or war file) is given it's own classloader, which has the system classloader as it's parent. Such a classloader hierarchy is normal in Java, however the servlet specification complicates the hierarchy by requiring that:

• Classes contained within WEB-INF/lib or WEB-INF/classes have priority over classes on the parent class loader. This is the opposite of the normal behaviour of a java 2 class loader.

• System classes such as java.lang.String are excluded from the webapp priority and may not be replaced by classes in WEB-INF/lib or WEB-INF/classes. Unfortunately the specification does not clearly state what classes are "System" classes and it is unclear if all javax classes should be treated as System classes.

• Server implementation classes like org.eclipse.jetty.server.Server should be hidden from the web application and should not be available in any class loader. Unfortunately the specification does not state what is a Server class and it is unclear if common libraries like the xerces parser should be treated as Implementation classes.

Jetty provides configuration options to control the three webapp classloading issues identified above.

Configuring Webapp Classloading

Webapp classloading can be configured by several methods on the org.eclipse.jetty.webapp.WebAppContext. These methods can be called directly if working with the Jetty API, or injected from a context xml file if using the Context Deployer. They CANNOT be set from a jetty-web.xml file, as that is executed after the classloader configuration is set.

Controlling Webapp classloader priority

The method org.eclipse.jetty.webapp.WebAppContext.setParentLoaderPriority(boolean) allows control over the priority given to webapp classes over system classes. If this is set to false (the default), then standard webapp classloading priority is used, however if in this mode some classes that are dependencies of other classes loaded from the parent classloader (due to settings of system classes below), then ambiguities may arise as both the webapp and system classloader version may end up being loaded.

If set to true, then normal JavaSE classloading priority is used and priority is given to the parent/system classloader. This avoids the issues of multiple versions of a class within a webapp, but the version provided by the parent/system loader must be the right version for all webapps configured in this way.

Setting System Classes

The methods org.eclipse.jetty.webapp.WebAppContext.setSystemClasses(String Array) or org.eclipse.jetty.webapp.WebAppContext.addSystemClass(String) may be called to allow fine control over what classes are considered System classes. A System class can be seen by a web application, but cannot be replaced by any WEB-INF class. The default system classes are:

System Classes

java.	Java SE classes (per servlet spec v2.5 / SRV.9.7.2)
javax.	Java SE classes (per servlet spec v2.5 / SRV.9.7.2)
org.xml.	needed by javax.xml
org.w3c.	needed by javax.xml
org.apache.commons.logging.	special case
org.eclipse.jetty.continuation.	webapp can see and not change continuation classes
org.eclipse.jetty.jndi.	webapp can see and not change naming classes
org.eclipse.jetty.plus.jaas.	webapp can see and not change jaas classes
org.eclipse.jetty.websocket.	WebSocket is a jetty extension
org.eclipse.jetty.servlet.DefaultServlet	webapp can see and not change default servlet

Absolute classname can be passed, names ending with . are treated as packages names and names starting with - are treated as negative matches and must be listed before any enclosing packages.

Setting Server Classes

The methods org.eclipse.jetty.webapp.WebAppContext.setServerClasses(String Array) or org.eclipse.jetty.webapp.WebAppContext.addServerClass(String) may be called to allow fine control over what classes are considered Server classes. A Server class can not be seen by a web application, but can be replaced by a WEB-INF class. The default server classes are:

Server Classes

-org.eclipse.jetty.continuation.	don't hide continuation classes
-org.eclipse.jetty.jndi.	don't hide naming classes
-org.eclipse.jetty.plus.jaas.	don't hide jaas classes
-org.eclipse.jetty.websocket.	don't hide websocket extension
-org.eclipse.jetty.servlet.DefaultServlet	don't hide default servlet
org.eclipse.jetty.	hide all other jetty classes

Adding extra classpaths to Jetty

Using start jar

At startup if using start.jar, the jetty runtime will automatically load option jars from the top level $jetty.home/lib directory. The default settings includes

• Adding all jars under $jetty.home/lib/ext to the system classpath. Additional jars may be placed here.
• Adding the directory $jetty.home/resources to the classpath (may contain classes or other resources)
• Adding a single path defined by the command line parameter "path"

Using the extraClasspath() method

Additional classpath can be added to a context classloader by calling org.eclipse.jetty.webapp.WebAppContext.setExtraClasspath(String) with a coma separated list of paths. This can be done directly to the API of via a context XML file like:

 <Configure class="org.eclipse.jetty.webapp.WebAppContext">
...
<Set name="extraClasspath">../my/classes:../my/jars/special.jar:../my/jars/other.jar</Set>
...

Using a custom WebAppClassLoader

If none of the other alternatives already described meet your needs, you can always provide a custom classloader for your webapp. It is recommended, but not required, that your custom loader subclasses WebAppClassLoader. You configure the classloader for the webapp like so:

 MyCleverClassLoader myCleverClassLoader = new MyCleverClassLoader();
...
WebAppContext webapp = new WebAppContext();
...
webapp.setClassLoader(myCleverClassLoader);

This can also be done in a context xml