You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by kk...@apache.org on 2011/07/29 21:49:59 UTC
svn commit: r1152352 - in /tomcat/trunk/webapps/docs: changelog.xml
class-loader-howto.xml
Author: kkolinko
Date: Fri Jul 29 19:49:58 2011
New Revision: 1152352
URL: http://svn.apache.org/viewvc?rev=1152352&view=rev
Log:
Improve class loading documentation
Review existing documentation. Rephrase and reformat some statements.
Documented $CATALINA_BASE/bin/tomcat-juli.jar.
Documented new JARs in $CATALINA_HOME/lib, that were not present in Tomcat 6.
More changes to this document are to follow.
Modified:
tomcat/trunk/webapps/docs/changelog.xml
tomcat/trunk/webapps/docs/class-loader-howto.xml
Modified: tomcat/trunk/webapps/docs/changelog.xml
URL: http://svn.apache.org/viewvc/tomcat/trunk/webapps/docs/changelog.xml?rev=1152352&r1=1152351&r2=1152352&view=diff
==============================================================================
--- tomcat/trunk/webapps/docs/changelog.xml (original)
+++ tomcat/trunk/webapps/docs/changelog.xml Fri Jul 29 19:49:58 2011
@@ -186,6 +186,9 @@
common class loader when separate values are used for $CATALINA_HOME and
$CATALINA_BASE. (markt)
</fix>
+ <update>
+ Improve class loading documentation. (kkolinko)
+ </update>
</changelog>
</subsection>
<subsection name="Other">
Modified: tomcat/trunk/webapps/docs/class-loader-howto.xml
URL: http://svn.apache.org/viewvc/tomcat/trunk/webapps/docs/class-loader-howto.xml?rev=1152352&r1=1152351&r2=1152352&view=diff
==============================================================================
--- tomcat/trunk/webapps/docs/class-loader-howto.xml (original)
+++ tomcat/trunk/webapps/docs/class-loader-howto.xml Fri Jul 29 19:49:58 2011
@@ -41,15 +41,16 @@
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>
+Servlet Specification, version 2.4 — in particular, Sections 9.4
+and 9.6.</p>
-<p>In a J2SE 2 (that is, J2SE 1.2 or later) environment, class loaders are
+<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. The model for
-web application class loaders differs slightly from this, as discussed below,
-but the main principles are the same.</p>
+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
@@ -76,83 +77,109 @@ the following section.</p>
<p>As indicated in the diagram above, Tomcat creates the following class
loaders as it is initialized:</p>
<ul>
-<li><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
+<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.</li>
-<li><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
+ (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><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.</li>
- <li><em>$CATALINA_HOME/bin/tomcat-juli.jar</em> - Package renamed Commons
- logging API, and java.util.logging LogManager.</li>
- </ul></li>
-<li><strong>Common</strong> - This class loader contains additional classes
- that are made visible to both Tomcat internal classes and to all web
- applications. Normally, application classes should <strong>NOT</strong>
+ <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:
+ 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>
- By default, this includes the following:
+ <p>By default, this includes the following:</p>
<ul>
- <li><em>annotations-api.jar</em> - JEE annotations classes.</li>
- <li><em>catalina.jar</em> - Implementation of the Catalina servlet
+ <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-tribes.jar</em> - Group communication package.</li>
- <li><em>el-api.jar</em> - EL 2.1 API.</li>
- <li><em>jasper.jar</em> - Jasper 2 Compiler and Runtime.</li>
- <li><em>jasper-el.jar</em> - Jasper 2 EL implementation.</li>
- <li><em>ecj-*.jar</em> - Eclipse JDT Java compiler.</li>
- <li><em>jsp-api.jar</em> - JSP 2.1 API.</li>
- <li><em>servlet-api.jar</em> - Servlet 3.0 API.</li>
- <li><em>tomcat-coyote.jar</em> - Tomcat connectors and utility classes.</li>
- <li><em>tomcat-dbcp.jar</em> - package renamed database connection
- pool based on Commons DBCP.</li>
- <li><em>tomcat-i18n-**.jar</em> - Optional JARs containing resource bundles
+ <li><em>catalina-ant.jar</em> — Tomcat Catalina Ant tasks.</li>
+ <li><em>catalina-ha.jar</em> — High availability package.</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 2.2 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.2 API.</li>
+ <li><em>servlet-api.jar</em> — Servlet 3.0 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>
</ul></li>
-<li><strong>WebappX</strong> - A class loader is created for each web
+<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 archive, plus classes and resources in JAR files
- under the <code>/WEB-INF/lib</code> directory of your web application
- archive, are made visible to the containing web application, but to
- no others.</li>
+ 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 2 delegation model (in accordance with the recommendations in the
-Servlet Specification, version 2.3, section 9.7.2 Web Application Classloader).
+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 overriden. For some classes (such as
+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.
-Last, any JAR containing servlet API classes will be ignored by the
-classloader.
+Last, any JAR file that contains Servlet API classes will be explicitly
+ignored by the classloader — Do not include such JARs in your web
+application.
All other class loaders in Tomcat follow the usual delegation pattern.</p>
<p>Therefore, from the perspective of a web application, class or resource
@@ -162,18 +189,17 @@ loading looks in the following repositor
<li>System 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>
-<li><em>$CATALINA_HOME/lib</em></li>
-<li><em>$CATALINA_HOME/lib/*.jar</em></li>
+<li>Common class loader classes (described above)</li>
</ul>
</section>
-<section name="XML Parsers and JSE 5">
+<section name="XML Parsers and JavaSE 5">
-<p>Among many other changes, the JSE 5 release packages the JAXP APIs, and
-a version of Xerces, inside the JRE. This has impacts on applications that
-wish to use their own XML parser.</p>
+<p>Among many other changes, the JavaSE 5 release packages the JAXP APIs, and
+a version of Apache Xerces, inside the JRE. This has impacts on applications
+that wish to use their own XML parser.</p>
<p>In previous versions of Tomcat, you could simply replace the XML parser
in the <code>$CATALINA_HOME/common/lib</code> directory to change the parser
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org