Like many server applications, Catalina installs a variety of class loaders
(that is, classes that extend java.lang.ClassLoader
) 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.
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.
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.
The class loaders that Catalina uses are organized as follows, where the parent class loader is above the child class loaders:
Bootstrap | System / \ Catalina Shared / \ Webapp1 Webapp2 ...
The usage of and repositories contained in each class loader are described further below:
java.*
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.CLASSPATH
environment variable. The
standard Catalina startup scripts assemble the following repositories
for the system class path:
$CATALINA_HOME/bin/bootstrap.jar
- The Bootstrap class
that is used to initialize the Catalina server, and the class
loader implementation classes it depends on.$CATALIA_HOME/bin/servlet.jar
- The Servlet and JSP
API classes, placed here so that they are shared between Catalina
and the web applications that run under it.$JAVA_HOME/lib/tools.jar
- Contains the Javac
compiler used to compile the servlets generated from JSP pages.$CATALINA_HOME/server
directory, which
should contain Catalina itself (i.e. all classes whose fully qualified
names begin with org.apache.catalina.
), and any JAR files
that it depends on. Because these classes are loaded from a separate
class loader, which is not visible to the Webapp class loader,
they are not visible to web applications.$CATALINA_HOME/lib
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
(NOTE - this behavior is specific to Tomcat 4.0, and
will not necessarily be portable to other containers.)WEB-INF/classes
directory (if it exists), plus all JAR files
in the WEB-INF/lib
directory, for this web app. Because of
the parentage hierarchy, web applications can indirectly see (and therefore
load classes from) the Shared, System, and
Bootstrap class loaders, but not from the
Catalina class loader.As you can see from the above descriptions, the contents of any
CLASSPATH
environment variable already existing in your server
is totally ignored. If you want to make a JAR file available to all web
applications, you must place a copy of this file in the
$CATALINA_HOME/lib
directory so that it becomes part of the
Shared class loader's repositories.
When a servlet (or JSP page) within a web application references a class
for the first time (either by using the new
operator or by
calling the Class.forName()
method), the following processing
occurs to locate and load the requested class:
loadClass()
method of the Webapp class loader
is called to load the specified class.org.apache.catalina.
, so that any attempt to load an internal
Catalina implementation class is refused (even if the web app developer
tries to put catalina.jar
someplace visible to their app).
java.
and javax.servlet.
so that you cannot override system or servlet API classes with your
own copies.WEB-INF/classes
directory, followed by the contents of JAR files found in the
WEB-INF/lib
directory) are searched next. If the class is
found here, it is cached in memory, and returned.ClassNotFoundException
if no class with this name can be
located anywhere in the class loader hierarchy visible to the web app.A similar pattern is followed when you call Class.getResource()
or Class.getResourceAsStream()
to access resources that are
co-resident with your classes.
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:
For more information about class loaders in general, see the Java Language Specification, and the Javadocs for the following classes:
java.lang.ClassLoader
java.net.URLClassLoader
The implementation class for all Catalina internal class loaders is
StandardClassLoader
. Required and available optional packages
are described using the Extension
class. For more information,
see the source code and/or Javadocs for the following classes:
org.apache.catalina.loader.StandardClassLoader
org.apache.catalina.loader.Extension