Tomcat Class Loader

Tomcat Class Loader

Quick Start

For classes and resources specific to a particular web app:

Put unpacked classes and resources under /WEB-INF/class of your web app archive
Put JAR files containing those classes and resources under /WEB-INF/lib of your web app archive.

For classes and resources that must be shared across all web apps

Put unpacked classes and resources under $CATALINA_HOME/shared/classes
Put JAR files containing those classes and resources under $CATALINA_HOME/shared/lib.

Overview

Tomcat 4 installs a variety of class loaders so that the web apps running on the container have access to different repositories of available classes and resources. In a Java 2 (JDK 1.2 or later) 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.
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:

Bootstrap | System | Common / \ Catalina Shared / \ Webapp1 Webapp2 ...

Class Loader Definitions

Bootstrap - 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 - Normally initialized from the contents of the CLASSPATH environment variable. All such classes are visible to both Tomcat internal classes, and to web apps. However, the standard Tomcat 4 startup scripts ($CATALINA_HOME/bin/catalina.sh) totally ignore the contents of the 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 4 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.

Common - Contains additional classes that are made visible to both Tomcat internal classes and to all web apps. Normally, app 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 $CATALINA_HOME/commons/endorsed and $CATALINA_HOME/common/lib directories, are made visible through this class loader. By default, that includes the following:

jndi.jar The Java Naming and Directory Interface API classes (loaded ONLY on a JDK 1.2 system, because they are included automatically on JDK 1.3 and later).

naming-common.jar The JNDI implementation used by Tomcat 4 to represent in-memory naming contexts.

naming-resources.jar The specialized JNDI naming context implementation used to represent the static resources of a web app.

servlet.jar The Servlet and JSP API classes.

xerces.jar The XML parser that is visible by default to Tomcat internal classes and to web apps. This can be overridden, for a particular web app, by including your desired parser in /WEB-INF/lib.

Catalina - Initialized to include all classes and resources required to implement Tomcat 4 itself. These classes and resources are TOTALLY invisible to web apps. 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 4.

jakarta-regexp-X.Y.jar The binary distribution of the Jakarta Regexp regular expression processing library, used in the implementation of request filters.

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 connector for Tomcat 4.

tomcat-http11.jar Standalone Java HTTP/1.1 connector.

tomcat-jk.jar Classes for the Java portion of the JK web server connector, which allows Tomcat to run behind web servers such as Apache and iPlanet iAS and iWS.

tomcat-jk2.jar Classes for the Java portion of the JK 2 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 Tomcat connectors.

tomcat-webapp.jar Classes for the Java portion of the Webapp web server connector, which allows Tomcat to run behind web servers such as Apache and iPlanet iAS and iWS.

Shared - Place to put classes and resources that you wish to share across ALL web apps (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_HOME/shared/classes, as well as classes and resources in JAR files under $CATALINA_HOME/lib are made visible through this class loader. By default, that includes the following:

jasper-compiler.jar - The page compiler classes required to convert JSP source pages into executable servlets and compile them.

jasper-runtime.jar - The runtime support classes required to execute JSP pages that have already been translated into Java servlets and then compiled.

naming-factory.jar - JNDI object factories for resources supported by the default JNDI naming context provided to web apps.

WebappN - A class loader is created for each web app that is deployed in a single Tomcat 4 instance. All unpacked classes and resources in the /WEB-INF/classes directory of your web app archive, plus classes and resources in JAR files under the /WEB-INF/lib directory of your web app archive, are made visible to the containing web app, but to no others.

As mentioned above, the web app 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 app's WebappN class loader is processed, this class loader will look in the local repositories first, instead of delegating before looking. All other class loaders in Tomcat 4 follow the usual delegation pattern.

Therefore, from the perspective of a web app, class or resource loading looks in the following repositories, in this order:

/WEB-INF/classes of your web app

/WEB-INF/lib/*.jar of your web app

Bootstrap classes of your JVM

System class loader classses (described above)

$CATALINA_HOME/common/classes

$CATALINA_HOME/common/endorsed/*.jar

$CATALINA_HOME/common/lib/*.jar

$CATALINA_HOME/shared/classes

$CATALINA_HOME/shared/lib/*.jar

XML Parsers and JDK 1.4

The JDK 1.4 release packages the JAXP APIs, and a version of Xerces, inside the JDK. This has impacts on apps that wish to use their own XML parser.

In previous versions of Tomcat 4, you could simply replace the XML parser in the $CATALINA_HOME/common/lib directory to change the parser used by all web apps. However, this technique will not be effective when you are running on JDK 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: http://java.sun.com/j2se/1.4/docs/guide/standards/index.html.

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.

jndi.jar	The Java Naming and Directory Interface API classes (loaded ONLY on a JDK 1.2 system, because they are included automatically on JDK 1.3 and later).
naming-common.jar	The JNDI implementation used by Tomcat 4 to represent in-memory naming contexts.
naming-resources.jar	The specialized JNDI naming context implementation used to represent the static resources of a web app.
servlet.jar	The Servlet and JSP API classes.
xerces.jar	The XML parser that is visible by default to Tomcat internal classes and to web apps. This can be overridden, for a particular web app, by including your desired parser in /WEB-INF/lib.

catalina.jar	Implementation of the Catalina servlet container portion of Tomcat 4.
jakarta-regexp-X.Y.jar	The binary distribution of the Jakarta Regexp regular expression processing library, used in the implementation of request filters.
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 connector for Tomcat 4.
tomcat-http11.jar	Standalone Java HTTP/1.1 connector.
tomcat-jk.jar	Classes for the Java portion of the JK web server connector, which allows Tomcat to run behind web servers such as Apache and iPlanet iAS and iWS.
tomcat-jk2.jar	Classes for the Java portion of the JK 2 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 Tomcat connectors.
tomcat-webapp.jar	Classes for the Java portion of the Webapp web server connector, which allows Tomcat to run behind web servers such as Apache and iPlanet iAS and iWS.