tomcat-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject cvs commit: jakarta-tomcat-4.0/catalina/docs/dev classloaders.html architecture.html
Date Sat, 30 Sep 2000 20:51:37 GMT
craigmcc    00/09/30 13:51:37

  Modified:    catalina/docs/dev architecture.html
  Added:       catalina/docs/dev classloaders.html
  Add a new Catalina developer doc that describes how class loaders are
  configured and used within Catalina.
  Revision  Changes    Path
  1.2       +2 -2      jakarta-tomcat-4.0/catalina/docs/dev/architecture.html
  Index: architecture.html
  RCS file: /home/cvs/jakarta-tomcat-4.0/catalina/docs/dev/architecture.html,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- architecture.html	2000/08/30 22:32:07	1.1
  +++ architecture.html	2000/09/30 20:51:36	1.2
  @@ -3,13 +3,13 @@
   <title>Architecture of Catalina</title>
  -<body bgcolor="white>
  +<body bgcolor="white">
   TODO ...
   <div align="center"><hr width="75%"><font size="2">
  -$Id: architecture.html,v 1.1 2000/08/30 22:32:07 craigmcc Exp $
  +$Id: architecture.html,v 1.2 2000/09/30 20:51:36 craigmcc Exp $
  1.1                  jakarta-tomcat-4.0/catalina/docs/dev/classloaders.html
  Index: classloaders.html
  <title>Catalina Class Loader Hierarchy</title>
  <body bgcolor="white">
  <div align="center">
  <h1>Catalina Class Loader Hierarchy</h1>
  <a href="#Introduction">[Introduction]</a>
  <a href="#Overview">[Overview]</a>
  <a href="#Process">[Process]</a>
  <a href="#Notes">[Notes]</a>
  <a name="Introduction"></a>
  <p>Like many server applications, Catalina installs a variety of class loaders
  (that is, classes that extend <code>java.lang.ClassLoader</code>) 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.</p>
  <p>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.</p>
  <a name="Overview"></a>
  <h3>Overview Diagram</h3>
  <p>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.</p>
  <p>The class loaders that Catalina uses are organized as follows, where
  the parent class loader is above the child class loaders:</p>
                        /      \
                   Catalina   Shared
                             /     \
                         Webapp1  Webapp2 ...
  <p>The usage of and repositories contained in each class loader are
  described further below:</p>
  <li><strong>Bootstrap</strong> - This class loader contains the basic
      runtime classes provided by the Java Virtual Machine, such as the
      <code>java.*</code> classes.  Depending on how your particular JVM
      is organized, this may actually be more than one class loader, or
      may not exist at all.  It is generally not referenced directly.</li>
  <li><strong>System</strong> - This class loader is initialized from the
      contents of the <code>CLASSPATH</code> environment variable.  The
      standard Catalina startup scripts assemble the following repositories
      for the system class path:
      <li><code>$CATALINA_HOME/bin/bootstrap.jar</code> - The Bootstrap
          that is used to initialize the Catalina server, and the class
          loader implementation classes it depends on.</li>
      <li><code>$CATALIA_HOME/bin/servlet.jar</code> - The Servlet and JSP
          API classes, placed here so that they are shared between Catalina
          and the web applications that run under it.</li>
      <li><code>$JAVA_HOME/lib/tools.jar</code> - Contains the Javac
          compiler used to compile the servlets generated from JSP pages.</li>
  <li><strong>Catalina</strong> - This class loader is initialized to include
      all JAR files in the <code>$CATALINA_HOME/server</code> directory, which
      should contain Catalina itself (i.e. all classes whose fully qualified
      names begin with <code>org.apache.catalina.</code>), and any JAR files
      that it depends on.  Because these classes are loaded from a separate
      class loader, which is not visible to the <em>Webapp</em> class loader,
      they are <strong>not</strong> visible to web applications.</li>
  <li><strong>Shared</strong> - This class loader is initialized to include
      all JAR files in the <code>$CATALINA_HOME/lib</code> directory.  All of
      the classes in these repositories will be visible to all web applications,
      so they may be used to share information between web apps
      (<strong>NOTE</strong> - this behavior is specific to Tomcat 4.0, and
      will not necessarily be portable to other containers.)</li>
  <li><strong>Webapp</strong> - A class loader is created for each web
      application that is installed in Catalina, and initialized to include the
      <code>WEB-INF/classes</code> directory (if it exists), plus all JAR files
      in the <code>WEB-INF/lib</code> directory, for this web app.  Because of
      the parentage hierarchy, web applications can indirectly see (and therefore
      load classes from) the <em>Shared</em>, <em>System</em>, and
      <em>Bootstrap</em> class loaders, but <strong>not</strong> from
      <em>Catalina</em> class loader.</li>
  <p>As you can see from the above descriptions, the contents of any
  <code>CLASSPATH</code> environment variable already existing in your server
  is totally ignored.  If you want to make a JAR file available to all web
  applications, you <strong>must</strong> place a copy of this file in the
  <code>$CATALINA_HOME/lib</code> directory so that it becomes part of the
  <em>Shared</em> class loader's repositories.</p>
  <a name="Process"></a>
  <h3>Web Application Class Loading Process</h3>
  <p>When a servlet (or JSP page) within a web application references a class
  for the first time (either by using the <code>new</code> operator or by
  calling the <code>Class.forName()</code> method), the following processing
  occurs to locate and load the requested class:</p>
  <li>The <code>loadClass()</code> method of the <em>Webapp</em>
