Skip to main content
summaryrefslogtreecommitdiffstats
blob: 8f9faba7f4d56bd977d2c325812a6b221af67800 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
<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-NS Stylesheets V1.76.1"><meta name="keywords" content="jetty, servlet, servlet-api, cometd, http, spdy, websocket, eclipse, maven, java, server, software"><link rel="home" href="index.html" title="Jetty : The Definitive Reference"><link rel="up" href="architecture.html" title="Chapter&nbsp;34.&nbsp;Architecture"><link rel="prev" href="architecture.html" title="Chapter&nbsp;34.&nbsp;Architecture"><link rel="next" href="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"><script type="text/javascript" src="js/shCore.js"></script><script type="text/javascript" src="js/shBrushJava.js"></script><script type="text/javascript" src="js/shBrushXml.js"></script><script type="text/javascript" src="js/shBrushBash.js"></script><script type="text/javascript" src="js/shBrushJScript.js"></script><script type="text/javascript" src="js/shBrushSql.js"></script><script type="text/javascript" src="js/shBrushProperties.js"></script><script type="text/javascript" src="js/shBrushPlain.js"></script><link type="text/css" rel="stylesheet" href="css/shCore.css"><link type="text/css" rel="stylesheet" href="css/shThemeEclipse.css"><link type="text/css" rel="stylesheet" href="css/font-awesome.min.css"><style 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" type="text/css">
          body { 
            background-image: url('images/draft-ribbon.png');
            background-repeat: no-repeat;
            background-position: top left;
          }
        </style></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.2.2-SNAPSHOT</span></td><td style="width: 50%"><script type="text/javascript">  (function() {
            var cx = '016459005284625897022:obd4lsai2ds';
            var gcse = document.createElement('script');
            gcse.type = 'text/javascript';
            gcse.async = true;
            gcse.src = (document.location.protocol == 'https:' ? 'https:' : 'http:') +
            '//www.google.com/cse/cse.js?cx=' + cx;
            var s = document.getElementsByTagName('script')[0];
            s.parentNode.insertBefore(gcse, s);
            })();
          </script><gcse:search></gcse:search></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="icon-chevron-left"></i> Previous</a>&nbsp;</td><th width="60%" align="center">Chapter&nbsp;34.&nbsp;Architecture<br><a accesskey="p" href="index.html"><i class="icon-home"></i> Home</a></th><td width="20%" align="right">&nbsp;<a accesskey="n" href="1xx-responses.html">Next <i class="icon-chevron-right"></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 from 1 day to full product delivery
      </p></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="draft"><h5>DRAFT</h5><p>
          This page contains content that we have migrated from Jetty 7 or Jetty 8 documentation into the correct format, but we have not yet audited it for technical accuracy in Jetty 9.  Be aware that examples or information contained on this page may be incorrect.  Please check back soon as we continue improving the documentation, or submit corrections yourself to this page through <a href="http://github.com/jetty-project/jetty-documentation" style="text-decoration:none"><i class="icon-github"></i> Github</a>. Thank you.
          </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><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" type="disc"><li class="listitem"><p>Classes contained within WEB-INF/lib or WEB-INF/classes have
      priority over classes on the parent classloader. This is the opposite of
      the normal behaviour of a Java 2 classloader.</p></li><li class="listitem"><p>System classes such as <code class="code">java.lang.String</code> are excluded
      from the webapp priority, and you may not replace them with classes in
      <code class="filename">WEB-INF/lib</code> or <code class="code">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 javax
      classes should be treated as System classes.</p></li><li class="listitem"><p>Server implementation classes like <a class="link" href="http://download.eclipse.org/jetty/stable-9/apidocs/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.</p></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://download.eclipse.org/jetty/stable-9/apidocs/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="filename"> jetty-web.xml</code> file, as it
    executes after the classloader configuration is set.</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://download.eclipse.org/jetty/stable-9/apidocs/org/eclipse/jetty/webapp/WebAppContext.html#isParentLoaderPriority()" target="_top">
      org.eclipse.jetty.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="classloading-setting-system-classes"></a>Setting System Classes</h4></div></div></div><p>You can call the methods <a class="link" href="http://download.eclipse.org/jetty/stable-9/apidocs/org/eclipse/jetty/webapp/WebAppContext.html#setSystemClasses%28java.lang.String%5B%5D%29" target="_top">
      org.eclipse.jetty.webapp.WebAppContext.setSystemClasses(String
      Array)</a> or <a class="link" href="http://download.eclipse.org/jetty/stable-9/apidocs/org/eclipse/jetty/webapp/WebAppContext.html#addSystemClass(java.lang.String)" target="_top">
      org.eclipse.jetty.webapp.WebAppContext.addSystemClass(String)</a> to
      allow fine control over which classes are considered System
      classes.</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>A web application can see a System class.</p></li><li class="listitem"><p>A WEB-INF class cannot replace a System class.</p></li></ul></div><p>The default system classes are:</p><div class="table"><a name="d0e22717"></a><p class="title"><b>Table&nbsp;34.1.&nbsp;Default System Classes</b></p><div class="table-contents"><table summary="Default System Classes" border="1"><colgroup><col align="left" class="col1"><col align="left" class="col2"></colgroup><thead><tr><th colspan="2" align="center">System
              Classes</th></tr></thead><tbody><tr><td align="left">java.</td><td align="left">Java SE classes (per servlet spec v2.5 /
              SRV.9.7.2).</td></tr><tr><td align="left">javax.</td><td align="left">Java SE classes (per servlet spec v2.5 /
              SRV.9.7.2).</td></tr><tr><td align="left">org.xml.</td><td align="left">Needed by javax.xml.</td></tr><tr><td align="left">org.w3c.</td><td align="left">Needed by javax.xml.</td></tr><tr><td align="left">org.eclipse.jetty.continuation.</td><td align="left">Webapp can see and not change continuation
              classes.</td></tr><tr><td align="left">org.eclipse.jetty.jndi.</td><td align="left">Webapp can see and not change naming classes.</td></tr><tr><td align="left">org.eclipse.jetty.jaas.</td><td align="left">Webapp can see and not change JAAS classes.</td></tr><tr><td align="left">org.eclipse.jetty.websocket.</td><td align="left">WebSocket is a Jetty extension.</td></tr><tr><td align="left">org.eclipse.jetty.servlet.DefaultServlet</td><td align="left">Webapp can see and not change default servlet.</td></tr></tbody></table></div></div><br class="table-break"><p>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.</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://download.eclipse.org/jetty/stable-9/apidocs/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://download.eclipse.org/jetty/stable-9/apidocs/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" type="disc"><li class="listitem"><p>A web application cannot see a Server class.</p></li><li class="listitem"><p>A WEB-INF class can replace a Server class.</p></li></ul></div><p>The default server classes are:</p><div class="table"><a name="d0e22795"></a><p class="title"><b>Table&nbsp;34.2.&nbsp;Default Server Classes</b></p><div class="table-contents"><table summary="Default Server Classes" border="1"><colgroup><col align="left" class="col1"><col align="left" class="col2"></colgroup><thead><tr><th colspan="2" align="center">Server
              Classes</th></tr></thead><tbody><tr><td align="left">-org.eclipse.jetty.continuation.</td><td align="left">Don't hide continuation classes.</td></tr><tr><td align="left">-org.eclipse.jetty.jndi.</td><td align="left">Don't hide naming classes.</td></tr><tr><td align="left">-org.eclipse.jetty.jaas.</td><td align="left">Don't hide jaas classes.</td></tr><tr><td align="left">-org.eclipse.jetty.servlets.</td><td align="left">Don't hide utility servlet classes if provided.</td></tr><tr><td align="left">-org.eclipse.jetty.servlet.DefaultServlet</td><td align="left">Don't hide default servlet.</td></tr><tr><td align="left">-org.eclipse.jetty.servlet.listener.</td><td align="left">Don't hide utility listeners</td></tr><tr><td align="left">-org.eclipse.jetty.websocket.</td><td align="left">Don't hide websocket extension.</td></tr><tr><td align="left">org.eclipse.jetty.</td><td align="left">Do hide all other Jetty classes.</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="code">start.jar</code></h4></div></div></div><p>If you are using <a class="xref" href="">???</a>, at
      startup the jetty runtime automatically loads option Jars from the top
      level <code class="filename">$jetty.home/lib</code> directory. The default
      settings include:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Adding Jars under <code class="filename">$jetty.home/lib/ext</code> to
          the system classpath. You can place additional Jars here.</p></li><li class="listitem"><p>Adding the directory
          <code class="filename">$jetty.home/resources</code> to the classpath (may
          contain classes or other resources).</p></li><li class="listitem"><p>Adding a single path defined by the command line parameter
          <span class="emphasis"><em>path</em></span>.</p></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://download.eclipse.org/jetty/stable-9/apidocs/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><div class="informalexample"><script type="syntaxhighlighter" class="brush: xml;toolbar: false">
          <![CDATA[<Configure class="org.eclipse.jetty.webapp.WebAppContext">
 ...
 <Set name="extraClasspath>../my/classes,../my/jars/special.jar,../my/jars/other.jar>
 </Set>
 ...]]>
        </script></div></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://download.eclipse.org/jetty/stable-9/apidocs/org/eclipse/jetty/webapp/WebAppClassLoader.html" target="_top">WebAppClassLoader</a>.
    You configure the classloader for the webapp like so:</p><div class="informalexample"><script type="syntaxhighlighter" class="brush: java;toolbar: false">
          <![CDATA[MyCleverClassLoader myCleverClassLoader = new MyCleverClassLoader();
 ...
   WebAppContext webapp = new WebAppContext();
 ...
   webapp.setClassLoader(myCleverClassLoader);
      ]]>
        </script></div><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
    WebAppClassLoader kicks in. By default the WebAppClassLoader uses the
    system class loader as its parent, hence the problem. This is easy to fix,
    like so:</p><div class="informalexample"><script type="syntaxhighlighter" class="brush: java;toolbar: false">
          <![CDATA[context.setClassLoader(new WebAppClassLoader(this.getClass().getClassLoader(), context));]]>
        </script></div><p>or</p><div class="informalexample"><script type="syntaxhighlighter" class="brush: java;toolbar: false">
          <![CDATA[context.setClassLoader(new WebAppClassLoader(new MyCustomClassLoader(), context));]]>
        </script></div></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="icon-chevron-left"></i> Previous</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="architecture.html"><i class="icon-chevron-up"></i> Top</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="1xx-responses.html">Next <i class="icon-chevron-right"></i></a></td></tr><tr><td width="40%" align="left" valign="top">Chapter&nbsp;34.&nbsp;Architecture&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="index.html"><i class="icon-home"></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/jetty-project/jetty-documentation">Contribute to this documentation at
                <span class="website"><i class="icon-github"></i> Github!</span></a></span><span style="float: right"><i>(Generated: 2014-07-27T01:00:33-07:00)</i></span></div></p><script 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" type="text/javascript">
  var _gaq = _gaq || [];
  _gaq.push(['_setAccount', 'UA-1149868-7']);
  _gaq.push(['_trackPageview']);

  (function() {
    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
    ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
  })();
    </script></body></html>

Back to the top