| <?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> |
| <author email="craigmcc@apache.org">Craig R. McClanahan</author> |
| <author email="yoavs@apache.org">Yoav Shapira</author> |
| <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 2.1.1 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 availabaility 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.0 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.1 |
| implementation</li> |
| <li><em>websocket-api.jar</em> — Optional. Jakarta WebSocket 2.1 API |
| </li> |
| <li><em>websocket-client-api.jar</em> — Optional. Jakarta WebSocket |
| 2.1 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> |
