<html><head>
      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   <title>Jetty Classloading</title><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="jetty, servlet, servlet-api, cometd, http, websocket, eclipse, maven, java, server, software"><link rel="home" href="index.html" title="Jetty"><link rel="up" href="architecture.html" title="Chapter&nbsp;30.&nbsp;Architecture"><link rel="prev" href="architecture.html" title="Chapter&nbsp;30.&nbsp;Architecture"><link rel="next" href="jetty-1xx-responses.html" title="Managing 1xx Responses"><link xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" rel="shortcut icon" href="images/favicon.ico"><link rel="stylesheet" href="css/highlighter/foundation.css"><script src="js/highlight.pack.js"></script><script>
      hljs.initHighlightingOnLoad();
    </script><link type="text/css" rel="stylesheet" href="css/font-awesome/font-awesome.min.css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><tr><td style="width: 25%"><a href="http://www.eclipse.org/jetty"><img src="images/jetty-header-logo.png" alt="Jetty Logo"></a><br><span style="font-size: small">
            Version: 9.4.28-SNAPSHOT</span></td><td style="width: 50%"></td></tr></table><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Jetty Classloading</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="architecture.html"><i class="fa fa-chevron-left" aria-hidden="true"></i> Previous</a>&nbsp;</td><th width="60%" align="center">Chapter&nbsp;30.&nbsp;Architecture<br><a accesskey="p" href="index.html"><i class="fa fa-home" aria-hidden="true"></i> Home</a></th><td width="20%" align="right">&nbsp;<a accesskey="n" href="jetty-1xx-responses.html">Next <i class="fa fa-chevron-right" aria-hidden="true"></i></a></td></tr></table><hr></div><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="jetty-callout"><h5 class="callout"><a href="http://www.webtide.com/">Contact the core Jetty developers at
          <span class="website">www.webtide.com</span></a></h5><p>
 private support for your internal/customer projects ... custom extensions and distributions ... versioned snapshots for indefinite support ...
 scalability guidance for your apps and Ajax/Comet projects ... development services for sponsored feature development
      </p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jetty-classloading"></a>Jetty Classloading</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="jetty-classloading.html#configuring-webapp-classloading">Configuring Webapp Classloading</a></span></dt><dt><span class="section"><a href="jetty-classloading.html#adding-extra-classpaths">Adding Extra Classpaths to Jetty</a></span></dt><dt><span class="section"><a href="jetty-classloading.html#using-custom-webappclassloader">Using a Custom WebAppClassLoader</a></span></dt><dt><span class="section"><a href="jetty-classloading.html#starting-jetty-custom-classloader">Starting Jetty with a Custom ClassLoader</a></span></dt></dl></div><p>Class loading in a web container is slightly more complex than a normal Java application.
