Apache Tomcat Development
The Apache Tomcat 5.5 Servlet/JSP Container
Class Loader HOW-TO
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:
- For classes and resources specific to a particular web application,
place unpacked classes and resources under
of your web application archive, or place JAR files containing those
classes and resources under
/WEB-INF/lib of your web
- For classes and resources that must be shared across all web applications,
place unpacked classes and resources under
$CATALINA_BASE/shared/classes, or place JAR files
containing those classes and resources under
Like many server applications, Tomcat 5 installs a variety of class loaders
(that is, classes that implement
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 Specification, version 2.4 -- in particular, Sections 9.4 and 9.6.
In a J2SE 2 (that is, J2SE 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.
When Tomcat 5 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:
Webapp1 Webapp2 ...
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.
|Class Loader Definitions|
As indicated in the diagram above, Tomcat 5 creates the following class
loaders as it is initialized:
- Bootstrap - 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
$JAVA_HOME/jre/lib/ext). NOTE - Some JVMs may
implement this as more than one class loader, or it may not be visible
(as a class loader) at all.
- System - This class loader is normally initialized from
the contents of the
CLASSPATH environment variable. All such
classes are visible to both Tomcat internal classes, and to web
applications. However, the standard Tomcat 5 startup scripts
%CATALINA_HOME%\bin\catalina.bat) totally ignore the contents
CLASSPATH environment variable itself, and instead
build the System class loader from the following repositories:
- $CATALINA_HOME/bin/bootstrap.jar - Contains the main() method
that is used to initialize the Tomcat 5 server, and the class loader
implementation classes it depends on.
- $JAVA_HOME/lib/tools.jar - Contains the "javac" compiler used
to convert JSP pages into servlet classes.
- $CATALINA_HOME/bin/commons-logging-api-x.y.z.jar - Jakarta
commons logging API.
- $CATALINA_HOME/bin/commons-daemon.jar - Jakarta commons
- jmx.jar - The JMX 1.2 implementation.
- Common - This class loader contains additional classes
that are made visible to both Tomcat internal classes and to all web
applications. Normally, application classes should NOT
be placed here. All unpacked classes and resources in
$CATALINA_HOME/common/classes, as well as classes and
resources in JAR files under the
are made visible through this
class loader. By default, that includes the following:
- commons-el.jar - Jakarta commons el, implementing the
expression language used by Jasper.
- ecj-x.y.x.jar - The Eclipse JDT Java compiler.
- jasper-compiler.jar - The JSP 2.0 compiler.
- jasper-runtime.jar - The JSP 2.0 runtime.
- jsp-api.jar - The JSP 2.0 API.
- naming-common.jar - The JNDI implementation used by Tomcat 5
to represent in-memory naming contexts.
- naming-factory.jar - The JNDI implementation used by Tomcat 5
to resolve references to enterprise resources (EJB, connection
- naming-factory-dbcp.jar - Jakarta commons DBCP, providing a
JDBC connection pool to web applications. The classes have been moved
out of their default org.apache.commons package.
- naming-java.jar - Handler for the java: namespace.
- naming-resources.jar - The specialized JNDI naming context
implementation used to represent the static resources of a web
application. This is not related to the support of the J2EE ENC, and
cannot be removed.
- servlet-api.jar - The Servlet 2.4 API.
- tomcat-i18n-**.jar - 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.
- Catalina - This class loader is initialized to include
all classes and resources required to implement Tomcat 5 itself. These
classes and resources are TOTALLY invisible to web
applications. All unpacked classes and resources in
$CATALINA_HOME/server/classes, as well as classes and
resources in JAR files under
$CATALINA_HOME/server/lib, are made visible through
this class loader. By default, that includes the following:
- catalina.jar - Implementation of the Catalina servlet
container portion of Tomcat 5.
- catalina-ant.jar - Some Ant tasks which can be used to
manage Tomcat using the manager web application.
- catalina-optional.jar - Some optional components of
- commons-modeler.jar - A model MBeans implementation used
by Tomcat to expose its internal objects through JMX.
- servlets-xxxxx.jar - The classes associated with each
internal servlet that provides part of Tomcat's functionality.
These are separated so that they can be completely removed if the
corresponding service is not required, or they can be subject to
specialized security manager permissions.
- tomcat-coyote.jar - Coyote API.
- tomcat-http.jar - Standalone Java HTTP/1.1
- tomcat-ajp.jar - Classes for the Java portion of the
AJP web server connector, which allows Tomcat to
run behind web servers such as Apache and iPlanet iAS and iWS.
- tomcat-util.jar - Utility classes required by some
- Shared - This class loader is the place to put classes
and resources that you wish to share across ALL
web applications (unless Tomcat internal classes also need access,
in which case you should put them in the Common
class loader instead). All unpacked classes and resources in
$CATALINA_BASE/shared/classes, as well as classes and
resources in JAR files under
made visible through this class loader. If multiple Tomcat instances are
run from the same binary using the $CATALINA_BASE environment variable,
then this classloader repositories are relative to $CATALINA_BASE rather
- WebappX - A class loader is created for each web
application that is deployed in a single Tomcat 5 instance. All unpacked
classes and resources in the
/WEB-INF/classes directory of
your web application archive, plus classes and resources in JAR files
/WEB-INF/lib directory of your web application
archive, are made visible to the containing web application, but to
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).
When a request to load a
class from the web application's WebappX class loader is processed,
this class loader will look in the local repositories first,
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
the XML parser components in J2SE 1.4+), the J2SE 1.4 endorsed feature can be
(see the common classloader definition above).
Last, any JAR containing servlet API classes will be ignored by the
All other class loaders in Tomcat 5 follow the usual delegation pattern.
Therefore, from the perspective of a web application, class or resource
loading looks in the following repositories, in this order:
- Bootstrap classes of your JVM
- System class loader classes (described above)
- /WEB-INF/classes of your web application
- /WEB-INF/lib/*.jar of your web application
|XML Parsers and J2SE 1.4|
Among many other changes, the J2SE 1.4 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.
In previous versions of Tomcat 5, you could simply replace the XML parser
$CATALINA_HOME/common/lib directory to change the parser
used by all web applications. However, this technique will not be effective
when you are running on J2SE 1.4, because the usual class loader delegation
process will always choose the implementation inside the JDK in preference
to this one.
JDK 1.4 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:
Tomcat utilizes this mechanism by including the system property setting
-Djava.endorsed.dirs=$CATALINA_HOME/common/endorsed in the
command line that starts the container. Therefore, you can replace the
parser that is installed in this directory, and it will get used even on a
JDK 1.4 system.