| 1 | <html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 6.0 - Class Loader HOW-TO</title><meta value="Craig R. McClanahan" name="author"><meta value="craigmcc@apache.org" name="email"><meta value="Yoav Shapira" name="author"><meta value="yoavs@apache.org" name="email"></head><body vlink="#525D76" alink="#525D76" link="#525D76" text="#000000" bgcolor="#ffffff"><table cellspacing="0" width="100%" border="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img border="0" alt=" |
|---|
| 2 | The Apache Tomcat Servlet/JSP Container |
|---|
| 3 | " align="right" src="./../images/tomcat.gif"></a></td><td><font face="arial,helvetica,sanserif"><h1>Apache Tomcat 6.0</h1></font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img border="0" alt="Apache Logo" align="right" src="./../images/asf-logo.gif"></a></td></tr></table><table cellspacing="4" width="100%" border="0"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><tr><!--RIGHT SIDE MAIN BODY--><td align="left" valign="top" width="80%"><table cellspacing="4" width="100%" border="0"><tr><td valign="top" align="left"><h1>Apache Tomcat 6.0</h1><h2>Class Loader HOW-TO</h2></td><td nowrap="true" valign="top" align="right"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Overview"><strong>Overview</strong></a></font></td></tr><tr><td><blockquote> |
|---|
| 4 | |
|---|
| 5 | <p>Like many server applications, Tomcat 6 installs a variety of class loaders |
|---|
| 6 | (that is, classes that implement <code>java.lang.ClassLoader</code>) to allow |
|---|
| 7 | different portions of the container, and the web applications running on the |
|---|
| 8 | container, to have access to different repositories of available classes and |
|---|
| 9 | resources. This mechanism is used to provide the functionality defined in the |
|---|
| 10 | Servlet Specification, version 2.4 -- in particular, Sections 9.4 and 9.6.</p> |
|---|
| 11 | |
|---|
| 12 | <p>In a J2SE 2 (that is, J2SE 1.2 or later) environment, class loaders are |
|---|
| 13 | arranged in a parent-child tree. Normally, when a class loader is asked to |
|---|
| 14 | load a particular class or resource, it delegates the request to a parent |
|---|
| 15 | class loader first, and then looks in its own repositories only if the parent |
|---|
| 16 | class loader(s) cannot find the requested class or resource. The model for |
|---|
| 17 | web application class loaders differs slightly from this, as discussed below, |
|---|
| 18 | but the main principles are the same.</p> |
|---|
| 19 | |
|---|
| 20 | <p>When Tomcat 6 is started, it creates a set of class loaders that are |
|---|
| 21 | organized into the following parent-child relationships, where the parent |
|---|
| 22 | class loader is above the child class loader:</p> |
|---|
| 23 | |
|---|
| 24 | <div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> |
|---|
| 25 | Bootstrap |
|---|
| 26 | | |
|---|
| 27 | System |
|---|
| 28 | | |
|---|
| 29 | Common |
|---|
| 30 | / \ |
|---|
| 31 | Webapp1 Webapp2 ... |
|---|
| 32 | </pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div> |
|---|
| 33 | |
|---|
| 34 | <p>The characteristics of each of these class loaders, including the source |
|---|
| 35 | of classes and resources that they make visible, are discussed in detail in |
|---|
| 36 | the following section.</p> |
|---|
| 37 | |
|---|
| 38 | </blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Class Loader Definitions"><strong>Class Loader Definitions</strong></a></font></td></tr><tr><td><blockquote> |
|---|
| 39 | |
|---|
| 40 | <p>As indicated in the diagram above, Tomcat 6 creates the following class |
|---|
| 41 | loaders as it is initialized:</p> |
|---|
| 42 | <ul> |
|---|
| 43 | <li><strong>Bootstrap</strong> - This class loader contains the basic runtime |
|---|
| 44 | classes provided by the Java Virtual Machine, plus any classes from JAR |
|---|
| 45 | files present in the System Extensions directory |
|---|
| 46 | (<code>$JAVA_HOME/jre/lib/ext</code>). <em>NOTE</em> - Some JVMs may |
|---|
| 47 | implement this as more than one class loader, or it may not be visible |
|---|
| 48 | (as a class loader) at all.</li> |
|---|
| 49 | <li><strong>System</strong> - This class loader is normally initialized from |
|---|
| 50 | the contents of the <code>CLASSPATH</code> environment variable. All such |
|---|
| 51 | classes are visible to both Tomcat internal classes, and to web |
|---|
| 52 | applications. However, the standard Tomcat 6 startup scripts |
|---|
| 53 | (<code>$CATALINA_HOME/bin/catalina.sh</code> or |
|---|
| 54 | <code>%CATALINA_HOME%\bin\catalina.bat</code>) totally ignore the contents |
|---|
| 55 | of the <code>CLASSPATH</code> environment variable itself, and instead |
|---|
| 56 | build the System class loader from the following repositories: |
|---|
| 57 | <ul> |
|---|
| 58 | <li><em>$CATALINA_HOME/bin/bootstrap.jar</em> - Contains the main() method |
|---|
| 59 | that is used to initialize the Tomcat 6 server, and the class loader |
|---|
| 60 | implementation classes it depends on.</li> |
|---|
| 61 | <li><em>$CATALINA_HOME/bin/tomcat-juli.jar</em> - Package renamed Jakarta commons |
|---|
| 62 | logging API, and java.util.logging LogManager.</li> |
|---|
| 63 | </ul></li> |
|---|
| 64 | <li><strong>Common</strong> - This class loader contains additional classes |
|---|
| 65 | that are made visible to both Tomcat internal classes and to all web |
|---|
| 66 | applications. Normally, application classes should <strong>NOT</strong> |
|---|
| 67 | be placed here. All unpacked classes and resources in |
|---|
| 68 | <code>$CATALINA_HOME/lib</code>, as well as classes and |
|---|
| 69 | resources in JAR files are made visible through this |
|---|
| 70 | class loader. By default, that includes the following: |
|---|
| 71 | <ul> |
|---|
| 72 | <li><em>annotations-api.jar</em> - JEE annotations classes.</li> |
|---|
| 73 | <li><em>catalina.jar</em> - Implementation of the Catalina servlet |
|---|
| 74 | container portion of Tomcat 6.</li> |
|---|
| 75 | <li><em>catalina-ant.jar</em> - Tomcat Catalina Ant tasks.</li> |
|---|
| 76 | <li><em>catalina-ha.jar</em> - High availability package.</li> |
|---|
| 77 | <li><em>catalina-tribes.jar</em> - Group communication package.</li> |
|---|
| 78 | <li><em>el-api.jar</em> - EL 2.1 API.</li> |
|---|
| 79 | <li><em>jasper.jar</em> - Jasper 2 Compiler and Runtime.</li> |
|---|
| 80 | <li><em>jasper-el.jar</em> - Jasper 2 EL implementation.</li> |
|---|
| 81 | <li><em>jasper-jdt.jar</em> - Eclipse JDT 3.2 Java compiler.</li> |
|---|
| 82 | <li><em>jsp-api.jar</em> - JSP 2.1 API.</li> |
|---|
| 83 | <li><em>servlet-api.jar</em> - Servlet 2.5 API.</li> |
|---|
| 84 | <li><em>tomcat-coyote.jar</em> - Tomcat connectors and utility classes.</li> |
|---|
| 85 | <li><em>tomcat-dbcp.jar</em> - package renamed database connection |
|---|
| 86 | pool based on Commons DBCP.</li> |
|---|
| 87 | <li><em>tomcat-i18n-**.jar</em> - Optional JARs containing resource bundles |
|---|
| 88 | for other languages. As default bundles are also included in each |
|---|
| 89 | individual JAR, they can be safely removed if no internationalization |
|---|
| 90 | of messages is needed.</li> |
|---|
| 91 | </ul></li> |
|---|
| 92 | <li><strong>WebappX</strong> - A class loader is created for each web |
|---|
| 93 | application that is deployed in a single Tomcat 6 instance. All unpacked |
|---|
| 94 | classes and resources in the <code>/WEB-INF/classes</code> directory of |
|---|
| 95 | your web application archive, plus classes and resources in JAR files |
|---|
| 96 | under the <code>/WEB-INF/lib</code> directory of your web application |
|---|
| 97 | archive, are made visible to the containing web application, but to |
|---|
| 98 | no others.</li> |
|---|
| 99 | </ul> |
|---|
| 100 | |
|---|
| 101 | <p>As mentioned above, the web application class loader diverges from the |
|---|
| 102 | default Java 2 delegation model (in accordance with the recommendations in the |
|---|
| 103 | Servlet Specification, version 2.3, section 9.7.2 Web Application Classloader). |
|---|
| 104 | When a request to load a |
|---|
| 105 | class from the web application's <em>WebappX</em> class loader is processed, |
|---|
| 106 | this class loader will look in the local repositories <strong>first</strong>, |
|---|
| 107 | instead of delegating before looking. There are exceptions. Classes which are |
|---|
| 108 | part of the JRE base classes cannot be overriden. For some classes (such as |
|---|
| 109 | the XML parser components in J2SE 1.4+), the J2SE 1.4 endorsed feature can be |
|---|
| 110 | used. |
|---|
| 111 | Last, any JAR containing servlet API classes will be ignored by the |
|---|
| 112 | classloader. |
|---|
| 113 | All other class loaders in Tomcat 6 follow the usual delegation pattern.</p> |
|---|
| 114 | |
|---|
| 115 | <p>Therefore, from the perspective of a web application, class or resource |
|---|
| 116 | loading looks in the following repositories, in this order:</p> |
|---|
| 117 | <ul> |
|---|
| 118 | <li>Bootstrap classes of your JVM</li> |
|---|
| 119 | <li>System class loader classses (described above)</li> |
|---|
| 120 | <li><em>/WEB-INF/classes</em> of your web application</li> |
|---|
| 121 | <li><em>/WEB-INF/lib/*.jar</em> of your web application</li> |
|---|
| 122 | <li><em>$CATALINA_HOME/lib</em></li> |
|---|
| 123 | <li><em>$CATALINA_HOME/lib/*.jar</em></li> |
|---|
| 124 | </ul> |
|---|
| 125 | |
|---|
| 126 | </blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="XML Parsers and JSE 5"><strong>XML Parsers and JSE 5</strong></a></font></td></tr><tr><td><blockquote> |
|---|
| 127 | |
|---|
| 128 | <p>Among many other changes, the JSE 5 release packages the JAXP APIs, and |
|---|
| 129 | a version of Xerces, inside the JRE. This has impacts on applications that |
|---|
| 130 | wish to use their own XML parser.</p> |
|---|
| 131 | |
|---|
| 132 | <p>In previous versions of Tomcat, you could simply replace the XML parser |
|---|
| 133 | in the <code>$CATALINA_HOME/common/lib</code> directory to change the parser |
|---|
| 134 | used by all web applications. However, this technique will not be effective |
|---|
| 135 | when you are running on JSE 5, because the usual class loader delegation |
|---|
| 136 | process will always choose the implementation inside the JDK in preference |
|---|
| 137 | to this one.</p> |
|---|
| 138 | |
|---|
| 139 | <p>JDK 1.5 supports a mechanism called the "Endorsed Standards Override |
|---|
| 140 | Mechanism" to allow replacement of APIs created outside of the JCP (i.e. |
|---|
| 141 | DOM and SAX from W3C). It can also be used to update the XML parser |
|---|
| 142 | implementation. For more information, see: |
|---|
| 143 | <a href="http://java.sun.com/j2se/1.5/docs/guide/standards/index.html"> |
|---|
| 144 | http://java.sun.com/j2se/1.5/docs/guide/standards/index.html</a>.</p> |
|---|
| 145 | |
|---|
| 146 | <p>Tomcat utilizes this mechanism by including the system property setting |
|---|
| 147 | <code>-Djava.endorsed.dirs=$JAVA_ENDORSED_DIRS</code> in the |
|---|
| 148 | command line that starts the container.</p> |
|---|
| 149 | |
|---|
| 150 | </blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Running under a security manager"><strong>Running under a security manager</strong></a></font></td></tr><tr><td><blockquote> |
|---|
| 151 | |
|---|
| 152 | <p>When running under a security manager the locations from which classes |
|---|
| 153 | are permitted to be loaded will also depend on the contents of your policy |
|---|
| 154 | file. See <a href="security-manager-howto.html">Security Manager HOW-TO</a> |
|---|
| 155 | for further information.</p> |
|---|
| 156 | |
|---|
| 157 | </blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font size="-1" color="#525D76"><em> |
|---|
| 158 | Copyright © 1999-2008, Apache Software Foundation |
|---|
| 159 | </em></font></div></td></tr></table></body></html> |
|---|
