Java Webapplication Classloaders with Tomcat 4.0 and the Eclipse Tomcatplugin

Author: Martin Kahr

1. ClassLoaders

   Classloaders are primarly responsible for loading Java class files and for initializing the corresponding java.lang.Class object.
   
   Different Classloader implementations already exist in Java2.
   e.g. The systemclassloader is responsible for searching and loading java class files from the jar, zip and directories as defined in the CLASSPATH systemproperty and the RMIClassLoader loads classes through the HTTP protocol.
   
   Classloaders may be nested.
   From the JAVA SDK Documentation:

   The ClassLoader class uses a delegation model to search for classes and resources. Each instance of ClassLoader has an associated parent class loader. When called upon to find a class or resource, a ClassLoader instance will delegate the search for the class or resource to its parent class loader before attempting to find the class or resource itself.
   

   The parent classloader is unable to access any resources (classes) of it's child classloaders.
   

2. Webapplication Classloader

   Simplified a Java Webapplication in Tomcat uses two different Classloader instances. The Systemclassloader (SCL) and the Webapplication-Classloader (WCL). The parent classloader of the WCL is the SCL.
   
   Each deployed Webapplication has it's own WCL in Tomat. All WCL share the same (one and only) SCL.
   So as defined by the Java SDK Documentation all classes which are loaded by the Systemclassloader are visible to all Webapplications.
   Classes which are loaded by one WCL are not visible to other WCLs !
   The WCL loads classes from the WEB-INF/classes directory and the from JAR (!) files in the WEB-INF/lib directory only.
   
   As defined in the Java SDK Documentation the WCL should work as following:
   Before a WCL loads a class he must ask the parent classloader (SCL) if he already knows the class. If the SCL does not know the class the WCL tries to load it.
   This feature makes it possible to deploy two web-applications which use a different version of class A (as long as class A is not loadable through the SCL).
   
   The exception:
   The final servlet 2.3 specification defines the exception to the common rule.
   From Servlet 2.3 Specification SRV.9.7.2 - WebApplication Classloader:

   It is recommended also that the application class loader be implemented so that classes and resources packaged within the WAR are loaded in preference to classes and resources residing in container-wide library JARs.

   Tomcat 4.x supports this recommendation through a property which may be set in the server.xml configuration. Default setting is to act as defined in the Servlet specification.
   See also the actual documentation of the Tomcat project.
   

3. Web-Projects in Eclipse

   With the TomcatPlugin it's easy to define a new webproject and to launch tomcat within the IDE.
   Eclipse makes it very easy to divide a big project into some subprojects. e.g. utility classes which will be used by many projects resist in a project named "utils" and the concrete projects are referencing the "utils" project.
   
   Unfortunatly the classes of the "utils" project are not automatically visible to Tomcat during runtime.
   
   There are two possibilities:

   1. Load the classes of the "utils" project through the Systemclassloader.
      This can be done by adding the "utils" project to the Systemclasspath of Tomcat (Window->Preferences->Tomcat).
      Why is this a bad idea ?
      Typically your webproject class files (including those of the "utils" project) will resist in WEB-INF/classes or WEB-INF/lib of the WAR file for production mode.
      So if you add some classes to the systemclassloader for development you will have a different classloading mechanism in production mode - this may lead to strange errors !
      Additionaly some code does not work if you load the classes in the systemclassloader.
      e.g. if the following class will resist in the "utils" project and you want to use this code to load a property file which resists in your webapplication (WEB-INF/classes) it is unable to load the resource because the systemclassloader is not allowed to access resources of the webappclassloader.

      public class ResourceLoader {
      	public Properties load(String resourceName) {
      		ClassLoader cl = ResourceLoader.class.getClassLoader();
      		InputStream in = cl.getResourceAsStream(resourceName);
      		...								
      	}
      }
      					

   2. Load the classes of the "utils" project through the Webclassloader.
      To load the classes through the Webclassloader the classes of the "utils" project must be put into the WEB-INF/classes or packaged as JAR into WEB-INF/lib directory.
      This may be done by hand or through some ANT build scripts - but unfortunatly each time you change code in the "utils" project :(
      

4. The Development-Webapp-Classloader
   

   There's a simple solution for making things easier. It works the following way:
   

   • A special Tomcat Webappclassloader implementation extends the mechanism of loading classes not only from WEB-INF/classes and WEB-INF/lib but also from locations which are specified in a special configuration file.
   • Through the TomcatPlugin you specify for each Tomcat project which classes shall be loaded through the Webclassloader - yust point and click.
     The TomcatPlugin writes the configuration file and the correct tomcat configuration (into server.xml).
   NOTE: Use the Development-Webapp-Classloader yust during development - It's not recommended to use it for production systems !!

5. Installation:
   

   The classes in the zip "devloader.zip" must be extracted into "TOMCAT_HOME/server/classes".
   

6. Requirements:
   

   At the moment an implementation of the "DevLoader" only exists for Tomcat 4.x.
   So Tomcat 4.x is required.