/usr/share/tomcat8-docs/docs/class-loader-howto.html is in tomcat8-docs 8.0.32-1ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 | <!DOCTYPE html SYSTEM "about:legacy-compat">
<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 8 (8.0.32) - Class Loader HOW-TO</title><meta name="author" content="Craig R. McClanahan"><meta name="author" content="Yoav Shapira"><script type="application/javascript" data-comments-identifier="tomcat-8.0-doc/class-loader-howto">
"use strict"; // Enable strict mode
(function() {
var thisScript = document.currentScript;
if (!thisScript) { // Workaround for IE <= 11
var scripts = document.getElementsByTagName("script");
thisScript = scripts[scripts.length - 1];
}
document.addEventListener("DOMContentLoaded", (function() {
var commentsDiv = document.getElementById("comments_thread");
var commentsShortname = "tomcat";
var commentsIdentifier = "http://tomcat.apache.org/" +
thisScript.getAttribute("data-comments-identifier") + ".html";
(function(w, d) {
if (w.location.hostname.toLowerCase() == "tomcat.apache.org") {
var s = d.createElement("script");
s.type = "application/javascript";
s.async = true;
s.src = "https://comments.apache.org/show_comments.lua?site=" +
encodeURIComponent(commentsShortname) +
"&page=" + encodeURIComponent(commentsIdentifier);
d.head.appendChild(s);
} else {
commentsDiv.appendChild(d.createTextNode("Comments are disabled for this page at the moment."));
}
})(window, document);
}), false);
})();
</script></head><body><div id="wrapper"><header><div id="header"><div><div><div class="logo noPrint"><a href="http://tomcat.apache.org/"><img alt="Tomcat Home" src="./images/tomcat.png"></a></div><div style="height: 1px;"></div><div class="asfLogo noPrint"><a href="http://www.apache.org/" target="_blank"><img src="./images/asf-feather.png" alt="The Apache Software Foundation" style="width: 266px; height: 83px;"></a></div><h1>Apache Tomcat 8</h1><div class="versionInfo">
Version 8.0.32,
<time datetime="2016-02-05">Feb 5 2016</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="http://wiki.apache.org/tomcat/FAQ">FAQ</a></li><li><a href="#comments_section">User Comments</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="realm-howto.html">6) Realms and AAA</a></li><li><a href="security-manager-howto.html">7) Security Manager</a></li><li><a href="jndi-resources-howto.html">8) JNDI Resources</a></li><li><a href="jndi-datasource-examples-howto.html">9) JDBC DataSources</a></li><li><a href="class-loader-howto.html">10) Classloading</a></li><li><a href="jasper-howto.html">11) JSPs</a></li><li><a href="ssl-howto.html">12) SSL/TLS</a></li><li><a href="ssi-howto.html">13) SSI</a></li><li><a href="cgi-howto.html">14) CGI</a></li><li><a href="proxy-howto.html">15) Proxy Support</a></li><li><a href="mbeans-descriptor-howto.html">16) MBean Descriptor</a></li><li><a href="default-servlet.html">17) Default Servlet</a></li><li><a href="cluster-howto.html">18) Clustering</a></li><li><a href="balancer-howto.html">19) Load Balancer</a></li><li><a href="connectors.html">20) Connectors</a></li><li><a href="monitoring.html">21) Monitoring and Management</a></li><li><a href="logging.html">22) Logging</a></li><li><a href="apr.html">23) APR/Native</a></li><li><a href="virtual-hosting-howto.html">24) Virtual Hosting</a></li><li><a href="aio.html">25) Advanced IO</a></li><li><a href="extras.html">26) Additional Components</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></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 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="http://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="http://wiki.apache.org/tomcat/TomcatVersions">Status</a></li><li><a href="developers.html">Developers</a></li><li><a href="architecture/index.html">Architecture</a></li><li><a href="funcspecs/index.html">Functional Specs.</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">
<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></ul>
</div><h3 id="Overview">Overview</h3><div class="text">
<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>
<div class="codeBox"><pre><code> Bootstrap
|
System
|
Common
/ \
Webapp1 Webapp2 ...</code></pre></div>
<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>
</div><h3 id="Class_Loader_Definitions">Class Loader Definitions</h3><div class="text">
<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="http://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> — JavaEE annotations classes.</li>
<li><em>catalina.jar</em> — Implementation of the Catalina servlet
container portion of Tomcat.</li>
<li><em>catalina-ant.jar</em> — Tomcat Catalina Ant tasks.</li>
<li><em>catalina-ha.jar</em> — High availability package.</li>
<li><em>catalina-storeconfig.jar</em> — Generation of XML
configuration files from current state</li>
<li><em>catalina-tribes.jar</em> — Group communication package.</li>
<li><em>ecj-*.jar</em> — Eclipse JDT Java compiler.</li>
<li><em>el-api.jar</em> — EL 3.0 API.</li>
<li><em>jasper.jar</em> — Tomcat Jasper JSP Compiler and Runtime.</li>
<li><em>jasper-el.jar</em> — Tomcat Jasper EL implementation.</li>
<li><em>jsp-api.jar</em> — JSP 2.3 API.</li>
<li><em>servlet-api.jar</em> — Servlet 3.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> — Database connection pool
implementation based on package-renamed copy of Apache Commons Pool
and Apache Commons DBCP.</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> — 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-util.jar</em> — Common classes used by various components of
Apache Tomcat.</li>
<li><em>tomcat-websocket.jar</em> — WebSocket 1.1 implementation</li>
<li><em>websocket-api.jar</em> — WebSocket 1.1 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. For some classes (such as
the XML parser components in J2SE 1.4+), the J2SE 1.4 endorsed feature can be
used.
Lastly, the web application class loader will always delegate first for JavaEE
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>
</div><h3 id="XML_Parsers_and_Java">XML Parsers and Java</h3><div class="text">
<p>Starting with Java 1.4 a copy of JAXP APIs and an XML parser are packed
inside the JRE. This has impacts on applications that wish to use their own
XML parser.</p>
<p>In old 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 the "Endorsed Standards Override
Mechanism" 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. For more information, see:
<a href="http://docs.oracle.com/javase/1.5.0/docs/guide/standards/index.html">
http://docs.oracle.com/javase/1.5.0/docs/guide/standards/index.html</a>.</p>
<p>Tomcat utilizes this mechanism by including the system property setting
<code>-Djava.endorsed.dirs=$JAVA_ENDORSED_DIRS</code> in the
command line that starts the container. The default value of this option is
<em>$CATALINA_HOME/endorsed</em>. This <em>endorsed</em> directory is not
created by default.</p>
</div><h3 id="Running_under_a_security_manager">Running under a security manager</h3><div class="text">
<p>When running under a security manager the locations from which classes
are permitted to be loaded will also depend on the contents of your policy
file. See <a href="security-manager-howto.html">Security Manager HOW-TO</a>
for further information.</p>
</div><div class="noprint"><h3 id="comments_section">
Comments
</h3><div class="text"><p class="notice"><strong>Notice: </strong>This comments section collects your suggestions
on improving documentation for Apache Tomcat.<br><br>
If you have trouble and need help, read
<a href="http://tomcat.apache.org/findhelp.html">Find Help</a> page
and ask your question on the tomcat-users
<a href="http://tomcat.apache.org/lists.html">mailing list</a>.
Do not ask such questions here. This is not a Q&A section.<br><br>
The Apache Comments System is explained <a href="./comments.html">here</a>.
Comments may be removed by our moderators if they are either
implemented or considered invalid/off-topic.
</p><div id="comments_thread"></div></div></div></div></div></div></div><footer><div id="footer">
Copyright © 1999-2016, The Apache Software Foundation
</div></footer></div></body></html>
|