Apache Tomcat 6.0

Class Loader HOW-TO

Like many server applications, Tomcat 6 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 6 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 / \ 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.

As indicated in the diagram above, Tomcat 6 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.sh or %CATALINA_HOME%\bin\catalina.bat) 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 6 server, and the class loader implementation classes it depends on.
  • $CATALINA_HOME/bin/tomcat-juli.jar - Package renamed Jakarta commons logging API, and java.util.logging LogManager.
• 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/lib, as well as classes and resources in JAR files are made visible through this class loader. By default, that includes the following:
  • annotations-api.jar - JEE annotations classes.
  • catalina.jar - Implementation of the Catalina servlet container portion of Tomcat 6.
  • catalina-ant.jar - Tomcat Catalina Ant tasks.
  • catalina-ha.jar - High availability package.
  • catalina-tribes.jar - Group communication package.
  • el-api.jar - EL 2.1 API.
  • jasper.jar - Jasper 2 Compiler and Runtime.
  • jasper-el.jar - Jasper 2 EL implementation.
  • jasper-jdt.jar - Eclipse JDT 3.2 Java compiler.
  • jsp-api.jar - JSP 2.1 API.
  • servlet-api.jar - Servlet 2.5 API.
  • tomcat-coyote.jar - Tomcat connectors and utility classes.
  • tomcat-dbcp.jar - package renamed database connection pool based on Commons DBCP.
  • 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.
• WebappX - A class loader is created for each web application that is deployed in a single Tomcat 6 instance. All unpacked classes and resources in the /WEB-INF/classes directory of your web application archive, plus classes and resources in JAR files under the /WEB-INF/lib directory of your web application archive, are made visible to the containing web application, but to no others.

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 used. Last, any JAR containing servlet API classes will be ignored by the classloader. All other class loaders in Tomcat 6 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 classses (described above)
• /WEB-INF/classes of your web application
• /WEB-INF/lib/*.jar of your web application
• $CATALINA_HOME/lib
• $CATALINA_HOME/lib/*.jar

Among many other changes, the JSE 5 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, you could simply replace the XML parser in the $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 JSE 5, because the usual class loader delegation process will always choose the implementation inside the JDK in preference to this one.

JDK 1.5 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.5/docs/guide/standards/index.html.

Tomcat utilizes this mechanism by including the system property setting -Djava.endorsed.dirs=$CATALINA_HOME/endorsed in the command line that starts the container.

When running under a security manager the locations from which classes are permitted to be loaded will also depend on the contents of your policy file. See Security Manager HOW-TO for further information.