<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="class-loader-howto.html">
&project;
<properties>
<title>Class Loader How-To</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Overview">
<p>Like many server applications, Tomcat installs a variety of class loaders
(that is, classes that implement <code>java.lang.ClassLoader</code>) to allow
different portions of the container, and the web applications running on the
container, to have access to different repositories of available classes and
resources. This mechanism is used to provide the functionality defined in the
Servlet Specification, version 2.4 — in particular, Sections 9.4
and 9.6.</p>
<p>In a Java environment, class loaders are
arranged in a parent-child tree. Normally, when a class loader is asked to
load a particular class or resource, it delegates the request to a parent
class loader first, and then looks in its own repositories only if the parent
class loader(s) cannot find the requested class or resource. Note, that the
model for web application class loaders <em>differs</em> slightly from this,
as discussed below, but the main principles are the same.</p>
<p>When Tomcat is started, it creates a set of class loaders that are
organized into the following parent-child relationships, where the parent
class loader is above the child class loader:</p>
<source> Bootstrap
|
System
|
Common
/ \
Webapp1 Webapp2 ...</source>
<p>The characteristics of each of these class loaders, including the source
of classes and resources that they make visible, are discussed in detail in
the following section.</p>
</section>
<section name="Class Loader Definitions">
<p>As indicated in the diagram above, Tomcat creates the following class
loaders as it is initialized:</p>
<ul>
<li><p><strong>Bootstrap</strong> — This class loader contains the basic
runtime classes provided by the Java Virtual Machine, plus any classes from
JAR files present in the System Extensions directory
(<code>$JAVA_HOME/jre/lib/ext</code>). <em>Note</em>: some JVMs may
implement this as more than one class loader, or it may not be visible
(as a class loader) at all.</p></li>
<li><p><strong>System</strong> — This class loader is normally initialized
from the contents of the <code>CLASSPATH</code> environment variable. All
such classes are visible to both Tomcat internal classes, and to web
applications. However, the standard Tomcat startup scripts
(<code>$CATALINA_HOME/bin/catalina.sh</code> or
<code>%CATALINA_HOME%\bin\catalina.bat</code>) totally ignore the contents
of the <code>CLASSPATH</code> environment variable itself, and instead
build the System class loader from the following repositories:
</p>
<ul>
<li><p><em>$CATALINA_HOME/bin/bootstrap.jar</em> — Contains the
main() method that is used to initialize the Tomcat server, and the
class loader implementation classes it depends on.</p></li>
<li><p><em>$CATALINA_BASE/bin/tomcat-juli.jar</em> or
<em>$CATALINA_HOME/bin/tomcat-juli.jar</em> — Logging
implementation classes. These include enhancement classes to
<code>java.util.logging</code> API, known as Tomcat JULI,
and a package-renamed copy of Apache Commons Logging library
used internally by Tomcat.
See <a href="logging.html">logging documentation</a> for more
details.</p>
<p>If <code>tomcat-juli.jar</code> is present in
<em>$CATALINA_BASE/bin</em>, it is used instead of the one in
<em>$CATALINA_HOME/bin</em>. It is useful in certain logging
configurations</p></li>
<li><p><em>$CATALINA_HOME/bin/commons-daemon.jar</em> — The classes
from <a href="https://commons.apache.org/daemon/">Apache Commons
Daemon</a> project.
This JAR file is not present in the <code>CLASSPATH</code> built by
<code>catalina.bat</code>|<code>.sh</code> scripts, but is referenced
from the manifest file of <em>bootstrap.jar</em>.</p></li>
</ul>
</li>
<li><p><strong>Common</strong> — This class loader contains additional
classes that are made visible to both Tomcat internal classes and to all
web applications.</p>
<p>Normally, application classes should <strong>NOT</strong>
be placed here. The locations searched by this class loader are defined by
the <code>common.loader</code> property in
$CATALINA_BASE/conf/catalina.properties. The default setting will search the
following locations in the order they are listed:</p>
<ul>
<li>unpacked classes and resources in <code>$CATALINA_BASE/lib</code></li>
<li>JAR files in <code>$CATALINA_BASE/lib</code></li>
<li>unpacked classes and resources in <code>$CATALINA_HOME/lib</code></li>
<li>JAR files in <code>$CATALINA_HOME/lib</code></li>
</ul>
<p>By default, this includes the following:</p>
<ul>
<li><em>annotations-api.jar</em> — Jakarta Annotations 3.0 classes.
</li>
<li><em>catalina.jar</em> — Implementation of the Catalina servlet
container portion of Tomcat.</li>
<li><em>catalina-ant.jar</em> — Optional. Tomcat Catalina Ant tasks
for working with the Manager web application.</li>
<li><em>catalina-ha.jar</em> — Optional. High availability package
that provides session clustering functionality built on Tribes.</li>
<li><em>catalina-ssi.jar</em> — Optional. Server-side Includes module.
</li>
<li><em>catalina-storeconfig.jar</em> — Optional. Generation of XML
configuration files from current state.</li>
<li><em>catalina-tribes.jar</em> — Optional. Group communication
package used by the high availability package.</li>
<li><em>ecj-*.jar</em> — Optional. Eclipse JDT Java compiler used to
compile JSPs to Servlets.</li>
<li><em>el-api.jar</em> — Optional. EL 6.0 API.</li>
<li><em>jakartaee-migration-*-shaded.jar</em> — Optional. Provides
conversion of web applications from Java EE 8 to Jakarta EE 9.</li>
<li><em>jasper.jar</em> — Optional. Tomcat Jasper JSP Compiler and
Runtime.</li>
<li><em>jasper-el.jar</em> — Optional. Tomcat EL implementation.</li>
<li><em>jaspic-api.jar</em> — Jakarta Authentication 3.1 API.</li>
<li><em>jsp-api.jar</em> — Optional. Jakarta Pages 4.0 API.</li>
<li><em>servlet-api.jar</em> — Jakarta Servlet 6.1 API.</li>
<li><em>tomcat-api.jar</em> — Several interfaces defined by Tomcat.
</li>
<li><em>tomcat-coyote.jar</em> — Tomcat connectors and utility
classes.</li>
<li><em>tomcat-dbcp.jar</em> — Optional. Database connection pool
implementation based on package-renamed copy of Apache Commons Pool 2
and Apache Commons DBCP 2.</li>
<li><em>tomcat-i18n-**.jar</em> — Optional JARs containing resource
bundles for other languages. As default bundles are also included in
each individual JAR, they can be safely removed if no
internationalization of messages is needed.</li>
<li><em>tomcat-jdbc.jar</em> — Optional. An alternative database
connection pool implementation, known as Tomcat JDBC pool. See
<a href="jdbc-pool.html">documentation</a> for more details.</li>
<li><em>tomcat-jni.jar</em> — Provides the integration with the Tomcat
Native library.</li>
<li><em>tomcat-util.jar</em> — Common classes used by various
components of Apache Tomcat.</li>
<li><em>tomcat-util-scan.jar</em> — Provides the class scanning
functionality used by Tomcat.</li>
<li><em>tomcat-websocket.jar</em> — Optional. Jakarta WebSocket 2.2
implementation</li>
<li><em>websocket-api.jar</em> — Optional. Jakarta WebSocket 2.2 API
</li>
<li><em>websocket-client-api.jar</em> — Optional. Jakarta WebSocket
2.2 Client API</li>
</ul></li>
<li><p><strong>WebappX</strong> — A class loader is created for each web
application that is deployed in a single Tomcat instance. All unpacked
classes and resources in the <code>/WEB-INF/classes</code> directory of
your web application, plus classes and resources in JAR files
under the <code>/WEB-INF/lib</code> directory of your web application,
are made visible to this web application, but not to other ones.</p></li>
</ul>
<p>As mentioned above, the web application class loader diverges from the
default Java delegation model (in accordance with the recommendations in the
Servlet Specification, version 2.4, section 9.7.2 Web Application Classloader).
When a request to load a
class from the web application's <em>WebappX</em> class loader is processed,
this class loader will look in the local repositories <strong>first</strong>,
instead of delegating before looking. There are exceptions. Classes which are
part of the JRE base classes cannot be overridden. There are some exceptions
such as the XML parser components which can be overridden using the upgradeable
modules feature.
Lastly, the web application class loader will always delegate first for Jakarta
EE API classes for the specifications implemented by Tomcat
(Servlet, JSP, EL, WebSocket). All other class loaders in Tomcat follow the
usual delegation pattern.</p>
<p>Therefore, from the perspective of a web application, class or resource
loading looks in the following repositories, in this order:</p>
<ul>
<li>Bootstrap classes of your JVM</li>
<li><em>/WEB-INF/classes</em> of your web application</li>
<li><em>/WEB-INF/lib/*.jar</em> of your web application</li>
<li>System class loader classes (described above)</li>
<li>Common class loader classes (described above)</li>
</ul>
<p>If the web application class loader is
<a href="config/loader.html">configured</a> with
<code><Loader delegate="true"/></code>
then the order becomes:</p>
<ul>
<li>Bootstrap classes of your JVM</li>
<li>System class loader classes (described above)</li>
<li>Common class loader classes (described above)</li>
<li><em>/WEB-INF/classes</em> of your web application</li>
<li><em>/WEB-INF/lib/*.jar</em> of your web application</li>
</ul>
</section>
<section name="XML Parsers and Java">
<p>In older versions of Tomcat, you could simply replace the XML parser
in the Tomcat libraries directory to change the parser
used by all web applications. However, this technique will not be effective
when you are running modern versions of Java, because the usual class loader
delegation process will always choose the implementation inside the JDK in
preference to this one.</p>
<p>Java supports a mechanism called upgradeable modules to allow replacement
of APIs created outside of the JCP (i.e. DOM and SAX from W3C). It can also be
used to update the XML parser implementation.</p>
<p>Note that overriding any JRE component carries risk. If the overriding
component does not provide a 100% compatible API (e.g. the API provided by
Xerces is not 100% compatible with the XML API provided by the JRE) then there
is a risk that Tomcat and/or the deployed application will experience errors.</p>
</section>
<section name="Advanced configuration">
<p>A more complex class loader hierarchy may also be configured. See the diagram
below. By default, the <strong>Server</strong> and <strong>Shared</strong>
class loaders are not defined and the simplified hierarchy shown above is used.
This more complex hierarchy may be use by defining values for the
<code>server.loader</code> and/or <code>shared.loader</code> properties in
<code>conf/catalina.properties</code>.</p>
<source>
Bootstrap
|
System
|
Common
/ \
Server Shared
/ \
Webapp1 Webapp2 ...</source>
<p>The <strong>Server</strong> class loader is only visible to Tomcat internals
and is completely invisible to web applications.</p>
<p>The <strong>Shared</strong> class loader is visible to all web applications
and may be used to shared code across all web applications. However, any updates
to this shared code will require a Tomcat restart.</p>
</section>
</body>
</document>