class loader
      is called to load the specified class.</li>
  <li>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 <em>Webapp</em>
      class loader, the restricted list is configured to include
      <code>org.apache.catalina.</code>, so that any attempt to load an internal
      Catalina implementation class is refused (even if the web app developer
      tries to put <code>catalina.jar</code> someplace visible to their app).
  <li>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.</li>
  <li>If the requested class has a prefix that is on the "system classes" list,
      the <em>Webapp</em> class loader delegates to its parent (i.e. the
      <em>Shared</em> class loader), in the usual Java2 delegation fashion.
      For the <em>Webapp</em> class loader, the "system classes" list is
      configured to include <code>java.</code> and <code>javax.servlet.</code>
      so that you cannot override system or servlet API classes with your
      own copies.</li>
  <li>Local repositories (i.e. the contents of the <code>WEB-INF/classes</code>
      directory, followed by the contents of JAR files found in the
      <code>WEB-INF/lib</code> directory) are searched next.  If the class is
      found here, it is cached in memory, and returned.</li>
  <li>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
      <code>ClassNotFoundException</code> if no class with this name can be
      located anywhere in the class loader hierarchy visible to the web app.</li>
  <p>A similar pattern is followed when you call <code>Class.getResource()</code>
  or <code>Class.getResourceAsStream()</code> to access resources that are
  co-resident with your classes.</p>
  <a name="Notes"></a>
  <h3>Miscellaneous Notes</h3>
  <h4>Class Loader Information Exposed For Web Applications</h4>
  <p>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:</p>
  <li><strong>org.apache.catalina.classloader</strong> - The <em>Webapp</em>
  class loader for this application (which will also be the class loader used
  to load the Jasper servlet itself).</li>
  <li><strong>org.apache.catalina.jsp_classpath</strong> - A String
  representation of the directories and JAR files available in the
  <em>webapp</em>, <em>shared</em>, and <em>system</em>
class loaders, with
  each repository separated by the appropriate path separator character for
  the platform this server is running on.</li>
  <h4>Additional Information</h4>
  <p>For more information about class loaders in general, see the Java Language
  Specification, and the Javadocs for the following classes:</p>
  <p>The implementation class for all Catalina internal class loaders is
  <code>StandardClassLoader</code>.  Required and available optional packages
  are described using the <code>Extension</code> class.  For more information,
  see the source code and/or Javadocs for the following classes:
  <div align="center"><hr width="75%"><font size="2">
  $Id: classloaders.html,v 1.1 2000/09/30 20:51:37 craigmcc Exp $

View raw message