Subversion Repositories Integrator Subversion

Rev

Details | Last modification | View Log | RSS feed

Rev Author Line No. Line
771 blopes 1 
<!DOCTYPE html SYSTEM "about:legacy-compat">
2 
<html lang="en"><head><META http-equiv="Content-Type" content="text/html; charset=UTF-8"><link href="./images/docs-stylesheet.css" rel="stylesheet" type="text/css"><title>Apache Tomcat 9 (9.0.112) - Class Loader How-To</title></head><body><div id="wrapper"><header><div id="header"><div><div><div class="logo noPrint"><a href="https://tomcat.apache.org/"><img alt="Tomcat Home" src="./images/tomcat.png"></a></div><div style="height: 1px;"></div><div class="asfLogo noPrint"><a href="https://www.apache.org/" target="_blank"><img src="./images/asf-logo.svg" alt="The Apache Software Foundation" style="width: 266px; height: 83px;"></a></div><h1>Apache Tomcat 9</h1><div class="versionInfo">
3 
            Version 9.0.112,
4 
            <time datetime="2025-11-06">Nov 6 2025</time></div><div style="height: 1px;"></div><div style="clear: left;"></div></div></div></div></header><div id="middle"><div><div id="mainLeft" class="noprint"><div><nav><div><h2>Links</h2><ul><li><a href="index.html">Docs Home</a></li><li><a href="https://cwiki.apache.org/confluence/display/TOMCAT/FAQ">FAQ</a></li></ul></div><div><h2>User Guide</h2><ul><li><a href="introduction.html">1) Introduction</a></li><li><a href="setup.html">2) Setup</a></li><li><a href="appdev/index.html">3) First webapp</a></li><li><a href="deployer-howto.html">4) Deployer</a></li><li><a href="manager-howto.html">5) Manager</a></li><li><a href="host-manager-howto.html">6) Host Manager</a></li><li><a href="realm-howto.html">7) Realms and AAA</a></li><li><a href="security-manager-howto.html">8) Security Manager</a></li><li><a href="jndi-resources-howto.html">9) JNDI Resources</a></li><li><a href="jndi-datasource-examples-howto.html">10) JDBC DataSources</a></li><li><a href="class-loader-howto.html">11) Classloading</a></li><li><a href="jasper-howto.html">12) JSPs</a></li><li><a href="ssl-howto.html">13) SSL/TLS</a></li><li><a href="ssi-howto.html">14) SSI</a></li><li><a href="cgi-howto.html">15) CGI</a></li><li><a href="proxy-howto.html">16) Proxy Support</a></li><li><a href="mbeans-descriptors-howto.html">17) MBeans Descriptors</a></li><li><a href="default-servlet.html">18) Default Servlet</a></li><li><a href="cluster-howto.html">19) Clustering</a></li><li><a href="balancer-howto.html">20) Load Balancer</a></li><li><a href="connectors.html">21) Connectors</a></li><li><a href="monitoring.html">22) Monitoring and Management</a></li><li><a href="logging.html">23) Logging</a></li><li><a href="apr.html">24) APR/Native</a></li><li><a href="virtual-hosting-howto.html">25) Virtual Hosting</a></li><li><a href="aio.html">26) Advanced IO</a></li><li><a href="maven-jars.html">27) Mavenized</a></li><li><a href="security-howto.html">28) Security Considerations</a></li><li><a href="windows-service-howto.html">29) Windows Service</a></li><li><a href="windows-auth-howto.html">30) Windows Authentication</a></li><li><a href="jdbc-pool.html">31) Tomcat's JDBC Pool</a></li><li><a href="web-socket-howto.html">32) WebSocket</a></li><li><a href="rewrite.html">33) Rewrite</a></li><li><a href="cdi.html">34) CDI 2 and JAX-RS</a></li><li><a href="graal.html">35) AOT/GraalVM Support</a></li></ul></div><div><h2>Reference</h2><ul><li><a href="RELEASE-NOTES.txt">Release Notes</a></li><li><a href="config/index.html">Configuration</a></li><li><a href="api/index.html">Tomcat Javadocs</a></li><li><a href="servletapi/index.html">Servlet 4.0 Javadocs</a></li><li><a href="jspapi/index.html">JSP 2.3 Javadocs</a></li><li><a href="elapi/index.html">EL 3.0 Javadocs</a></li><li><a href="websocketapi/index.html">WebSocket 1.1 Javadocs</a></li><li><a href="jaspicapi/index.html">JASPIC 1.1 Javadocs</a></li><li><a href="annotationapi/index.html">Common Annotations 1.3 Javadocs</a></li><li><a href="https://tomcat.apache.org/connectors-doc/">JK 1.2 Documentation</a></li></ul></div><div><h2>Apache Tomcat Development</h2><ul><li><a href="building.html">Building</a></li><li><a href="changelog.html">Changelog</a></li><li><a href="https://cwiki.apache.org/confluence/display/TOMCAT/Tomcat+Versions">Status</a></li><li><a href="developers.html">Developers</a></li><li><a href="architecture/index.html">Architecture</a></li><li><a href="tribes/introduction.html">Tribes</a></li></ul></div></nav></div></div><div id="mainRight"><div id="content"><h2>Class Loader How-To</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
