tomcat-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From kkoli...@apache.org
Subject svn commit: r1152466 - in /tomcat/tc6.0.x/trunk/webapps/docs: changelog.xml class-loader-howto.xml
Date Sat, 30 Jul 2011 14:06:34 GMT
Author: kkolinko
Date: Sat Jul 30 14:06:33 2011
New Revision: 1152466

URL: http://svn.apache.org/viewvc?rev=1152466&view=rev
Log:
Improve class loading documentation
Backport documentation changes from Tomcat 7.
CTR: Docs

- Changed formatting and rewrote some phrases
- Documented tomcat-juli.jar and commons-daemon.jar
- Documented the peculiarities of tomcat-juli.jar handling in TC6 (vs. TC7).
- Mention both CATALINA_HOME and CATALINA_BASE.
- Improve documentation about $CATALINA_HOME/endorsed.

Modified:
    tomcat/tc6.0.x/trunk/webapps/docs/changelog.xml
    tomcat/tc6.0.x/trunk/webapps/docs/class-loader-howto.xml

Modified: tomcat/tc6.0.x/trunk/webapps/docs/changelog.xml
URL: http://svn.apache.org/viewvc/tomcat/tc6.0.x/trunk/webapps/docs/changelog.xml?rev=1152466&r1=1152465&r2=1152466&view=diff
==============================================================================
--- tomcat/tc6.0.x/trunk/webapps/docs/changelog.xml (original)
+++ tomcat/tc6.0.x/trunk/webapps/docs/changelog.xml Sat Jul 30 14:06:33 2011
@@ -325,6 +325,9 @@
         system property name for changing the name of the SSO session cookie.
         (markt)
       </fix>
+      <update>
+        Improve class loading documentation. (kkolinko)
+      </update>
     </changelog>
   </subsection>
   <subsection name="Other">

Modified: tomcat/tc6.0.x/trunk/webapps/docs/class-loader-howto.xml
URL: http://svn.apache.org/viewvc/tomcat/tc6.0.x/trunk/webapps/docs/class-loader-howto.xml?rev=1152466&r1=1152465&r2=1152466&view=diff
==============================================================================
--- tomcat/tc6.0.x/trunk/webapps/docs/class-loader-howto.xml (original)
+++ tomcat/tc6.0.x/trunk/webapps/docs/class-loader-howto.xml Sat Jul 30 14:06:33 2011
@@ -36,22 +36,23 @@
 
 <section name="Overview">
 
-<p>Like many server applications, Tomcat 6 installs a variety of class loaders
+<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>
+Servlet Specification, version 2.4&#160;&#8212; 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 6 is started, it creates a set of class loaders that are
+<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>
 
@@ -76,67 +77,101 @@ the following section.</p>
 <p>As indicated in the diagram above, Tomcat 6 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> &#8212; 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
