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...@locus.apache.org on 2000/09/30 22:51:37 UTC
cvs commit: jakarta-tomcat-4.0/catalina/docs/dev classloaders.html architecture.html
craigmcc 00/09/30 13:51:37
Modified: catalina/docs/dev architecture.html
Added: catalina/docs/dev classloaders.html
Log:
Add a new Catalina developer doc that describes how class loaders are
configured and used within Catalina.
Revision Changes Path
1.2 +2 -2 jakarta-tomcat-4.0/catalina/docs/dev/architecture.html
Index: architecture.html
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/catalina/docs/dev/architecture.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- architecture.html 2000/08/30 22:32:07 1.1
+++ architecture.html 2000/09/30 20:51:36 1.2
@@ -3,13 +3,13 @@
<title>Architecture of Catalina</title>
</head>
-<body bgcolor="white>
+<body bgcolor="white">
TODO ...
<br>
<div align="center"><hr width="75%"><font size="2">
-$Id: architecture.html,v 1.1 2000/08/30 22:32:07 craigmcc Exp $
+$Id: architecture.html,v 1.2 2000/09/30 20:51:36 craigmcc Exp $
</font></div>
</body>
1.1 jakarta-tomcat-4.0/catalina/docs/dev/classloaders.html
Index: classloaders.html
===================================================================
<html>
<head>
<title>Catalina Class Loader Hierarchy</title>
</head>
<body bgcolor="white">
<div align="center">
<h1>Catalina Class Loader Hierarchy</h1>
<br>
<a href="#Introduction">[Introduction]</a>
<a href="#Overview">[Overview]</a>
<a href="#Process">[Process]</a>
<a href="#Notes">[Notes]</a>
<br><br>
</div>
<a name="Introduction"></a>
<h3>Introduction</h3>
<p>Like many server applications, Catalina installs a variety of class loaders
(that is, classes that extend <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 API Specification, version 2.3 (public draft 1) -- in particular
sections 9.4 and 9.6.</p>
<p>The remainder of this document provides an overview diagram of the
parent - child relationships between each class loader that is created, more
detailed information about the content and use of each class loader, and
some additional relevant notes.</p>
<a name="Overview"></a>
<h3>Overview Diagram</h3>
<p>In a Java2 environment, class loaders are arranged in a parentage tree.
Normally, when a class loader is asked to load a class (or get a resource),
it delegates the request upwards first, and only searches its local
repositories if the parent class loader(s) cannot find the requested class
or resource. The model for web applications differs slightly from this, as
discussed further below.</p>
<p>The class loaders that Catalina uses are organized as follows, where
the parent class loader is above the child class loaders:</p>
<pre>
Bootstrap
|
System
/ \
Catalina Shared
/ \
Webapp1 Webapp2 ...
</pre>
<p>The usage of and repositories contained in each class loader are
described further below:</p>
<ul>
<li><strong>Bootstrap</strong> - This class loader contains the basic
runtime classes provided by the Java Virtual Machine, such as the
<code>java.*</code> classes. Depending on how your particular JVM
is organized, this may actually be more than one class loader, or
may not exist at all. It is generally not referenced directly.</li>
<li><strong>System</strong> - This class loader is initialized from the
contents of the <code>CLASSPATH</code> environment variable. The
standard Catalina startup scripts assemble the following repositories
for the system class path:
<ul>
<li><code>$CATALINA_HOME/bin/bootstrap.jar</code> - The Bootstrap class
that is used to initialize the Catalina server, and the class
loader implementation classes it depends on.</li>
<li><code>$CATALIA_HOME/bin/servlet.jar</code> - The Servlet and JSP
API classes, placed here so that they are shared between Catalina
and the web applications that run under it.</li>
<li><code>$JAVA_HOME/lib/tools.jar</code> - Contains the Javac
compiler used to compile the servlets generated from JSP pages.</li>
</ul>
<li><strong>Catalina</strong> - This class loader is initialized to include
all JAR files in the <code>$CATALINA_HOME/server</code> directory, which
should contain Catalina itself (i.e. all classes whose fully qualified
names begin with <code>org.apache.catalina.</code>), and any JAR files
that it depends on. Because these classes are loaded from a separate
class loader, which is not visible to the <em>Webapp</em> class loader,
they are <strong>not</strong> visible to web applications.</li>
<li><strong>Shared</strong> - This class loader is initialized to include
all JAR files in the <code>$CATALINA_HOME/lib</code> directory. All of
the classes in these repositories will be visible to all web applications,
so they may be used to share information between web apps
(<strong>NOTE</strong> - this behavior is specific to Tomcat 4.0, and
will not necessarily be portable to other containers.)</li>
<li><strong>Webapp</strong> - A class loader is created for each web
application that is installed in Catalina, and initialized to include the
<code>WEB-INF/classes</code> directory (if it exists), plus all JAR files
in the <code>WEB-INF/lib</code> directory, for this web app. Because of
the parentage hierarchy, web applications can indirectly see (and therefore
load classes from) the <em>Shared</em>, <em>System</em>, and
<em>Bootstrap</em> class loaders, but <strong>not</strong> from the
<em>Catalina</em> class loader.</li>
</ul>
<p>As you can see from the above descriptions, the contents of any
<code>CLASSPATH</code> environment variable already existing in your server
is totally ignored. If you want to make a JAR file available to all web
applications, you <strong>must</strong> place a copy of this file in the
<code>$CATALINA_HOME/lib</code> directory so that it becomes part of the
<em>Shared</em> class loader's repositories.</p>
<a name="Process"></a>
<h3>Web Application Class Loading Process</h3>
<p>When a servlet (or JSP page) within a web application references a class
for the first time (either by using the <code>new</code> operator or by
calling the <code>Class.forName()</code> method), the following processing
occurs to locate and load the requested class:</p>
<ol>
<li>The <code>loadClass()</code> method of the <em>Webapp</em> class loader
is called to load the specified class.</li>
<li>If the requested class has a prefix that is on the restricted list,
the class loader refuses to load the class at all. For the <em>Webapp</em>
class loader, the restricted list is configured to include
<code>org.apache.catalina.</code>, so that any attempt to load an internal
Catalina implementation class is refused (even if the web app developer
tries to put <code>catalina.jar</code> someplace visible to their app).
</li>
<li>If this class has been previously loaded by this class loader, the
cached copy is returned again. This avoids having to do potentially
expensive I/O every time a class is requested.</li>
<li>If the requested class has a prefix that is on the "system classes" list,
the <em>Webapp</em> class loader delegates to its parent (i.e. the
<em>Shared</em> class loader), in the usual Java2 delegation fashion.
For the <em>Webapp</em> class loader, the "system classes" list is
configured to include <code>java.</code> and <code>javax.servlet.</code>
so that you cannot override system or servlet API classes with your
own copies.</li>
<li>Local repositories (i.e. the contents of the <code>WEB-INF/classes</code>
directory, followed by the contents of JAR files found in the
<code>WEB-INF/lib</code> directory) are searched next. If the class is
found here, it is cached in memory, and returned.</li>
<li>Finally, responsibility for finding this class is delegated upward
to the parent class loader, who will either find the class itself (after
possibly delegating upwards to its own parent) or throw a
<code>ClassNotFoundException</code> if no class with this name can be
located anywhere in the class loader hierarchy visible to the web app.</li>
</ol>
<p>A similar pattern is followed when you call <code>Class.getResource()</code>
or <code>Class.getResourceAsStream()</code> to access resources that are
co-resident with your classes.</p>
<a name="Notes"></a>
<h3>Miscellaneous Notes</h3>
<h4>Class Loader Information Exposed For Web Applications</h4>
<p>Certain web application components (such as the Jasper JSP page compiler
servlet, require additional information related to class loading to operate
successfully. To avoid creating dependencies between the Jasper and Catalina
code bases, this information is exposed as a set of servlet context attributes
that are initialized when the web application is started. The following
context attributes are created:</p>
<ul>
<li><strong>org.apache.catalina.classloader</strong> - The <em>Webapp</em>
class loader for this application (which will also be the class loader used
to load the Jasper servlet itself).</li>
<li><strong>org.apache.catalina.jsp_classpath</strong> - A String
representation of the directories and JAR files available in the
<em>webapp</em>, <em>shared</em>, and <em>system</em> class loaders, with
each repository separated by the appropriate path separator character for
the platform this server is running on.</li>
</ul>
<h4>Additional Information</h4>
<p>For more information about class loaders in general, see the Java Language
Specification, and the Javadocs for the following classes:</p>
<ul>
<li><code>java.lang.ClassLoader</code>
<li><code>java.net.URLClassLoader</code>
</ul>
<p>The implementation class for all Catalina internal class loaders is
<code>StandardClassLoader</code>. Required and available optional packages
are described using the <code>Extension</code> class. For more information,
see the source code and/or Javadocs for the following classes:
<ul>
<li><code>org.apache.catalina.loader.StandardClassLoader</code>
<li><code>org.apache.catalina.loader.Extension</code>
</ul>
<br>
<div align="center"><hr width="75%"><font size="2">
$Id: classloaders.html,v 1.1 2000/09/30 20:51:37 craigmcc Exp $
</font></div>
</body>
</html>