5 
<ul><li><a href="#Overview">Overview</a></li><li><a href="#Class_Loader_Definitions">Class Loader Definitions</a></li><li><a href="#XML_Parsers_and_Java">XML Parsers and Java</a></li><li><a href="#Running_under_a_security_manager">Running under a security manager</a></li><li><a href="#Advanced_configuration">Advanced configuration</a></li></ul>
6 
</div><h3 id="Overview">Overview</h3><div class="text">
7 
 
8 
<p>Like many server applications, Tomcat installs a variety of class loaders
9 
(that is, classes that implement <code>java.lang.ClassLoader</code>) to allow
10 
different portions of the container, and the web applications running on the
11 
container, to have access to different repositories of available classes and
12 
resources.  This mechanism is used to provide the functionality defined in the
13 
Servlet Specification, version 2.4&nbsp;&mdash; in particular, Sections 9.4
14 
and 9.6.</p>
15 
 
16 
<p>In a Java environment, class loaders are
17 
arranged in a parent-child tree.  Normally, when a class loader is asked to
18 
load a particular class or resource, it delegates the request to a parent
19 
class loader first, and then looks in its own repositories only if the parent
20 
class loader(s) cannot find the requested class or resource.  Note, that the
21 
model for web application class loaders <em>differs</em> slightly from this,
22 
as discussed below, but the main principles are the same.</p>
23 
 
24 
<p>When Tomcat is started, it creates a set of class loaders that are
25 
organized into the following parent-child relationships, where the parent
26 
class loader is above the child class loader:</p>
27 
 
28 
<div class="codeBox"><pre><code>      Bootstrap
29 
          |
30 
       System
31 
          |
32 
       Common
33 
       /     \
34 
  Webapp1   Webapp2 ...</code></pre></div>
35 
 
36 
<p>The characteristics of each of these class loaders, including the source
37 
of classes and resources that they make visible, are discussed in detail in
38 
the following section.</p>
39 
 
40 
</div><h3 id="Class_Loader_Definitions">Class Loader Definitions</h3><div class="text">
41 
 
42 
<p>As indicated in the diagram above, Tomcat creates the following class
43 
loaders as it is initialized:</p>
44 
<ul>
45 
<li><p><strong>Bootstrap</strong> &mdash; This class loader contains the basic
46 
    runtime classes provided by the Java Virtual Machine, plus any classes from
47 
    JAR files present in the System Extensions directory
48 
    (<code>$JAVA_HOME/jre/lib/ext</code>).  <em>Note</em>: some JVMs may
49 
    implement this as more than one class loader, or it may not be visible
50 
    (as a class loader) at all.</p></li>
51 
<li><p><strong>System</strong> &mdash; This class loader is normally initialized
52 
    from the contents of the <code>CLASSPATH</code> environment variable.  All
53 
    such classes are visible to both Tomcat internal classes, and to web
54 
    applications.  However, the standard Tomcat startup scripts
55 
    (<code>$CATALINA_HOME/bin/catalina.sh</code> or
56 
    <code>%CATALINA_HOME%\bin\catalina.bat</code>) totally ignore the contents
57 
    of the <code>CLASSPATH</code> environment variable itself, and instead
58 
    build the System class loader from the following repositories:
59 
    </p>
60 
    <ul>
61 
    <li><p><em>$CATALINA_HOME/bin/bootstrap.jar</em> &mdash; Contains the
62 
        main() method that is used to initialize the Tomcat server, and the
63 
        class loader implementation classes it depends on.</p></li>
64 
    <li><p><em>$CATALINA_BASE/bin/tomcat-juli.jar</em> or
65 
        <em>$CATALINA_HOME/bin/tomcat-juli.jar</em> &mdash; Logging
66 
        implementation classes. These include enhancement classes to
67 
        <code>java.util.logging</code> API, known as Tomcat JULI,
68 
        and a package-renamed copy of Apache Commons Logging library
69 
        used internally by Tomcat.
70 
        See <a href="logging.html">logging documentation</a> for more
71 
        details.</p>
72 
        <p>If <code>tomcat-juli.jar</code> is present in
73 
        <em>$CATALINA_BASE/bin</em>, it is used instead of the one in
74 
        <em>$CATALINA_HOME/bin</em>. It is useful in certain logging
75 
        configurations</p></li>
76 
    <li><p><em>$CATALINA_HOME/bin/commons-daemon.jar</em> &mdash; The classes
77 
        from <a href="https://commons.apache.org/daemon/">Apache Commons
78 
        Daemon</a> project.
79 
        This JAR file is not present in the <code>CLASSPATH</code> built by
80 
        <code>catalina.bat</code>|<code>.sh</code> scripts, but is referenced
81 
        from the manifest file of <em>bootstrap.jar</em>.</p></li>
82 
    </ul>
83 
    </li>
84 
<li><p><strong>Common</strong> &mdash; This class loader contains additional
85 
    classes that are made visible to both Tomcat internal classes and to all
86 
    web applications.</p>
87 
    <p>Normally, application classes should <strong>NOT</strong>
88 
    be placed here.  The locations searched by this class loader are defined by
89 
    the <code>common.loader</code> property in
90 
    $CATALINA_BASE/conf/catalina.properties. The default setting will search the
91 
    following locations in the order they are listed:</p>
92 
    <ul>
93 
      <li>unpacked classes and resources in <code>$CATALINA_BASE/lib</code></li>
94 
      <li>JAR files in <code>$CATALINA_BASE/lib</code></li>
95 
      <li>unpacked classes and resources in <code>$CATALINA_HOME/lib</code></li>
96 
      <li>JAR files in <code>$CATALINA_HOME/lib</code></li>
97 
    </ul>
98 
    <p>By default, this includes the following:</p>
99 
    <ul>
100 
    <li><em>annotations-api.jar</em> &mdash; Common Annotations 1.3 classes.
101 
        </li>
102 
    <li><em>catalina.jar</em> &mdash; Implementation of the Catalina servlet
103 
        container portion of Tomcat.</li>
104 
    <li><em>catalina-ant.jar</em> &mdash; Optional. Tomcat Catalina Ant tasks
105 
        for working with the Manager web application.</li>
106 
    <li><em>catalina-ha.jar</em> &mdash; Optional. High availability package
107 
        that provides session clustering functionality built on Tribes.</li>
108 
    <li><em>catalina-ssi.jar</em> &mdash; Optional. Server-side Includes module.
109 
        </li>
110 
    <li><em>catalina-storeconfig.jar</em> &mdash; Optional. Generation of XML
111 
        configuration files from current state.</li>
112 
    <li><em>catalina-tribes.jar</em> &mdash; Optional. Group communication
113 
        package used by the high availability package.</li>
114 
    <li><em>ecj-*.jar</em> &mdash; Optional. Eclipse JDT Java compiler used to
115 
        compile JSPs to Servlets.</li>
116 
    <li><em>el-api.jar</em> &mdash; Optional. EL 3.0 API.</li>
117 
    <li><em>jasper.jar</em> &mdash; Optional. Tomcat Jasper JSP Compiler and
118 
        Runtime.</li>
119 
    <li><em>jasper-el.jar</em> &mdash; Optional. Tomcat EL implementation.</li>
120 
    <li><em>jaspic-api.jar</em> &mdash; JASPIC 1.1 API.</li>