-    applications.  However, the standard Tomcat 6 startup scripts
+    (as a class loader) at all.</p></li>
+<li><p><strong>System</strong> &#8212; 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 6 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>
-    be placed here.  All unpacked classes and resources in
-    <code>$CATALINA_HOME/lib</code>, as well as classes and
-    resources in JAR files are made visible through this
-    class loader.  By default, that includes the following:
+    <li><p><em>$CATALINA_HOME/bin/bootstrap.jar</em> &#8212;
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> and
+        <em>$CATALINA_HOME/bin/tomcat-juli.jar</em> &#8212; 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></li>
+    <li><p><em>$CATALINA_HOME/bin/commons-daemon.jar</em> &#8212;
The classes
+        from <a href="http://commons.apache.org/daemon/">Apache Commons
+        Daemon</a> project.</p></li>
+    </ul>
+    <p>The <em>tomcat-juli.jar</em> and <em>commons-daemon.jar</em>
JARs in
+    <em>$CATALINA_HOME/bin</em> are not present in the <code>CLASSPATH</code>
+    built by <code>catalina.bat</code>|<code>.sh</code> scripts,
but are
+    referenced from the manifest file of <em>bootstrap.jar</em>.
+    </p>
+    <p>If <em>$CATALINA_BASE</em> and <em>$CATALINA_HOME</em>
do differ and
+    <em>$CATALINA_BASE/bin/tomcat-juli.jar</em> does exist, the startup scripts
+    will add it to <code>CLASSPATH</code> before <em>bootstrap.jar</em>,
so
+    that Java will look into <em>$CATALINA_BASE/bin/tomcat-juli.jar</em> for
+    classes before it will look into <em>$CATALINA_HOME/bin/tomcat-juli.jar</em>
+    referenced by <em>bootstrap.jar</em>. It should work in most cases but,
+    if you are using such configuration, it might be recommended to remove
+    <em>tomcat-juli.jar</em> from <em>$CATALINA_HOME/bin</em> so
that only
+    one copy of the file is present on the classpath. The next version of
+    Tomcat, Tomcat 7, takes different approach here.
+    </p></li>
+<li><p><strong>Common</strong> &#8212; 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> - JEE annotations classes.</li>
-    <li><em>catalina.jar</em> - Implementation of the Catalina servlet
-        container portion of Tomcat 6.</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 2.5 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>annotations-api.jar</em> &#8212; JavaEE annotations classes.</li>
+    <li><em>catalina.jar</em> &#8212; Implementation of the Catalina
servlet
+        container portion of Tomcat.</li>
+    <li><em>catalina-ant.jar</em> &#8212; Tomcat Catalina Ant tasks.</li>
+    <li><em>catalina-ha.jar</em> &#8212; High availability package.</li>
+    <li><em>catalina-tribes.jar</em> &#8212; Group communication package.</li>
+    <li><em>ecj-*.jar</em> &#8212; Eclipse JDT Java compiler.</li>
+    <li><em>el-api.jar</em> &#8212; EL 2.1 API.</li>
+    <li><em>jasper.jar</em> &#8212; Tomcat Jasper JSP Compiler and
Runtime.</li>
+    <li><em>jasper-el.jar</em> &#8212; Tomcat Jasper EL implementation.</li>
+    <li><em>jsp-api.jar</em> &#8212; JSP 2.1 API.</li>
+    <li><em>servlet-api.jar</em> &#8212; Servlet 2.5 API.</li>
+    <li><em>tomcat-coyote.jar</em> &#8212; Tomcat connectors and utility
classes.</li>
+    <li><em>tomcat-dbcp.jar</em> &#8212; Database connection pool
+        implementation based on package-renamed copy of Apache Commons Pool
+        and Apache Commons DBCP.</li>
+    <li><em>tomcat-i18n-**.jar</em> &#8212; 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>
     </ul></li>
-<li><strong>WebappX</strong> - A class loader is created for each web
-    application that is deployed in a single Tomcat 6 instance.  All unpacked
+<li><p><strong>WebappX</strong> &#8212; 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).  
+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>,
@@ -144,8 +179,9 @@ instead of delegating before looking.  T
 part of the JRE base classes cannot be overriden. 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 &#8212; Do not include such JARs in your web
+application.
 All other class loaders in Tomcat 6 follow the usual delegation pattern.</p>
 
 <p>Therefore, from the perspective of a web application, class or resource
@@ -155,36 +191,37 @@ 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 Java">
 
-<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>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 previous versions of Tomcat, you could simply replace the XML parser
-in the <code>$CATALINA_HOME/common/lib</code> directory to change the parser
+<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 on JSE 5, because the usual class loader delegation
-process will always choose the implementation inside the JDK in preference
-to this one.</p>
-
-<p>JDK 1.5 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
+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://java.sun.com/j2se/1.5/docs/guide/standards/index.html">
-http://java.sun.com/j2se/1.5/docs/guide/standards/index.html</a>.</p>
+<a href="http://download.oracle.com/javase/1.5.0/docs/guide/standards/index.html">
+http://download.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.</p>
+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>
 
 </section>
 



---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org


Mime
View raw message