The normal configuration is that each web context (web application or WAR file) has its own classloader, which has the system classloader as its parent.
Such a classloader hierarchy is normal in Java, however the servlet specification complicates the hierarchy because it requires the following:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">Classes contained within <code class="literal">WEB-INF/lib</code> or <code class="literal">WEB-INF/classes</code> have priority over classes on the parent classloader.
This is the opposite of the normal behavior of a Java 2 classloader.</li><li class="listitem">System classes such as <code class="literal">java.lang.String</code> are excluded from the webapp priority, and you may not replace them with classes in <code class="literal">WEB-INF/lib</code> or <code class="literal">WEB-INF/</code> classes.
Unfortunately the specification does not clearly state what classes are <span class="emphasis"><em>System</em></span> classes, and it is unclear if all <code class="literal">javax</code> classes should be treated as System classes.</li><li class="listitem">Server implementation classes like <a class="link" href="http://www.eclipse.org/jetty/javadoc/9.4.28-SNAPSHOT/org/eclipse/jetty/server/Server.html" target="_top">Server</a> should be hidden from the web application and should not be available in any classloader.
Unfortunately the specification does not state what classes are <span class="emphasis"><em>Server</em></span> classes, and it is unclear if common libraries like the Xerces parser should be treated as Implementation classes.</li></ul></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="configuring-webapp-classloading"></a>Configuring Webapp Classloading</h3></div></div></div><p>Jetty provides configuration options to control the three webapp class loading issues identified above.</p><p>You can configure webapp classloading by several methods on the <a class="link" href="http://www.eclipse.org/jetty/javadoc/9.4.28-SNAPSHOT/org/eclipse/jetty/webapp/WebAppContext.html" target="_top">WebAppContext</a>.
You can call these methods directly if you are working with the Jetty API, or you can inject methods from a context XML file if you are using the Context Provider (<a class="xref" href="">???</a>).
You CANNOT set these methods from a <code class="literal">jetty-web.xml</code> file, as it executes after the classloader configuration is set.
As a note, <code class="literal">jetty-web.xml</code> uses the webapp classpath and not the classpath of the server.</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="controlling-webapp-classloader-priority"></a>Controlling Webapp Classloader Priority</h4></div></div></div><p>The method <a class="link" href="http://www.eclipse.org/jetty/javadoc/9.4.28-SNAPSHOT/org/eclipse/jetty/webapp/WebAppContext.html#isParentLoaderPriority()" target="_top">org.eclipse.jett .webapp.WebAppContext.setParentLoaderPriority(boolean)</a> allows control over the priority given to webapp classes over system classes.
If you set it to false (the default), Jetty uses standard webapp classloading priority.
However, if in this mode some classes that are dependencies of other classes are loaded from the parent classloader (due to settings of system classes below), ambiguities might arise as both the webapp and system classloader versions can end up being loaded.</p><p>If set to true, Jetty uses normal JavaSE classloading priority, and gives priority to the parent/system classloader.
This avoids the issues of multiple versions of a class within a webapp, but the version the parent/system loader provides must be the right version for all webapps you configure in this way.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="configuring-webapp-caching"></a>Configuring Webapp Classloader Caching</h4></div></div></div><p>Introduced in Jetty 9.3.6, the <a class="link" href="http://www.eclipse.org/jetty/javadoc/9.4.28-SNAPSHOT/org/eclipse/jetty/webapp/CachingWebAppClassLoader.html" target="_top">CachingWebAppClassLoader</a> can be used to cache <code class="literal">getResource(String)</code> results.
For webapps that search for classes and resources regularly, this can increase speed and performance.
This is an optional feature and it should be noted that it can conflict with several other libraries such as JSP, JSTL, JSF and CDI.
As such, this feature must be manually enabled for each webapp you want to use it in.</p><p>Below is an example of implementing this feature using Jetty IoC XML format:</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code>&lt;Configure id="mywebapp" class="org.eclipse.jetty.webapp.WebAppContext"&gt;

...

  &lt;Set name="classLoader"&gt;
    &lt;New class="org.eclipse.jetty.webapp.CachingWebAppClassLoader"&gt;
      &lt;Arg&gt;&lt;Ref refid="mywebapp"/&gt;&lt;/Arg&gt;
    &lt;/New&gt;
  &lt;/Set&gt;

