Gitiles
Code Review Sign In
source.supwisdom.com / portal_platform / tomcat-cms / 07b3087b89f4c23810bb2a7902fe5a06f392b984 / . / webapps / docs / class-loader-howto.html
blob: ded6e7429338207fcc609b5f3b7ee30a52da3182 [file] [log] [blame]
Cheng Tang07b30872014-04-27 16:37:18 +0800[diff] [blame^]1<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 7 (7.0.42) - Class Loader HOW-TO</title><meta name="author" content="Craig R. McClanahan"><meta name="author" content="Yoav Shapira"><style type="text/css" media="print">
2 .noPrint {display: none;}
3 td#mainBody {width: 100%;}
4 </style><style type="text/css">
5 code {background-color:rgb(224,255,255);padding:0 0.1em;}
6 code.attributeName, code.propertyName {background-color:transparent;}
7 </style><style type="text/css">
8 .wrapped-source code { display: block; background-color: transparent; }
9 .wrapped-source div { margin: 0 0 0 1.25em; }
10 .wrapped-source p { margin: 0 0 0 1.25em; text-indent: -1.25em; }
11 </style><style type="text/css">
12 p.notice {
13 border: 1px solid rgb(255, 0, 0);
14 background-color: rgb(238, 238, 238);
15 color: rgb(0, 51, 102);
16 padding: 0.5em;
17 margin: 1em 2em 1em 1em;
18 }
19 </style></head><body bgcolor="#ffffff" text="#000000" link="#525D76" alink="#525D76" vlink="#525D76"><table border="0" width="100%" cellspacing="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img src="./images/tomcat.gif" align="right" alt="
20 The Apache Tomcat Servlet/JSP Container
21 " border="0"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 7</font></h1><font face="arial,helvetica,sanserif">Version 7.0.42, Jul 2 2013</font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="./images/asf-logo.gif" align="right" alt="Apache Logo" border="0"></a></td></tr></table><table border="0" width="100%" cellspacing="4"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><tr><!--LEFT SIDE NAVIGATION--><td width="20%" valign="top" nowrap class="noPrint"><p><strong>Links</strong></p><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><p><strong>User Guide</strong></p><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</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></ul><p><strong>Reference</strong></p><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.2 Javadocs</a></li><li><a href="elapi/index.html">EL 2.2 Javadocs</a></li><li><a href="http://tomcat.apache.org/connectors-doc/">JK 1.2 Documentation</a></li></ul><p><strong>Apache Tomcat Development</strong></p><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></td><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left" id="mainBody"><h1>Class Loader HOW-TO</h1><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Table of Contents"><!--()--></a><a name="Table_of_Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote>
22<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>
23</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Overview"><strong>Overview</strong></a></font></td></tr><tr><td><blockquote>
24
25<p>Like many server applications, Tomcat installs a variety of class loaders
26(that is, classes that implement <code>java.lang.ClassLoader</code>) to allow
27different portions of the container, and the web applications running on the
28container, to have access to different repositories of available classes and
29resources. This mechanism is used to provide the functionality defined in the
30Servlet Specification, version 2.4&nbsp;&mdash; in particular, Sections 9.4
31and 9.6.</p>
32
33<p>In a Java environment, class loaders are
34arranged in a parent-child tree. Normally, when a class loader is asked to
35load a particular class or resource, it delegates the request to a parent
36class loader first, and then looks in its own repositories only if the parent
37class loader(s) cannot find the requested class or resource. Note, that the
38model for web application class loaders <em>differs</em> slightly from this,
39as discussed below, but the main principles are the same.</p>
40
41<p>When Tomcat is started, it creates a set of class loaders that are
42organized into the following parent-child relationships, where the parent
43class loader is above the child class loader:</p>
44
45<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
46 Bootstrap
47 |
48 System
49 |
50 Common
51 / \
52 Webapp1 Webapp2 ...
53</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
54
55<p>The characteristics of each of these class loaders, including the source
56of classes and resources that they make visible, are discussed in detail in
57the following section.</p>
58
59</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Class Loader Definitions"><!--()--></a><a name="Class_Loader_Definitions"><strong>Class Loader Definitions</strong></a></font></td></tr><tr><td><blockquote>
60
61<p>As indicated in the diagram above, Tomcat creates the following class
62loaders as it is initialized:</p>
63<ul>
64<li><p><strong>Bootstrap</strong> &mdash; This class loader contains the basic
65 runtime classes provided by the Java Virtual Machine, plus any classes from
66 JAR files present in the System Extensions directory
67 (<code>$JAVA_HOME/jre/lib/ext</code>). <em>Note</em>: some JVMs may
68 implement this as more than one class loader, or it may not be visible
69 (as a class loader) at all.</p></li>
70<li><p><strong>System</strong> &mdash; This class loader is normally initialized
71 from the contents of the <code>CLASSPATH</code> environment variable. All
72 such classes are visible to both Tomcat internal classes, and to web
73 applications. However, the standard Tomcat startup scripts
74 (<code>$CATALINA_HOME/bin/catalina.sh</code> or
75 <code>%CATALINA_HOME%\bin\catalina.bat</code>) totally ignore the contents
76 of the <code>CLASSPATH</code> environment variable itself, and instead
77 build the System class loader from the following repositories:
78 </p>
79 <ul>
80 <li><p><em>$CATALINA_HOME/bin/bootstrap.jar</em> &mdash; Contains the
81 main() method that is used to initialize the Tomcat server, and the
82 class loader implementation classes it depends on.</p></li>
83 <li><p><em>$CATALINA_BASE/bin/tomcat-juli.jar</em> or
84 <em>$CATALINA_HOME/bin/tomcat-juli.jar</em> &mdash; Logging
85 implementation classes. These include enhancement classes to
86 <code>java.util.logging</code> API, known as Tomcat JULI,
87 and a package-renamed copy of Apache Commons Logging library
88 used internally by Tomcat.
89 See <a href="logging.html">logging documentation</a> for more
90 details.</p>
91 <p>If <code>tomcat-juli.jar</code> is present in
92 <em>$CATALINA_BASE/bin</em>, it is used instead of the one in
93 <em>$CATALINA_HOME/bin</em>. It is useful in certain logging
94 configurations</p></li>
95 <li><p><em>$CATALINA_HOME/bin/commons-daemon.jar</em> &mdash; The classes
96 from <a href="http://commons.apache.org/daemon/">Apache Commons
97 Daemon</a> project.
98 This JAR file is not present in the <code>CLASSPATH</code> built by
99 <code>catalina.bat</code>|<code>.sh</code> scripts, but is referenced
100 from the manifest file of <em>bootstrap.jar</em>.</p></li>
101 </ul>
102 </li>
103<li><p><strong>Common</strong> &mdash; This class loader contains additional
104 classes that are made visible to both Tomcat internal classes and to all
105 web applications.</p>
106 <p>Normally, application classes should <strong>NOT</strong>
107 be placed here. The locations searched by this class loader are defined by
108 the <code>common.loader</code> property in
109 $CATALINA_BASE/conf/catalina.properties. The default setting will search the
110 following locations in the order they are listed:</p>
111 <ul>
112 <li>unpacked classes and resources in <code>$CATALINA_BASE/lib</code></li>
113 <li>JAR files in <code>$CATALINA_BASE/lib</code></li>
114 <li>unpacked classes and resources in <code>$CATALINA_HOME/lib</code></li>
115 <li>JAR files in <code>$CATALINA_HOME/lib</code></li>
116 </ul>
117 <p>By default, this includes the following:</p>
118 <ul>
119 <li><em>annotations-api.jar</em> &mdash; JavaEE annotations classes.</li>
120 <li><em>catalina.jar</em> &mdash; Implementation of the Catalina servlet
121 container portion of Tomcat.</li>
122 <li><em>catalina-ant.jar</em> &mdash; Tomcat Catalina Ant tasks.</li>
123 <li><em>catalina-ha.jar</em> &mdash; High availability package.</li>
124 <li><em>catalina-tribes.jar</em> &mdash; Group communication package.</li>
125 <li><em>ecj-*.jar</em> &mdash; Eclipse JDT Java compiler.</li>
126 <li><em>el-api.jar</em> &mdash; EL 2.2 API.</li>
127 <li><em>jasper.jar</em> &mdash; Tomcat Jasper JSP Compiler and Runtime.</li>
128 <li><em>jasper-el.jar</em> &mdash; Tomcat Jasper EL implementation.</li>
129 <li><em>jsp-api.jar</em> &mdash; JSP 2.2 API.</li>
130 <li><em>servlet-api.jar</em> &mdash; Servlet 3.0 API.</li>
131 <li><em>tomcat-api.jar</em> &mdash; Several interfaces defined by Tomcat.</li>
132 <li><em>tomcat-coyote.jar</em> &mdash; Tomcat connectors and utility classes.</li>
133 <li><em>tomcat-dbcp.jar</em> &mdash; Database connection pool
134 implementation based on package-renamed copy of Apache Commons Pool
135 and Apache Commons DBCP.</li>
136 <li><em>tomcat-i18n-**.jar</em> &mdash; Optional JARs containing resource bundles
137 for other languages. As default bundles are also included in each
138 individual JAR, they can be safely removed if no internationalization
139 of messages is needed.</li>
140 <li><em>tomcat-jdbc.jar</em> &mdash; An alternative database connection pool
141 implementation, known as Tomcat JDBC pool. See
142 <a href="jdbc-pool.html">documentation</a> for more details.</li>
143 <li><em>tomcat-util.jar</em> &mdash; Common classes used by various components of
144 Apache Tomcat.</li>
145 </ul></li>
146<li><p><strong>WebappX</strong> &mdash; A class loader is created for each web
147 application that is deployed in a single Tomcat instance. All unpacked
148 classes and resources in the <code>/WEB-INF/classes</code> directory of
149 your web application, plus classes and resources in JAR files
150 under the <code>/WEB-INF/lib</code> directory of your web application,
151 are made visible to this web application, but not to other ones.</p></li>
152</ul>
153
154<p>As mentioned above, the web application class loader diverges from the
155default Java delegation model (in accordance with the recommendations in the
156Servlet Specification, version 2.4, section 9.7.2 Web Application Classloader).
157When a request to load a
158class from the web application's <em>WebappX</em> class loader is processed,
159this class loader will look in the local repositories <strong>first</strong>,
160instead of delegating before looking. There are exceptions. Classes which are
161part of the JRE base classes cannot be overridden. For some classes (such as
162the XML parser components in J2SE 1.4+), the J2SE 1.4 endorsed feature can be
163used.
164Last, any JAR file that contains Servlet API classes will be explicitly
165ignored by the classloader &mdash; Do not include such JARs in your web
166application.
167All other class loaders in Tomcat follow the usual delegation pattern.</p>
168
169<p>Therefore, from the perspective of a web application, class or resource
170loading looks in the following repositories, in this order:</p>
171<ul>
172<li>Bootstrap classes of your JVM</li>
173<li>System class loader classes (described above)</li>
174<li><em>/WEB-INF/classes</em> of your web application</li>
175<li><em>/WEB-INF/lib/*.jar</em> of your web application</li>
176<li>Common class loader classes (described above)</li>
177</ul>
178
179</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="XML Parsers and Java"><!--()--></a><a name="XML_Parsers_and_Java"><strong>XML Parsers and Java</strong></a></font></td></tr><tr><td><blockquote>
180
181<p>Starting with Java 1.4 a copy of JAXP APIs and an XML parser are packed
182inside the JRE. This has impacts on applications that wish to use their own
183XML parser.</p>
184
185<p>In old versions of Tomcat, you could simply replace the XML parser
186in the Tomcat libraries directory to change the parser
187used by all web applications. However, this technique will not be effective
188when you are running modern versions of Java, because the usual class loader
189delegation process will always choose the implementation inside the JDK in
190preference to this one.</p>
191
192<p>Java supports a mechanism called the "Endorsed Standards Override
193Mechanism" to allow replacement of APIs created outside of the JCP
194(i.e. DOM and SAX from W3C). It can also be used to update the XML parser
195implementation. For more information, see:
196<a href="http://docs.oracle.com/javase/1.5.0/docs/guide/standards/index.html">
197http://docs.oracle.com/javase/1.5.0/docs/guide/standards/index.html</a>.</p>
198
199<p>Tomcat utilizes this mechanism by including the system property setting
200<code>-Djava.endorsed.dirs=$JAVA_ENDORSED_DIRS</code> in the
201command line that starts the container. The default value of this option is
202<em>$CATALINA_HOME/endorsed</em>. This <em>endorsed</em> directory is not
203created by default.</p>
204
205</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Running under a security manager"><!--()--></a><a name="Running_under_a_security_manager"><strong>Running under a security manager</strong></a></font></td></tr><tr><td><blockquote>
206
207<p>When running under a security manager the locations from which classes
208are permitted to be loaded will also depend on the contents of your policy
209file. See <a href="security-manager-howto.html">Security Manager HOW-TO</a>
210for further information.</p>
211
212</blockquote></td></tr></table></td></tr><tr class="noPrint"><td width="20%" valign="top" nowrap class="noPrint"></td><td width="80%" valign="top" align="left"><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="comments_section" id="comments_section"><strong>Comments</strong></a></font></td></tr><tr><td><blockquote><p class="notice"><strong>Notice: </strong>This comments section collects your suggestions
213 on improving documentation for Apache Tomcat.<br><br>
214 If you have trouble and need help, read
215 <a href="http://tomcat.apache.org/findhelp.html">Find Help</a> page
216 and ask your question on the tomcat-users
217 <a href="http://tomcat.apache.org/lists.html">mailing list</a>.
218 Do not ask such questions here. This is not a Q&amp;A section.<br><br>
219 The Apache Comments System is explained <a href="/tomcat-7.0-doc/comments.html">here</a>.
220 Comments may be removed by our moderators if they are either
221 implemented or considered invalid/off-topic.</p><script type="text/javascript"><!--//--><![CDATA[//><!--
222 var comments_shortname = 'tomcat';
223 var comments_identifier = 'http://tomcat.apache.org/tomcat-7.0-doc/class-loader-howto.html';
224 (function(w, d) {
225 if (w.location.hostname.toLowerCase() == "tomcat.apache.org") {
226 d.write('<div id="comments_thread"><\/div>');
227 var s = d.createElement('script');
228 s.type = 'text/javascript';
229 s.async = true;
230 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
231 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
232 }
233 else {
234 d.write('<div id="comments_thread"><strong>Comments are disabled for this page at the moment.<\/strong><\/div>');
235 }
236 })(window, document);
237 //--><!]]></script></blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
238 Copyright &copy; 1999-2013, Apache Software Foundation
239 </em></font></div></td></tr></table></body></html>