You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by cr...@apache.org on 2001/09/04 06:39:05 UTC
cvs commit: jakarta-tomcat-4.0/webapps/tomcat-docs class-loader-howto.xml index.xml project.xml
craigmcc 01/09/03 21:39:05
Modified: webapps/tomcat-docs index.xml project.xml
Added: webapps/tomcat-docs class-loader-howto.xml
Log:
Convert documentation on the use of class loaders in Tomcat 4 into the new
documentation format.
Revision Changes Path
1.10 +3 -0 jakarta-tomcat-4.0/webapps/tomcat-docs/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/tomcat-docs/index.xml,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- index.xml 2001/08/21 02:28:21 1.9
+++ index.xml 2001/09/04 04:39:04 1.10
@@ -62,6 +62,9 @@
- Reference manual that documents all available elements and attributes
that may be placed into a Tomcat 4 <code>conf/server.xml</code> file.
</li>
+<li><a href="class-loader-howto.html"><strong>Class Loader HOW-TO</strong></a>
+ - Information about class loading in Tomcat 4, including where to place
+ your application classes so that they are visible.</li>
<li><a href="manager-howto.html"><strong>Manager App HOW-TO</strong></a> -
Operating the <code>Manager</code> web app to deploy, undeploy, and
redeploy applications while Tomcat is running.</li>
1.10 +1 -0 jakarta-tomcat-4.0/webapps/tomcat-docs/project.xml
Index: project.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/tomcat-docs/project.xml,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- project.xml 2001/08/21 02:28:21 1.9
+++ project.xml 2001/09/04 04:39:04 1.10
@@ -24,6 +24,7 @@
<menu name="Administrators">
<item name="Config. Reference" href="config/index.html"/>
+ <item name="Class Loader HOW-TO" href="class-loader-howto.html"/>
<item name="Manager App HOW-TO" href="manager-howto.html"/>
<item name="Proxy Support HOW-TO" href="proxy-howto.html"/>
<item name="SSL Config HOW-TO" href="ssl-howto.html"/>
1.1 jakarta-tomcat-4.0/webapps/tomcat-docs/class-loader-howto.xml
Index: class-loader-howto.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document>
&project;
<properties>
<author email="craigmcc@apache.org">Craig R. McClanahan</author>
<title>Class Loader INFO</title>
</properties>
<body>
<section name="Quick Start">
<p>The following rules cover about 95% of the decisions that application
developers and deployers must make about where to place class and resource
files to make them available to web applications:</p>
<ul>
<li>For classes and resources specific to a particular web application,
place unpacked classes and resources under <code>/WEB-INF/classe</code>
of your web application archive, or place JAR files containing those
classes and resources under <code>/WEB-INF/lib</code> of your web
application archive.</li>
<li>For classes and resources that must be shared across all web applications,
place unpacked classes and resources under
<code>$CATALINA_HOME/classes</code>, or place JAR files containing those
classes and resources under <code>$CATALINA_HOME/lib</code>.</li>
</ul>
<p><strong>WARNING</strong> - Unlike Tomcat 3.x, Tomcat 4 does
<strong>NOT</strong> make an XML parser visible to web applications by default.
If you need to do this, see <a href="#Tomcat 4 and XML Parsers">Tomcat 4 and
XML Parsers</a>, below.</p>
</section>
<section name="Overview">
<p>Like many server applications, Tomcat 4 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.3 -- in particular, Sections 9.4 and 9.6.</p>
<p>In a Java 2 (that is, JDK 1.2 or later) 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>
<p>When Tomcat 4 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>
<source>
Bootstrap
|
System
|
Common
/ \
Catalina Shared
/ \
Webapp1 Webapp2 ...
/ /
Jasper1 Jasper2 ...
</source>
<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>
</section>
<section name="Class Loader Definitions">
<p>As indicated in the diagram above, Tomcat 4 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
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 4 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:
<ul>
<li><em>$CATALINA_HOME/lib/bootstrap.jar</em> - Contains the main() method
that is used to initialize the Tomcat 4 server, and the class loader
implementation classes it depends on.</li>
<li><em>$JAVA_HOME/lib/tools.jar</em> - Contains the "javac" compiler used
to convert JSP pages into servlet classes.</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/common/classes</code>, as well as classes and
resources in JAR files under
<code>$CATALINA_HOME/common/lib</code>, are made visible through this
class loader. By default, that includes the following:
<ul>
<li><em>jndi.jar</em> - The Java Naming and Directory Interface API
classes (loaded <strong>ONLY</strong> on a JDK 1.2 system, because they
are included automatically on JDK 1.3 and later).</li>
<li><em>naming.jar</em> - The JNDI implementation used by Tomcat 4 to
represent the default JNDI naming context provided to web
applications.</li>
<li><em>resources.jar</em> - Resource factory classes for the JNDI naming
context that is used internally to represent the static resources of
a web application.</li>
<li><em>servlet.jar</em> - The Servlet and JSP API classes.</li>
</ul></li>
<li><strong>Catalina</strong> - This class loader is initialized to include
all classes and resources required to implement Tomcat 4 itself. These
classes and resources are <strong>TOTALLY</strong> invisible to web
applications. All unpacked classes and resources in
<code>$CATALINA_HOME/server/classes</code>, as well as classes and
resources in JAR files under
<code>$CATALINA_HOME/server/lib</code>, are made visible through
this class loader. By default, that includes the following:
<ul>
<li><em>catalina.jar</em> - Implementation of the Catalina servlet
container portion of Tomcat 4.</li>
<li><em>crimson.jar</em> - Parser portion of the JAXP/1.1 reference
implementation, used to parse web application deployment descriptor
(<code>web.xml</code>) files, as well as the server configuration file
(<code>$CATALINA_HOME/conf/server.xml</code>).</li>
<li><em>jakarta-regexp-X.Y.jar</em> - The binary distribution of the
<a href="http://jakarta.apache.org/regexp/">Jakarta Regexp</a>
regular expression processing library, used in the implementation of
request filters.</li>
<li><em>jaxp.jar</em> - JAXP API portion of the JAXP/1.1 reference
implementation, used to parse web application deployment descriptor
(<code>web.xml</code>) files, as well as the server configuration file
(<code>$CATALINA_HOME/conf/server.xml</code>).</li>
<li><em>warp.jar</em> - Classes for the Java portion of the
<code>mod_webapp</code> web server connector, which allows Tomcat to
run behind web servers such as Apache and iPlanet iAS and iWS.</li>
</ul></li>
<li><strong>Shared</strong> - This class loader is the place to put classes
and resources that you wish to share across <strong>ALL</strong>
web applications (unless Tomcat internal classes also need access, which
is an unusual case). All unpacked classes and resources in
<code>$CATALINA_HOME/classes</code>, as well as classes and resources
in JAR files under <code>$CATALINA_HOME/lib</code>, are made visible
through this class loader. By default, that includes the following:
<ul>
<li><em>jasper-runtime.jar</em> - The runtime support classes required
to execute JSP pages that have already been translated into Java
servlets and then compiled.</li>
<li><em>namingfactory.jar</em> - JNDI object factories for resources
supported by the default JNDI naming context provided to web
applications.</li>
</ul></li>
<li><strong>WebappX</strong> - A class loader is created for each web
application that is deployed in a single Tomcat 4 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>
<li><strong>JasperX</strong> - If your web application uses JSP pages, Tomcat
also creates an additional class loader for the web application,
containing the JSP compiler and classes it depends on. It is initialized
to include all JAR files found in <code>$CATALINA_HOME/jasper</code>.
Because this is a child class loader of the web application class loader,
the Jasper compiler (and the pages that it compiles) can see all of the
application bean classes visible in the <code>Webapp</code> class loader.
</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.6). 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. All other class loaders in Tomcat 4
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><em>/WEB-INF/classes</em> of your web application</li>
<li><em>/WEB-INF/lib/*.jar</em> of your web application</li>
<li>Bootstrap classes of your JVM</li>
<li>System class loader classses (described above)</li>
<li><em>$CATALINA_HOME/common/classes</em></li>
<li><em>$CATALINA_HOME/common/*.jar</em></li>
<li><em>$CATALINA_HOME/classes</em></li>
<li><em>$CATALINA_HOME/lib/*.jar</em></li>
</ul>
</section>
<section name="Tomcat 4 and XML Parsers">
<p>Tomcat 4 itself utilizes XML parsing for three processing activities:</p>
<ul>
<li>Parsing the <code>server.xml</code> configuration file</li>
<li>Parsing <code>web.xml</code> deployment descriptors</li>
<li>Parsing JSP pages in XML syntax</li>
</ul>
<p>By default, the Java API for XML Processing (Version 1.1) reference
implementation is utilized for all of these purposes. However, this parser
is <strong>not</strong> visible to web applications -- instead, the XML
parser stored in <code>$CATALINA_HOME/server/lib</code> is used for parsing
<code>web.xml</code> and <code>server.xml</code> files, while the parser
stored in <code>$CATALINA_HOME/jasper</code> is used for parsing JSP pages
in XML syntax.</p>
<p>To make an XML parser available to your web applications, you have several
options:</p>
<ul>
<li>To utilize an XML parser in a single web application, simply include the
parser's JAR files in the <code>/WEB-INF/web.xml</code> directory of that
web application. This will work, no matter what parser might be used by
Tomcat 4 internally, or by other web applications running in the same
instance of Tomcat 4.</li>
<li>If you wish to make the JAXP/1.1 reference implementation parser available
to all web applications, simply move the "jaxp.jar" and "crimson.jar" files
from the <code>$CATALINA_HOME/jasper</code> directory into the
<code>$CATALINA_HOME/lib</code> directory. Jasper will continue to use
this parser for processing JSP pages in XML syntax.</li>
<li>If you wish to make another XML parser that is JAXP/1.1 compatible
(such as Xerces 1.3.1 or later), install that parser's JAR files into the
<code>$CATALINA_HOME/lib</code> directory, and remove "jaxp.jar" and
"crimson.jar" from the <code>$CATALINA_HOME/jasper</code> directory.
Jasper will then utilize the new XML parser as well.</li>
</ul>
<p><strong>WARNING</strong> - Do not attempt to use a JAXP/1.0 (rather than
JAXP/1.1) compliant parser with Tomcat 4. Tomcat relies on the extra features
that were added in JAXP/1.1 to perform its parsing activities.</p>
<p><strong>WARNING</strong> - The final release of the JAXP/1.1 reference
implementation includes JAR files with the <code>sealed</code> attribute.
This causes class loading problems (most commonly visible through "package
sealing violation" exceptions) on JDK 1.3 and later platforms. To avoid
these problems, <em>modified</em> versions of "jaxp.jar" and "crimson.jar"
are shipped with Tomcat 4. You must <strong>NOT</strong> replace these files
with standard JAXP/1.1 JAR files, until a subsequent JAXP release occurs that
has the "sealed" attribute removed.</p>
</section>
</body>
</document>