...
&lt;/Configure&gt;</code></pre></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="classloading-setting-system-classes"></a>Setting System Classes</h4></div></div></div><p>You can call the methods
<a class="link" href="http://www.eclipse.org/jetty/javadoc/9.4.28-SNAPSHOT/org/eclipse/jetty/webapp/WebAppContext.html#setSystemClasses%28java.lang.String%5B%5D%29" target="_top">WebAppContext.setSystemClasses(String[])</a>
or
<a class="link" href="http://www.eclipse.org/jetty/javadoc/9.4.28-SNAPSHOT/org/eclipse/jetty/webapp/WebAppContext.html#getSystemClasspathPattern()" target="_top">WebAppContext.getSystemClasspathPattern().add(String)</a>
to allow fine control over which classes are considered system classes.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">A web application can see a System class.</li><li class="listitem">A WEB-INF class cannot replace a System class.</li></ul></div><p>The default system classes are:</p><div class="table"><a name="d0e29448"></a><p class="title"><b>Table&nbsp;30.1.&nbsp;Default System Classes</b></p><div class="table-contents"><table class="table" summary="Default System Classes" border="1" width="100%"><colgroup><col class="col_1"><col class="col_2"></colgroup><thead><tr><th align="left" valign="top">System Classes</th><th align="left" valign="top">Note</th></tr></thead><tbody><tr><td align="left" valign="top"><p>java.</p></td><td align="left" valign="top"><p>Java SE classes (per servlet spec v2.5 / SRV.9.7.2).</p></td></tr><tr><td align="left" valign="top"><p>javax.</p></td><td align="left" valign="top"><p>Java SE classes (per servlet spec v2.5 / SRV.9.7.2).</p></td></tr><tr><td align="left" valign="top"><p>org.xml.</p></td><td align="left" valign="top"><p>Needed by javax.xml.</p></td></tr><tr><td align="left" valign="top"><p>org.w3c.</p></td><td align="left" valign="top"><p>Needed by javax.xml.</p></td></tr><tr><td align="left" valign="top"><p>org.eclipse.jetty.continuation.</p></td><td align="left" valign="top"><p>Webapp can see and not change continuation classes.</p></td></tr><tr><td align="left" valign="top"><p>org.eclipse.jetty.jndi.</p></td><td align="left" valign="top"><p>Webapp can see and not change naming classes.</p></td></tr><tr><td align="left" valign="top"><p>org.eclipse.jetty.jaas.</p></td><td align="left" valign="top"><p>Webapp can see and not change JAAS classes.</p></td></tr><tr><td align="left" valign="top"><p>org.eclipse.jetty.websocket.</p></td><td align="left" valign="top"><p>WebSocket is a Jetty extension.</p></td></tr><tr><td align="left" valign="top"><p>org.eclipse.jetty.servlet.DefaultServlet</p></td><td align="left" valign="top"><p>Webapp can see and not change default servlet.</p></td></tr></tbody></table></div></div><br class="table-break"><p>Absolute classname can be passed, names ending with <code class="literal">.</code> are treated as packages names, and names starting with <code class="literal">-</code> are treated as negative matches and must be listed before any enclosing packages.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="setting-server-classes"></a>Setting Server Classes</h4></div></div></div><p>You can call the methods <a class="link" href="http://www.eclipse.org/jetty/javadoc/9.4.28-SNAPSHOT/org/eclipse/jetty/webapp/WebAppContext.html#setServerClasses%28java.lang.String%5B%5D%29" target="_top">org.eclipse.jetty.webapp.WebAppContext.setServerClasses(String Array)</a> or
<a class="link" href="http://www.eclipse.org/jetty/javadoc/9.4.28-SNAPSHOT/org/eclipse/jetty/webapp/WebAppContext.html#addServerClass(java.lang.String)" target="_top">org.eclipse.jetty.webapp.WebAppContext.addServerClass(String)</a> to allow fine control over which classes are considered Server classes.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">A web application cannot see a Server class.</li><li class="listitem">A WEB-INF class can replace a Server class.</li></ul></div><p>The default server classes are:</p><div class="table"><a name="d0e29555"></a><p class="title"><b>Table&nbsp;30.2.&nbsp;Default Server Classes</b></p><div class="table-contents"><table class="table" summary="Default Server Classes" border="1" width="100%"><colgroup><col class="col_1"><col class="col_2"></colgroup><thead><tr><th align="left" valign="top">Server Classes</th><th align="left" valign="top">-org.eclipse.jetty.continuation.</th></tr></thead><tbody><tr><td align="left" valign="top"><p>Don&#8217;t hide continuation classes.</p></td><td align="left" valign="top"><p>-org.eclipse.jetty.jndi.</p></td></tr><tr><td align="left" valign="top"><p>Don&#8217;t hide naming classes.</p></td><td align="left" valign="top"><p>-org.eclipse.jetty.jaas.</p></td></tr><tr><td align="left" valign="top"><p>Don&#8217;t hide jaas classes.</p></td><td align="left" valign="top"><p>-org.eclipse.jetty.servlets.</p></td></tr><tr><td align="left" valign="top"><p>Don&#8217;t hide utility servlet classes if provided.</p></td><td align="left" valign="top"><p>-org.eclipse.jetty.servlet.DefaultServlet</p></td></tr><tr><td align="left" valign="top"><p>Don&#8217;t hide default servlet.</p></td><td align="left" valign="top"><p>-org.eclipse.jetty.servlet.listener.</p></td></tr><tr><td align="left" valign="top"><p>Don&#8217;t hide utility listeners</p></td><td align="left" valign="top"><p>-org.eclipse.jetty.websocket.</p></td></tr><tr><td align="left" valign="top"><p>Don&#8217;t hide websocket extension.</p></td><td align="left" valign="top"><p>org.eclipse.jetty.</p></td></tr></tbody></table></div></div><br class="table-break"></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="adding-extra-classpaths"></a>Adding Extra Classpaths to Jetty</h3></div></div></div><p>You can add extra classpaths to Jetty in several ways.</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="classpaths-using-start-jar"></a>Using <code class="literal">start.jar</code></h4></div></div></div><p>If you are using <code class="literal">start.jar</code> via the Jetty distribution, at startup the Jetty runtime automatically loads option Jars from the top level <code class="literal">$jetty.home/lib</code> directory. The default settings include:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">Adding Jars under <code class="literal">$jetty.home/lib/ext</code> to the system classpath.
You can place additional Jars here.</li><li class="listitem">Adding the directory <code class="literal">$jetty.home/resources</code> to the classpath (may contain classes or other resources).</li><li class="listitem">Adding a single path defined by the command line parameter <span class="emphasis"><em>path</em></span>.</li></ul></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="using-extra-classpath-method"></a>Using the extraClasspath() method</h4></div></div></div><p>You can add an additional classpath to a context classloader by calling <a class="link" href="http://www.eclipse.org/jetty/javadoc/9.4.28-SNAPSHOT/org/eclipse/jetty/webapp/WebAppContext.html#setExtraClasspath(java.lang.String)" target="_top">org.eclipse.jetty.webapp.WebAppContext.setExtraClasspath(String)</a> with a comma-separated list of paths.
You can do so directly to the API via a context XML file such as the following:</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code>&lt;Configure class="org.eclipse.jetty.webapp.WebAppContext"&gt;
 ...
 &lt;Set name="extraClasspath"&gt;../my/classes,../my/jars/special.jar,../my/jars/other.jar&lt;/Set&gt;
 ...</code></pre></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="using-custom-webappclassloader"></a>Using a Custom WebAppClassLoader</h3></div></div></div><p>If none of the alternatives already described meet your needs, you can always provide a custom classloader for your webapp.
