Catalina Class Loader Hierarchy


[Introduction] [Overview] [Process] [Notes]

Introduction

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.

Overview Diagram

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:

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.

Web Application Class Loading Process

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:

  1. The loadClass() method of the Webapp class loader is called to load the specified class.
  2. 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 Webapp class loader, the restricted list is configured to include 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).
  3. 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.
  4. If the requested class has a prefix that is on the "system classes" list, the Webapp class loader delegates to its parent (i.e. the Shared class loader), in the usual Java2 delegation fashion. For the Webapp class loader, the "system classes" list is configured to include java. and javax.servlet. so that you cannot override system or servlet API classes with your own copies.
  5. Local repositories (i.e. the contents of the 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.
  6. 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 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.

Miscellaneous Notes

Class Loader Information Exposed For Web Applications

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:

Additional Information

For more information about class loaders in general, see the Java Language Specification, and the Javadocs for the following classes:

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:



$Id: classloaders.html,v 1.1 2000/09/30 20:51:37 craigmcc Exp $