tomcat-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From craig...@apache.org
Subject cvs commit: jakarta-tomcat-4.0/webapps/tomcat-docs class-loader-howto.xml index.xml project.xml
Date Tue, 04 Sep 2001 04:39:05 GMT
craigmcc    01/09/03 21:39:05

  Modified:    webapps/tomcat-docs index.xml project.xml
  Added:       webapps/tomcat-docs class-loader-howto.xml
  Log:
  Convert documentation on the use of class loaders in Tomcat 4 into the new
  documentation format.
  
  Revision  Changes    Path
  1.10      +3 -0      jakarta-tomcat-4.0/webapps/tomcat-docs/index.xml
  
  Index: index.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/tomcat-docs/index.xml,v
  retrieving revision 1.9
  retrieving revision 1.10
  diff -u -r1.9 -r1.10
  --- index.xml	2001/08/21 02:28:21	1.9
  +++ index.xml	2001/09/04 04:39:04	1.10
  @@ -62,6 +62,9 @@
       - Reference manual that documents all available elements and attributes
         that may be placed into a Tomcat 4 <code>conf/server.xml</code> file.
       </li>
  +<li><a href="class-loader-howto.html"><strong>Class Loader HOW-TO</strong></a>
  +    - Information about class loading in Tomcat 4, including where to place
  +    your application classes so that they are visible.</li>
   <li><a href="manager-howto.html"><strong>Manager App HOW-TO</strong></a>