We recommend, but do not require, that your custom loader subclasses <a class="link" href="http://www.eclipse.org/jetty/javadoc/9.4.28-SNAPSHOT/org/eclipse/jetty/webapp/WebAppClassLoader.html" target="_top">WebAppClassLoader</a>.</p><p>If you do not subclass WebAppClassLoader, we recommend that you implement the <a class="link" href="http://www.eclipse.org/jetty/javadoc/9.4.28-SNAPSHOT/org/eclipse/jetty/util/ClassVisibilityChecker.html" target="_top">ClassVisibilityChecker</a> interface.
Without this interface, session persistence will be slower.</p><p>You configure the classloader for the webapp like so:</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code>MyCleverClassLoader myCleverClassLoader = new MyCleverClassLoader();
 ...
   WebAppContext webapp = new WebAppContext();
 ...
   webapp.setClassLoader(myCleverClassLoader);</code></pre><p>You can also accomplish this in a context xml file.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="starting-jetty-custom-classloader"></a>Starting Jetty with a Custom ClassLoader</h3></div></div></div><p>If you start a Jetty server using a custom class loader&#8211;consider the Jetty classes not being available to the system class loader, only your custom class loader&#8211;you may run into class loading issues when the <code class="literal">WebAppClassLoader</code> kicks in.
By default the <code class="literal">WebAppClassLoader</code> uses the system class loader as its parent, hence the problem. This is easy to fix, like so:</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code>context.setClassLoader(new WebAppClassLoader(this.getClass().getClassLoader(), context));</code></pre><p>or</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code>context.setClassLoader(new WebAppClassLoader(new MyCustomClassLoader(), context));</code></pre></div></div><script type="text/javascript">
      SyntaxHighlighter.all()
    </script><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="architecture.html"><i class="fa fa-chevron-left" aria-hidden="true"></i> Previous</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="architecture.html"><i class="fa fa-chevron-up" aria-hidden="true"></i> Top</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="jetty-1xx-responses.html">Next <i class="fa fa-chevron-right" aria-hidden="true"></i></a></td></tr><tr><td width="40%" align="left" valign="top">Chapter&nbsp;30.&nbsp;Architecture&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="index.html"><i class="fa fa-home" aria-hidden="true"></i> Home</a></td><td width="40%" align="right" valign="top">&nbsp;Managing 1xx Responses</td></tr></table></div><p xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><div class="jetty-callout">
            See an error or something missing?
            <span class="callout"><a href="http://github.com/eclipse/jetty.project">Contribute to this documentation at
                <span class="website"><i class="fa fa-github" aria-hidden="true"></i> Github!</span></a></span><span style="float: right"><i>(Generated: 2020-03-10)</i></span></div></p></body></html>