Links Docs Home Getting Started Introduction READ ME Install and Run Building from Source Administrators Config. Reference Class Loader HOW-TO JNDI Resources HOW-TO Manager App HOW-TO Proxy Support HOW-TO Realm HOW-TO Security Mgr. HOW-TO SSL Config HOW-TO Application Developers App Developer Guide Servlet/JSP Javadocs Catalina Developers Functional Specs. Javadocs Jasper Developers Javadocs | # Class Loader INFO
Quick Start
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 `/WEB-INF/classe` of your web application archive, or place JAR files containing those classes and resources under `/WEB-INF/lib` of your web application archive. For classes and resources that must be shared across all web applications, place unpacked classes and resources under `$CATALINA_HOME/classes`, or place JAR files containing those classes and resources under `$CATALINA_HOME/lib`. WARNING - Unlike Tomcat 3.x, Tomcat 4 does NOT make an XML parser visible to web applications by default. If you need to do this, see Tomcat 4 and XML Parsers, below.
Overview
> Like many server applications, Tomcat 4 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.3 -- in particular, Sections 9.4 and 9.6. In a Java 2 (that is, JDK 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 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 ...

>               /         /

>            Jasper1  Jasper2 ...
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 4 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 4 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/lib/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 - 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 `$CATALINA_HOME/common/lib`, 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.jar - The JNDI implementation used by Tomcat 4 to represent the default JNDI naming context provided to web applications. resources.jar - Resource factory classes for the JNDI naming context that is used internally to represent the static resources of a web application. servlet.jar - The Servlet and JSP API classes. Catalina - This class loader is initialized to include all classes and resources required to implement Tomcat 4 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 4. crimson.jar - Parser portion of the JAXP/1.1 reference implementation, used to parse web application deployment descriptor (`web.xml`) files, as well as the server configuration file (`$CATALINA_HOME/conf/server.xml`). jakarta-regexp-X.Y.jar - The binary distribution of the Jakarta Regexp regular expression processing library, used in the implementation of request filters. jaxp.jar - JAXP API portion of the JAXP/1.1 reference implementation, used to parse web application deployment descriptor (`web.xml`) files, as well as the server configuration file (`$CATALINA_HOME/conf/server.xml`). warp.jar - Classes for the Java portion of the `mod_webapp` web server connector, which allows Tomcat to run behind web servers such as Apache and iPlanet iAS and iWS. 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, which is an unusual case). All unpacked classes and resources in `$CATALINA_HOME/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-runtime.jar - The runtime support classes required to execute JSP pages that have already been translated into Java servlets and then compiled. namingfactory.jar - JNDI object factories for resources supported by the default JNDI naming context provided to web applications. WebappX - A class loader is created for each web application that is deployed in a single Tomcat 4 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. JasperX - If your web application uses JSP pages, Tomcat also creates an additional class loader for the web application, containing the JSP compiler and classes it depends on. It is initialized to include all JAR files found in `$CATALINA_HOME/jasper`. Because this is a child class loader of the web application class loader, the Jasper compiler (and the pages that it compiles) can see all of the application bean classes visible in the `Webapp` class loader. 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.6). 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. All other class loaders in Tomcat 4 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: /WEB-INF/classes of your web application /WEB-INF/lib/*.jar of your web application Bootstrap classes of your JVM System class loader classses (described above) $CATALINA_HOME/common/classes $CATALINA_HOME/common/*.jar $CATALINA_HOME/classes $CATALINA_HOME/lib/*.jar
Tomcat 4 and XML Parsers
Tomcat 4 itself utilizes XML parsing for three processing activities: Parsing the `server.xml` configuration file Parsing `web.xml` deployment descriptors Parsing JSP pages in XML syntax By default, the Java API for XML Processing (Version 1.1) reference implementation is utilized for all of these purposes. However, this parser is not visible to web applications -- instead, the XML parser stored in `$CATALINA_HOME/server/lib` is used for parsing `web.xml` and `server.xml` files, while the parser stored in `$CATALINA_HOME/jasper` is used for parsing JSP pages in XML syntax. To make an XML parser available to your web applications, you have several options: To utilize an XML parser in a single web application, simply include the parser's JAR files in the `/WEB-INF/web.xml` directory of that web application. This will work, no matter what parser might be used by Tomcat 4 internally, or by other web applications running in the same instance of Tomcat 4. If you wish to make the JAXP/1.1 reference implementation parser available to all web applications, simply move the "jaxp.jar" and "crimson.jar" files from the `$CATALINA_HOME/jasper` directory into the `$CATALINA_HOME/lib` directory. Jasper will continue to use this parser for processing JSP pages in XML syntax. If you wish to make another XML parser that is JAXP/1.1 compatible (such as Xerces 1.3.1 or later), install that parser's JAR files into the `$CATALINA_HOME/lib` directory, and remove "jaxp.jar" and "crimson.jar" from the `$CATALINA_HOME/jasper` directory. Jasper will then utilize the new XML parser as well. WARNING - Do not attempt to use a JAXP/1.0 (rather than JAXP/1.1) compliant parser with Tomcat 4. Tomcat relies on the extra features that were added in JAXP/1.1 to perform its parsing activities. WARNING - The final release of the JAXP/1.1 reference implementation includes JAR files with the `sealed` attribute. This causes class loading problems (most commonly visible through "package sealing violation" exceptions) on JDK 1.3 and later platforms. To avoid these problems, modified versions of "jaxp.jar" and "crimson.jar" are shipped with Tomcat 4. You must NOT replace these files with standard JAXP/1.1 JAR files, until a subsequent JAXP release occurs that has the "sealed" attribute removed.
Copyright © 1999-2001, Apache Software Foundation