-
       Operating the <code>Manager</code> web app to deploy, undeploy, and
       redeploy applications while Tomcat is running.</li>
  
  
  
  1.10      +1 -0      jakarta-tomcat-4.0/webapps/tomcat-docs/project.xml
  
  Index: project.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/tomcat-docs/project.xml,v
  retrieving revision 1.9
  retrieving revision 1.10
  diff -u -r1.9 -r1.10
  --- project.xml	2001/08/21 02:28:21	1.9
  +++ project.xml	2001/09/04 04:39:04	1.10
  @@ -24,6 +24,7 @@
   
       <menu name="Administrators">
           <item name="Config. Reference"     href="config/index.html"/>
  +        <item name="Class Loader HOW-TO"   href="class-loader-howto.html"/>
           <item name="Manager App HOW-TO"    href="manager-howto.html"/>
           <item name="Proxy Support HOW-TO"  href="proxy-howto.html"/>
           <item name="SSL Config HOW-TO"     href="ssl-howto.html"/>
  
  
  
  1.1                  jakarta-tomcat-4.0/webapps/tomcat-docs/class-loader-howto.xml
  
  Index: class-loader-howto.xml
  ===================================================================
  <?xml version="1.0"?>
  <!DOCTYPE document [
    <!ENTITY project SYSTEM "project.xml">
  ]>
  <document>
  
      &project;
  
      <properties>
          <author email="craigmcc@apache.org">Craig R. McClanahan</author>
          <title>Class Loader INFO</title>
      </properties>
  
  <body>
  
  
  <section name="Quick Start">
  
  <p>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:</p>
  <ul>
  <li>For classes and resources specific to a particular web application,
      place unpacked classes and resources under <code>/WEB-INF/classe</code>
      of your web application archive, or place JAR files containing those
      classes and resources under <code>/WEB-INF/lib</code> of your web
      application archive.</li>
  <li>For classes and resources that must be shared across all web applications,
      place unpacked classes and resources under
      <code>$CATALINA_HOME/classes</code>, or place JAR files containing those
      classes and resources under <code>$CATALINA_HOME/lib</code>.</li>
  </ul>
  
  <p><strong>WARNING</strong> - Unlike Tomcat 3.x, Tomcat 4 does
  <strong>NOT</strong> make an XML parser visible to web applications by default.
  If you need to do this, see <a href="#Tomcat 4 and XML Parsers">Tomcat 4 and
  XML Parsers</a>, below.</p>
  
  </section>
  
  
  <section name="Overview">
  
  <p>Like many server applications, Tomcat 4 installs a variety of class loaders
  (that is, classes that implement <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 Specification, version 2.3 -- in particular, Sections 9.4 and 9.6.</p>
  
  <p>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.</p>
  
  <p>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:</p>
  
  <source>
        Bootstrap
            |
         System
            |
         Common
        /      \
   Catalina   Shared
               /   \
          Webapp1  Webapp2 ... 
            /         /
         Jasper1  Jasper2 ...
  </source>
  
  <p>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.</p>
  
  </section>
  
  <section name="Class Loader Definitions">
  
  <p>As indicated in the diagram above, Tomcat 4 creates the following class
  loaders as it is initialized:</p>
  <ul>
  <li><strong>Bootstrap</strong> - 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
      (<code>$JAVA_HOME/jre/lib/ext</code>).  <em>NOTE</em> - Some
JVMs may
      implement this as more than one class loader, or it may not be visible
      (as a class loader) at all.</li>
  <li><strong>System</strong> - This class loader is normally initialized
from
      the contents of the <code>CLASSPATH</code> environment variable.  All such
      classes are visible to both Tomcat internal classes, and to web
      applications.  However, the standard Tomcat 4 startup scripts
      (<code>$CATALINA_HOME/bin/catalina.sh</code> or
      <code>%CATALINA_HOME%\bin\catalina.bat</code>) totally ignore the contents
      of the <code>CLASSPATH</code> environment variable itself, and instead
      build the System class loader from the following repositories:
      <ul>
      <li><em>$CATALINA_HOME/lib/bootstrap.jar</em> - Contains the main()
method
          that is used to initialize the Tomcat 4 server, and the class loader
          implementation classes it depends on.</li>
      <li><em>$JAVA_HOME/lib/tools.jar</em> - Contains the "javac" compiler
used
          to convert JSP pages into servlet classes.</li>
      </ul></li>
  <li><strong>Common</strong> - This class loader contains additional classes
      that are made visible to both Tomcat internal classes and to all web
      applications.  Normally, application classes should <strong>NOT</strong>
      be placed here.  All unpacked classes and resources in
      <code>$CATALINA_HOME/common/classes</code>, as well as classes and
      resources in JAR files under
      <code>$CATALINA_HOME/common/lib</code>, are made visible through this
      class loader.  By default, that includes the following:
      <ul>
      <li><em>jndi.jar</em> - The Java Naming and Directory Interface API
          classes (loaded <strong>ONLY</strong> on a JDK 1.2 system, because they
          are included automatically on JDK 1.3 and later).</li>
      <li><em>naming.jar</em> - The JNDI implementation used by Tomcat 4
to
          represent the default JNDI naming context provided to web
          applications.</li>
      <li><em>resources.jar</em> - Resource factory classes for the JNDI
naming
          context that is used internally to represent the static resources of
          a web application.</li>
      <li><em>servlet.jar</em> - The Servlet and JSP API classes.</li>
      </ul></li>
  <li><strong>Catalina</strong> - This class loader is initialized to include
      all classes and resources required to implement Tomcat 4 itself.  These
      classes and resources are <strong>TOTALLY</strong> invisible to web
      applications.  All unpacked classes and resources in
      <code>$CATALINA_HOME/server/classes</code>, as well as classes and
      resources in JAR files under
      <code>$CATALINA_HOME/server/lib</code>, are made visible through
      this class loader.  By default, that includes the following:
      <ul>
      <li><em>catalina.jar</em> - Implementation of the Catalina servlet
          container portion of Tomcat 4.</li>
      <li><em>crimson.jar</em> - Parser portion of the JAXP/1.1 reference
          implementation, used to parse web application deployment descriptor
          (<code>web.xml</code>) files, as well as the server configuration file
          (<code>$CATALINA_HOME/conf/server.xml</code>).</li>
      <li><em>jakarta-regexp-X.Y.jar</em> - The binary distribution of the
          <a href="http://jakarta.apache.org/regexp/">Jakarta Regexp</a>
          regular expression processing library, used in the implementation of
          request filters.</li>
      <li><em>jaxp.jar</em> - JAXP API portion of the JAXP/1.1 reference
          implementation, used to parse web application deployment descriptor
          (<code>web.xml</code>) files, as well as the server configuration file
          (<code>$CATALINA_HOME/conf/server.xml</code>).</li>
      <li><em>warp.jar</em> - Classes for the Java portion of the
          <code>mod_webapp</code> web server connector, which allows Tomcat to
          run behind web servers such as Apache and iPlanet iAS and iWS.</li>
      </ul></li>
  <li><strong>Shared</strong> - This class loader is the place to put classes
      and resources that you wish to share across <strong>ALL</strong>
      web applications (unless Tomcat internal classes also need access, which
      is an unusual case).  All unpacked classes and resources in
      <code>$CATALINA_HOME/classes</code>, as well as classes and resources
      in JAR files under <code>$CATALINA_HOME/lib</code>, are made visible
      through this class loader.  By default, that includes the following:
      <ul>
      <li><em>jasper-runtime.jar</em> - The runtime support classes required
          to execute JSP pages that have already been translated into Java
          servlets and then compiled.</li>
      <li><em>namingfactory.jar</em> - JNDI object factories for resources
          supported by the default JNDI naming context provided to web
          applications.</li>
      </ul></li>
  <li><strong>WebappX</strong> - 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 <code>/WEB-INF/classes</code> directory of
      your web application archive, plus classes and resources in JAR files
      under the <code>/WEB-INF/lib</code> directory of your web application
      archive, are made visible to the containing web application, but to
      no others.</li>
  <li><strong>JasperX</strong> - 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 <code>$CATALINA_HOME/jasper</code>.
      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 <code>Webapp</code> class loader.
      </li>
  </ul>
  
  <p>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 <em>WebappX</em> class loader is processed,
  this class loader will look in the local repositories <strong>first</strong>,
  instead of delegating before looking.  All other class loaders in Tomcat 4
  follow the usual delegation pattern.</p>
  
  <p>Therefore, from the perspective of a web application, class or resource
  loading looks in the following repositories, in this order:</p>
  <ul>
  <li><em>/WEB-INF/classes</em> of your web application</li>
  <li><em>/WEB-INF/lib/*.jar</em> of your web application</li>
  <li>Bootstrap classes of your JVM</li>
  <li>System class loader classses (described above)</li>
  <li><em>$CATALINA_HOME/common/classes</em></li>
  <li><em>$CATALINA_HOME/common/*.jar</em></li>
  <li><em>$CATALINA_HOME/classes</em></li>
  <li><em>$CATALINA_HOME/lib/*.jar</em></li>
  </ul>
  
  </section>
  
  
  <section name="Tomcat 4 and XML Parsers">
  
  <p>Tomcat 4 itself utilizes XML parsing for three processing activities:</p>
  <ul>
  <li>Parsing the <code>server.xml</code> configuration file</li>
  <li>Parsing <code>web.xml</code> deployment descriptors</li>
  <li>Parsing JSP pages in XML syntax</li>
  </ul>
  
  <p>By default, the Java API for XML Processing (Version 1.1) reference
  implementation is utilized for all of these purposes.  However, this parser
  is <strong>not</strong> visible to web applications -- instead, the XML
  parser stored in <code>$CATALINA_HOME/server/lib</code> is used for parsing
  <code>web.xml</code> and <code>server.xml</code> files, while the
parser
  stored in <code>$CATALINA_HOME/jasper</code> is used for parsing JSP pages
  in XML syntax.</p>
  
  <p>To make an XML parser available to your web applications, you have several
  options:</p>
  <ul>
  <li>To utilize an XML parser in a single web application, simply include the
      parser's JAR files in the <code>/WEB-INF/web.xml</code> 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.</li>
  <li>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 <code>$CATALINA_HOME/jasper</code> directory into the
      <code>$CATALINA_HOME/lib</code> directory.  Jasper will continue to use
      this parser for processing JSP pages in XML syntax.</li>
  <li>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
      <code>$CATALINA_HOME/lib</code> directory, and remove "jaxp.jar" and
      "crimson.jar" from the <code>$CATALINA_HOME/jasper</code> directory.
      Jasper will then utilize the new XML parser as well.</li>
  </ul>
  
  <p><strong>WARNING</strong> - 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.</p>
  
  <p><strong>WARNING</strong> - The final release of the JAXP/1.1 reference
  implementation includes JAR files with the <code>sealed</code> 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, <em>modified</em> versions of "jaxp.jar" and "crimson.jar"
  are shipped with Tomcat 4.  You must <strong>NOT</strong> replace these files
  with standard JAXP/1.1 JAR files, until a subsequent JAXP release occurs that
  has the "sealed" attribute removed.</p>
  
  </section>
  
  
  </body>
  
  </document>
  
  
  

Mime
View raw message