121 
    <li><em>jsp-api.jar</em> &mdash; Optional. JSP 2.3 API.</li>
122 
    <li><em>servlet-api.jar</em> &mdash; Java Servlet 4.0 API.</li>
123 
    <li><em>tomcat-api.jar</em> &mdash; Several interfaces defined by Tomcat.
124 
        </li>
125 
    <li><em>tomcat-coyote.jar</em> &mdash; Tomcat connectors and utility
126 
        classes.</li>
127 
    <li><em>tomcat-dbcp.jar</em> &mdash; Optional. Database connection pool
128 
        implementation based on package-renamed copy of Apache Commons Pool 2
129 
        and Apache Commons DBCP 2.</li>
130 
    <li><em>tomcat-i18n-**.jar</em> &mdash; Optional JARs containing resource
131 
        bundles for other languages. As default bundles are also included in
132 
        each individual JAR, they can be safely removed if no
133 
        internationalization of messages is needed.</li>
134 
    <li><em>tomcat-jdbc.jar</em> &mdash; Optional. An alternative database
135 
        connection pool implementation, known as Tomcat JDBC pool. See
136 
        <a href="jdbc-pool.html">documentation</a> for more details.</li>
137 
    <li><em>tomcat-jni.jar</em> &mdash; Provides the integration with the Tomcat
138 
        Native library.</li>
139 
    <li><em>tomcat-util.jar</em> &mdash; Common classes used by various
140 
        components of Apache Tomcat.</li>
141 
    <li><em>tomcat-util-scan.jar</em> &mdash; Provides the class scanning
142 
        functionality used by Tomcat.</li>
143 
    <li><em>tomcat-websocket.jar</em> &mdash; Optional. Java WebSocket 1.1
144 
        implementation</li>
145 
    <li><em>websocket-api.jar</em> &mdash; Optional. Java WebSocket 1.1 API
146 
        </li>
147 
    </ul></li>
148 
<li><p><strong>WebappX</strong> &mdash; A class loader is created for each web
149 
    application that is deployed in a single Tomcat instance.  All unpacked
150 
    classes and resources in the <code>/WEB-INF/classes</code> directory of
151 
    your web application, plus classes and resources in JAR files
152 
    under the <code>/WEB-INF/lib</code> directory of your web application,
153 
    are made visible to this web application, but not to other ones.</p></li>
154 
</ul>
155 
 
156 
<p>As mentioned above, the web application class loader diverges from the
157 
default Java delegation model (in accordance with the recommendations in the
158 
Servlet Specification, version 2.4, section 9.7.2 Web Application Classloader).
159 
When a request to load a
160 
class from the web application's <em>WebappX</em> class loader is processed,
161 
this class loader will look in the local repositories <strong>first</strong>,
162 
instead of delegating before looking.  There are exceptions. Classes which are
163 
part of the JRE base classes cannot be overridden. There are some exceptions
164 
such as the XML parser components which can be overridden using the appropriate
165 
JVM feature which is the endorsed standards override feature for Java &lt;= 8
166 
and the upgradeable modules feature for Java 9+.
167 
Lastly, the web application class loader will always delegate first for JavaEE
168 
API classes for the specifications implemented by Tomcat
169 
(Servlet, JSP, EL, WebSocket). All other class loaders in Tomcat follow the
170 
usual delegation pattern.</p>
171 
 
172 
<p>Therefore, from the perspective of a web application, class or resource
173 
loading looks in the following repositories, in this order:</p>
174 
<ul>
175 
<li>Bootstrap classes of your JVM</li>
176 
<li><em>/WEB-INF/classes</em> of your web application</li>
177 
<li><em>/WEB-INF/lib/*.jar</em> of your web application</li>
178 
<li>System class loader classes (described above)</li>
179 
<li>Common class loader classes (described above)</li>
180 
</ul>
181 
 
182 
<p>If the web application class loader is
183 
<a href="config/loader.html">configured</a> with
184 
<code>&lt;Loader delegate="true"/&gt;</code>
185 
then the order becomes:</p>
186 
<ul>
187 
<li>Bootstrap classes of your JVM</li>
188 
<li>System class loader classes (described above)</li>
189 
<li>Common class loader classes (described above)</li>
190 
<li><em>/WEB-INF/classes</em> of your web application</li>
191 
<li><em>/WEB-INF/lib/*.jar</em> of your web application</li>
192 
</ul>
193 
 
194 
</div><h3 id="XML_Parsers_and_Java">XML Parsers and Java</h3><div class="text">
195 
 
196 
<p>Starting with Java 1.4 a copy of JAXP APIs and an XML parser are packed
197 
inside the JRE.  This has impacts on applications that wish to use their own
198 
XML parser.</p>
199 
 
200 
<p>In old versions of Tomcat, you could simply replace the XML parser
201 
in the Tomcat libraries directory to change the parser
202 
used by all web applications.  However, this technique will not be effective
203 
when you are running modern versions of Java, because the usual class loader
204 
delegation process will always choose the implementation inside the JDK in
205 
preference to this one.</p>
206 
 
207 
<p>Java &lt;= 8 supports a mechanism called the "Endorsed Standards Override
208 
Mechanism" to allow replacement of APIs created outside of the JCP
209 
(i.e. DOM and SAX from W3C).  It can also be used to update the XML parser
210 
implementation.  For more information, see:
211 
<a href="http://docs.oracle.com/javase/1.5.0/docs/guide/standards/index.html">
212 
http://docs.oracle.com/javase/1.5.0/docs/guide/standards/index.html</a>. For
213 
Java 9+, use the upgradeable modules feature.</p>
214 
 
215 
<p>Tomcat utilizes the endorsed mechanism by including the system property setting
216 
<code>-Djava.endorsed.dirs=$JAVA_ENDORSED_DIRS</code> in the
217 
command line that starts the container. The default value of this option is
218 
<em>$CATALINA_HOME/endorsed</em>. This <em>endorsed</em> directory is not
219 
created by default. Note that the endorsed feature is no longer supported
220 
with Java 9 and the above system property will only be set if either the
221 
directory <em>$CATALINA_HOME/endorsed</em> exists, or the variable
222 
<code>JAVA_ENDORSED_DIRS</code> has been set.
223 
</p>
224 
 
225 
<p>Note that overriding any JRE component carries risk. If the overriding
226 
component does not provide a 100% compatible API (e.g. the API provided by
227 
Xerces is not 100% compatible with the XML API provided by the JRE) then there
228 
is a risk that Tomcat and/or the deployed application will experience errors.</p>
229 
 
230 
</div><h3 id="Running_under_a_security_manager">Running under a security manager</h3><div class="text">
231 
 
232 
<p>When running under a security manager the locations from which classes
233 
are permitted to be loaded will also depend on the contents of your policy
234 
file. See <a href="security-manager-howto.html">Security Manager How-To</a>
235 
for further information.</p>
236 
 
237 
</div><h3 id="Advanced_configuration">Advanced configuration</h3><div class="text">
238 
 
239 
<p>A more complex class loader hierarchy may also be configured. See the diagram
240 
below. By default, the <strong>Server</strong> and <strong>Shared</strong>
241 
class loaders are not defined and the simplified hierarchy shown above is used.
242 
This more complex hierarchy may be use by defining values for the
243 
<code>server.loader</code> and/or <code>shared.loader</code> properties in
244 
<code>conf/catalina.properties</code>.</p>
245 
 
246 
<div class="codeBox"><pre><code>
247 
  Bootstrap
248 
      |
249 
    System
250 
      |
251 
    Common
252 
     /  \
253 
Server  Shared
254 
         /  \
255 
   Webapp1  Webapp2 ...</code></pre></div>
256 
 
257 
<p>The <strong>Server</strong> class loader is only visible to Tomcat internals
258 
and is completely invisible to web applications.</p>
259 
 
260 
<p>The <strong>Shared</strong> class loader is visible to all web applications
261 
and may be used to shared code across all web applications. However, any updates
262 
to this shared code will require a Tomcat restart.</p>
263 
 
264 
</div></div></div></div></div><footer><div id="footer">
265 
    Copyright &copy; 1999-2025, The Apache Software Foundation
266 
    <br>
267 
    Apache Tomcat, Tomcat, Apache, the Apache Tomcat logo and the Apache logo
268 
    are either registered trademarks or trademarks of the Apache Software
269 
    Foundation.
270 
    </div></footer></div></body></html>