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/catalina/docs/dev/xdocs/stylesheets project.xml
Date Fri, 18 May 2001 20:58:12 GMT
craigmcc    01/05/18 13:58:12

  Added:       catalina/docs/dev/xdocs building.xml classloaders.xml
                        fs-default.xml fs-invoker.xml index.xml
               catalina/docs/dev/xdocs/stylesheets project.xml
  Log:
  Begin converting the Catalina developer docs to XML format, so that they
  can be generated by whatever Anakia-based or XSLT-based generation script
  is selected.
  
  To begin the process of documenting current behavior of Tomcat 4.0
  components (and to provide folks trying to write tests some assertions
  about what correct behavior is), I've provided "Functional Specifications"
  that document the current behavior of the default file-serving servlet and
  the invoker servlet.  Folks working on various portions of Tomcat are
  encouraged to do the same thing for those portions.  This will help us
  build better tests, and also serve as useful information for newcomers to
  the Tomcat source base to understand what is going on.
  
  Revision  Changes    Path
  1.1                  jakarta-tomcat-4.0/catalina/docs/dev/xdocs/building.xml
  
  Index: building.xml
  ===================================================================
  <?xml version="1.0"?>
  <document>
  
    <properties>
      <author email="craigmcc@apache.org">Craig McClanahan</author>
      <title>Building Catalina</title>
      <revision>$Id: building.xml,v 1.1 2001/05/18 20:58:09 craigmcc Exp $</revision>
    </properties>
  
  <body>
  
  
  <section name="Building Catalina">
  
  
    <p>This document outlines the procedures necessary to build Tomcat 4.0
    container from source code.  Tomcat includes the following major
    components:</p>
  
    <ul>
    <li><strong>Catalina</strong> - Servlet container conforming to the
        Servlet Specification, version 2.3 (Proposed Final Draft 2)</li>
    <li><strong>Connectors</strong> - Connectors for web servers</li>
    <li><strong>Jasper</strong> - JSP compiler and runtime environment
        conforming to the JavaServer Pages (JSP) Specification, version
        1.2 (Proposed Final Draft 2)</li>
    <li><strong>Tester</strong> - Unit test web application, with tests
        that focus on Tomcat-specific features as well as specification
        compliance.</li>
    <li><strong>Webapps</strong> - Example web applications, and associated
        documentation, that are packaged with Tomcat.</li>
    </ul>
  
    <p>The overall process of building Tomcat involves the following major
    steps:</p>
    <ul>
    <li>Download and install external prerequisites</li>
    <li>Download and install Jakarta package prerequisites</li>
    <li>Download and install Tomcat source code</li>
    <li>Set environment variables</li>
    <li>Build Tomcat components</li>
    <li>Test and execute your build</li>
    <li>Create binary and source distributions (optional)</li>
    </ul>
  
  </section>
  
  
  <section name="Download External Prerequisites">
  
    <p>You must download and install all of the following external software
    components in order to build Tomcat:</p>
  
    <ul>
    <li><strong>Java Development Kit</strong>:
        <ul>
        <li>Download and install a version of the Java Development Kit
            (version 1.2 or later, version 1.3.1 is recommended) from
            <a href="http://java.sun.com/j2se">http://java.sun.com/j2se</a>.</li>
        <li>Set an environment variable <code>JAVA_HOME</code> containing the
            full pathname of the directory in which Java is installed.</li>
        <li>Make the Java commands available from your shell command line,
            by adding <code>$JAVA_HOME/bin</code> to your <code>PATH</code>
            environment variable.</li>
        </ul></li>
    <li><strong>Java Database Connectors (JDBC) Optional Package</strong>:
        <ul>
        <li>These steps are required <strong>only</strong> if you want to build
            support for the Tyrex JNDI-accessed data source resources.</li>
        <li>Download the JDBC 2.0 Optional Extensions package from
            <a href="http://java.sun.com/products/jdbc">http://java.sun.com/products/jdbc</a>
            and install it.</li>
        <li>Add the full pathname of the <code>jdbc2_0-stdext.jar</code> file
            to your <code>CLASSPATH</code> environment variable.</li>
        </ul>
    <li><strong>JavaMail</strong>:
        <ul>
        <li>These steps are required <strong>only</strong> if you want to build
            the object factories for supporting mail-releated resource entries
            in your web application deployment descriptors.</li>
        <li>Download the JavaMail from
            <a href="http://java.sun.com/products/javamail>http://java.sun.com/products/javamail</a>
            and install it.</li>
        <li>Download the JavaBeans Activation Framework (JAF) from
            <a href="http://java.sun.com/beans/glasgow/jaf.html">http://java.sun.com/beans/glasgow/jaf.html</a>
            and install it.</li>
        <li>Add the full pathnames of the <code>mail.jar</code> and
            <code>activation.jar</code> files from these downloads to
            your <code>CLASSPATH</code> environment variable.</li>
        </ul></li>
    <li><strong>Java Management Extensions (JMX)</strong>:
        <ul>
        <li>Download the JMX "Instrumentation and Agent Reference Implementation"
            (version 1.0 or later) from
            <a href="http://java.sun.com/products/JavaManagement/download.html">http://java.sun.com/products/JavaManagement/download.html</a>
            and install it.</li>
        <li>Set an environment variable <code>JMX_HOME</code> containing the
            full pathname of the directory in which JMX is installed.</li>
        </ul></li>
    <li><strong>Java Naming and Directory Interface (JNDI)</strong>:
        <ul>
        <li>These steps are required <strong>only</strong> if you have
            installed JDK 1.2.  The required JNDI packages are already
            included in JDK 1.3 or later.</li>
        <li>Download the base package of JNDI (version 1.2.1 or later) from
            <a href="http://java.sun.com/products/jndi">http://java.sun.com/products/jndi"</a>.</li>
        <li>Set an environment variable <code>JNDI_HOME</code> containing the
            full pathname of the directory in which JNDI is installed.</li>
        <li>If you wish to compile the JNDIRealm class (which allows users and
            roles to be retrieved from an LDAP-based directory server), you will
            also need to download the corresponding <code>ldap.jar</code> file
            and place it in <code>$JNDI_HOME/lib</code>.</li>
        <li>Add the full pathnames of the <code>jndi.jar</code> and
            (optional) <code>ldap.jar</code> files to your
            <code>CLASSPATH</code> environment variable.</li>
        </ul></li>
    <li><strong>Java Secure Sockets Extension (JSSE)</strong>
        <ul>
        <li>These steps are required <strong>only</strong> if you want to build
            support for SSL connections into Tomcat.</li>
        <li>Download the JSSE package (version 1.0.2 or later) from
            <a href="http://java.sun.com/products/jsse">http://java.sun.com/products/jsse</a>
            and install it.</li>
        <li>Create an environment variable <code>JSSE_HOME</code> containing the
            full pathname of the directory in which JSSE is installed.</li>
        </ul></li>
    <li><strong>Java Transaction Architecture</strong>
        <ul>
        <li>These steps are required <strong>only</strong> if you want to build
            support for the Tyrex JNDI-accessed data source resources.</li>
        <li>Download the JTA package from
            <http://java.sun.com/products/jta">http://java.sun.com/products/jta</a>
            and install it.</li>
        <li>Add the full pathname of the <code>jta-spec1_0_1.jar</code> file
            (or equivalent) to your <code>CLASSPATH</code> environment
            variable.</li>
        </ul></li>
    <li><strong>Tyrex</strong>
        <ul>
        <li>These steps are required <strong>only</strong> if you want to build
            support for the Tyrex JNDI-accessed data source resources.</li>
        <li>Download the Tyrex package from
            <a href="http://tyrex.exolab.org">http://tyrex.exolab.org</a>
            and install it.</li>
        <li>Add the full pathname of the <code>tyrex-0.9.7.0.jar</code> file
            (or equivalent) to your <code>CLASSPATH</code> environment
            variable.</li>
        </ul></li>
    </ul>
    
  
  </section>
  
  
  <section name="Download Jakarta Prerequisites">
  
    <p>You must download and install all of the following packages from the
    <a href="http://jakarta.apache.org">http://jakarta.apache.org</a> web
    site.  It is generally recommended that you use the most recent production
    binary distribution of each of these packages.</p>
  
    <ul>
    <li><strong>Ant</strong> Build Tool</strong>:
        <ul>
        <li>Download and install the latest production release of Ant from
            <a href="http://jakarta.apache.org/site/binindex.html">http://jakarta.apache.org/site/binindex.html</a>.
            You will need version 1.3 or later.</li>
        <li>Set an environment variable <code>ANT_HOME</code> containing the
            full pathname of the directory in which Ant is installed.</li>
        <li>It is recommended that you make the commands in  Ant's
            <code>bin</code> directory available from your shell command line,
            by adding <code>$ANT_HOME/bin</code> to your
            <code>PATH</code> environment variable.  This
            is not currently required, but is likely to be required by later
            changes in the build process.
        </ul></li>
    <li><strong>Regular Expressions Library</strong>:
        <ul>
        <li>Download and install the REGEXP release (version 1.2 or later) from
            <a href="http://jakarta.apache.org/site/binindex.html">http://jakarta.apache.org/site/binindex.html</a>.</li>
        <li>Set an environment variable <code>REGEXP_HOME</code> containing the
            full pathname of the directory in which REGEXP is installed.</li>
        </ul></li>
    <li><strong>Servlet API Classes</strong>:
        <li>Download and install a recent nightly build of the
            <code>jakarta-servletapi-4</code> CVS repository from
            <a href="http://jakarta.apache.org/builds/jakarta-servletapi-4/nightly">http://jakarta.apache.org/builds/jakarta-servletapi-4/nightly</a></li>
        <li>Set an environment variable <code>SERVLETAPI_HOME</code> containing
            the full pathname of the directory where the API classes are
            installed.</li>
        </ul></li>
    </ul>
  
  </section>
  
  
  <section name="Download and Build Tomcat">
  
    <p>You can download a nightly snapshot of the Tomcat 4.0 source repository at
    <a href="http://jakarta.apache.org/builds/jakarta-tomcat-4.0/nightly/src">http://jakarta.apache.org/builds/jakarta-tomcat-4.0/nightly/src</a>
    or follow the directions for
    <a href="http://jakarta.apache.org/site/cvsindex.html>anonymous CVS access</a>
    as described on the Jakarta web site.</p>
  
    <p>After downloading and installing the Tomcat source code, and all of the
    prerequisites listed above, you can build Tomcat by executing the following
    commands (assuming that TOMCAT_HOME is an environment variable containing
    the path to the Tomcat 4.0 source repository directory).</p>
  
    <p>On UNIX platforms:</p>
    <source>
    cd $TOMCAT_HOME
    ./build.sh
    </source>
  
    <p>On Windows platforms:</p>
    <source>
    cd %TOMCAT_HOME%
    build
    </source>
  
    <p>On either platform, this script will use the Ant build tool to create
    a runnable version of Tomcat 4.0 in the <code>TOMCAT_HOME/build</code>
    directory on your computer.</p>
  
  </section>
  
  
  <section name="Executing and Testing Your Build">
  
    <p>To execute Tomcat once you have built it, issue one of the following
    commands (assuming that TOMCAT_HOME is an environment variable containing
    the path to the Tomcat 4.0 source repository directory).</p>
  
    <p>On UNIX platforms:</p>
    <source>
    $TOMCAT_HOME/build/bin/startup.sh
    </source>
  
    <p>On Windows platforms:</p>
    <source>
    %TOMCAT_HOME%\build\bin\startup
    </source>
  
    <p>To shut down Tomcat once you have started it, issue one of the following
    commands (assuming that TOMCAT_HOME is an environment variable containing
    the path to the Tomcat 4.0 source repository directory).</p>
  
    <p>On UNIX platforms:</p>
    <source>
    $TOMCAT_HOME/build/bin/shutdown.sh
    </source>
  
    <p>On Windows platforms:</p>
    <source>
    %TOMCAT_HOME%\build\bin\shutdown
    </source>
  
    <p>You can also compile and install the unit test suite by executing one
    of the following commands (assuming TOMCAT_HOME is an environment variable
    containing the path to the Tomcat 4.0 source repository directory).</p>
  
    <p>On UNIX platforms:</p>
    <source>
    cd $TOMCAT_HOME/tester
    ./build.sh deploy-main
    </source>
  
    <p>On Windows platforms:</p>
    <source>
    cd %TOMCAT_HOME%\tester
    build deploy-main
    </source>
  
    <p>After restarting Tomcat, you can execute the unit test suite by
    executing one of the following commands (assuming TOMCAT_HOME is an
    environment variable containing the path to the Tomcat 4.0 source
    repository directory).</p>
  
    <p>On UNIX platforms:</p>
    <source>
    $TOMCAT_HOME/build/bin/tester.sh
    </source>
  
    <p>On Windows platforms:</p>
    <source>
    %TOMCAT_HOME%\build\bin\tester
    </source>
  
  </section>
  
  
  <section name="Creating Binary and Source Distributions">
  
    <p>To create a complete binary distribution of Tomcat 4.0 (such as for a
    nightly build or a release), execute one of the following commands
    (assuming TOMCAT_HOME is an environment variable containing the path to
    the Tomcat 4.0 source repository directory).</p>
  
    <p>On UNIX platforms:</p>
    <source>
    cd $TOMCAT_HOME
    ./build.sh dist
    </source>
  
    <p>On Windows platforms:</p>
    <source>
    cd %TOMCAT_HOME%
    build dist
    </source>
  
    <p>On either platform, this will create a complete binary distribution in
    the <code>$TOMCAT_HOME/dist</code> directory on your computer.</p>
  
  </section>
  
  
  </body>
  
  </document>
  
  
  
  1.1                  jakarta-tomcat-4.0/catalina/docs/dev/xdocs/classloaders.xml
  
  Index: classloaders.xml
  ===================================================================
  <?xml version="1.0"?>
  <document>
  
    <properties>
      <author email="craigmcc@apache.org">Craig McClanahan</author>
      <title>Catalina Class Loader Hierarchy</title>
      <revision>$Id: classloaders.xml,v 1.1 2001/05/18 20:58:09 craigmcc Exp $</revision>
    </properties>
  
  <body>
  
  
  <section name="Introduction">
  
  <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>
  
  </section>
  
  
  <section name="Overview Diagram">
  
  <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>
  
  <source>
         Bootstrap
             |
          System
             |
          Common
         /      \
    Catalina   Shared
              /     \
          Webapp1  Webapp2 ...  
            /          /
         Jasper1   Jasper2
  </source>
  
  <p>The usage of and repositories contained in each class loader are
  described further below:</p>
  
  <ul>
  <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, and
      contains classes that must be visible to both the Catalina internal
      classes and to web applications.  The standard Catalina startup scripts
      assemble the following repositories for the system class path:
      <ul>
      <li><code>$CATALINA_HOME/bin/bootstrap.jar</code> - The Bootstrap class
          that is used to initialize the Catalina server, and the class
          loader implementation classes it depends on.</li>
      <li><code>$JAVA_HOME/lib/tools.jar</code> - The Javac
          compiler used to compile the servlets generated from JSP pages
          (if present on your system).</li>
      </ul>
  <li><strong>Common</strong> - This class loader is initialized to include all 
      unpacked classes in the <code>$CATALINA_HOME/common/classes</code>
      directory (if it exists), and all JAR files in the
      <code>$CATALINA_HOME/common/lib</code> directory (if it exists).  The
      latter group normally includes the following:
      <ul>
      <li><code>jndi.jar</code> - The Java Naming and Directory Service API
          classes (loaded <strong>only</strong> if not already included in
          the JDK, as they are with JDK 1.3).</li>
      <li><code>naming.jar</code> - The JNDI implementation used by
          Tomcat 4 itself.</li>
      <li><code>servlet.jar</code> - The servlet and JSP API classes.</li>
      </ul></li>
  <li><strong>Catalina</strong> - This class loader is initialized to include all
      unpacked classes in the <code>$CATALINA_HOME/server/classes</code>
      directory (if it exists), and all JAR files in the
      <code>$CATALINA_HOME/server/lib</code> directory (if it exists).  Because
      these classes are loaded from a separate class loader, which is not visible
      to the <strong>Webapp</strong> class loader, they are <em>not</em> visible
      to web applications.</li>
  <li><strong>Shared</strong> - This class loader is initialized to include all
      unpacked classes in the <code>$CATALINA_HOME/classes</code> directory
      (if it exists), and all JAR files in the <code>$CATALINA_HOME/lib</code>
      directory (if it exists).  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>WebappX</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 <strong>Shared</strong>, <strong>Common</strong>,
      <strong>System</strong>, and <strong>Bootstrap</strong> class loaders,
      but <em>not</em> from the <strong>Catalina</strong> or
      <strong>JasperX</strong> class loaders.</li>
  <li><strong>JasperX</strong> - If and only if a web application utilizes
      Jasper to compile and execute JSP pages, an additional class loader is
      created for each web application.  It is initialized to include all JAR
      files in the <code>$CATALINA_HOME/jasper</code> directory, which normally
      includes the Jasper compiler classes and the XML parser that they require.
      Because the parent of this class loader is the <strong>WebappX</strong>
      class loader for this application, the JSP compiler can see all of the
      JavaBean and other classes that are part of this application, but the
      application classes cannot see anything loaded from here (and, in
      particular, will not have access to the XML parser loaded by this
      class loader.</li>
  </ul>
  
  <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 <em>must</em> place a copy of this file in the
  <code>$CATALINA_HOME/lib</code> directory so that it becomes part of the
  <strong>Shared</strong> class loader's repositories.</p>
  
  </section>
  
  
  <section name="Web Application Class Loading Process">
  
  <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>
  
  <ol>
  <li>The <code>loadClass()</code> method of the <strong>WebappX</strong> class
      loader is called to load the specified class.</li>
  <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 class to be loaded is a Java core class (<code>java.*</code>),
      it is loaded directly by the <strong>System</strong> class loader.</li>
  <li>If Catalina is running under a security manager (which is normally the
      case), the class loading permissions in the policy file are checked.  If
      the specified policies prohibit loading the named class, the class loader
      will log the violation attempt and return a
      <code>ClassNotFoundException</code>.</li>
  <li>If this class loader's <code>delegate</code> property is set to
      <code>true</code> (which is <em>not</em> the default), we will ask our
      parent class loader to load this class before looking locally.  This is
      the standard Java2 delegation model, but prevents a web application from
      overriding a class from the <strong>Shared</strong> class loader with its
      own copy from <code>WEB-INF/classes</code> or a JAR file in
      <code>WEB-INF/lib</code>.</li>
  <li>The local repositories are searched next, starting with the
      <code>WEB-INF/classes</code> directory (if it exists), and then the JAR
      files in <code>WEB-INF/lib</code>.</li>
  <li>If we still have not found the class, and did not delegate earlier, we
      delegate to our parent class loader (i.e. the <strong>Shared</strong>
      class loader, which will attempt to load the class itself or delegate
      upwards.  This process continues until the class is found, or we have
      reached the top of the class loader hierarchy.</li>
  <li>If the class has still not been found, <code>ClassNotFoundException</code>
      is thrown, as required by the Javadocs for a class loader.</li>
  </ol>
  
  <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>
  
  </section>
  
  
  <section name="Miscellaneous Notes">
  
  
  <subsection name="Class Loader Information Exposed For Web Applications">
  
  <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>
  <ul>
  <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>
  </ul>
  
  </subsection>
  
  
  <subsection name="A Note on XML Parsers">
  
  <p>Previously, the Jasper page compiler was loaded in the
  <strong>Shared</strong> class loader, along with the XML parser that it
  requires.  This had the side effect of causing this XML parser to be visible
  to all web applications, through the inheritance hierarchy.  However, this
  causes problems if the JAR files of the selected XML parser are sealed (as are
  the JAR files in the JAXP 1.1 reference implementation, for example) -- any
  attempt to load your own XML parser (such as Xerces) from
  <code>WEB-INF/lib</code> would cause "package sealing violation" errors to be
  thrown.</p>
  
  <p>Now that the XML parser required by Jasper is loaded from the
  <strong>JasperX</strong> class loader, rather than the <strong>Shared</strong>
  class loader, this problem no longer occurs.  However, any web application that
  relied on an XML parser being made available by Catalina will fail, because
  this is no longer true by default.  If your web application requires an XML
  parser, you have three choices:</p>
  <ul>
  <li>Place the XML parser's JAR file(s) in the <code>WEB-INF/lib</code>
      directory of your web application.</li>
  <li>Move the XML parser JAR files from the "jasper" directory to the "lib"
      directory so that the parser is visible both to Jasper and to your
      web applications.</li>
  <li>Place the XML parser's JAR file(s) in the <code>$CATALINA_HOME/lib</code>
      directory so that they are available to all web applications.  Note that
      this is likely to introduce "package sealing violation" problems again,
      so this option is only practical if your applications do not require
      JSP pages.</li>
  </ul>
  
  </subsection>
  
  
  <subsection name="Additional Information">
  
  <p>For more information about class loaders in general, see the Java Language
  Specification, and the Javadocs for the following classes:</p>
  <ul>
  <li><code>java.lang.ClassLoader</code>
  <li><code>java.net.URLClassLoader</code>
  </ul>
  
  <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:
  <ul>
  <li><code>org.apache.catalina.loader.StandardClassLoader</code>
  <li><code>org.apache.catalina.loader.Extension</code>
  </ul>
  
  </subsection>
  
  
  </section>
  
  
  </body>
  
  </document>
  
  
  
  1.1                  jakarta-tomcat-4.0/catalina/docs/dev/xdocs/fs-default.xml
  
  Index: fs-default.xml
  ===================================================================
  <?xml version="1.0"?>
  <document>
  
    <properties>
      <author email="craigmcc@apache.org">Craig McClanahan</author>
      <title>Default Servlet - Functional Specification</title>
      <revision>$Id: fs-default.xml,v 1.1 2001/05/18 20:58:09 craigmcc Exp $</revision>
    </properties>
  
  <body>
  
  
  <section name="Overview">
  
  
    <subsection name="Introduction">
  
      <p>The purpose of the <strong>Default Servlet</strong> is to serve
      static resources of a web application in response to client requests.
      As the name implies, it is generally configured as the "default"
      servlet for a web application, by being mapped to a URL pattern "/".</p>
  
    </subsection>
  
  
    <subsection name="External Specifications">
  
      <p>The following external specifications have provisions which
      partially define the correct behavior of the default servlet:</p>
      <ul>
      <li><a href="http://java.sun.com/products/servlet/download.html">
          Servlet Specification</a> (Version 2.3 PFD2)</li>
      <li><a href="http://www.rfc-editor.org/rfc/rfc2046.txt>Multipurpose
          Internet Mail Extensions (MIME) Part Two: Media Types</a></li>
      <li><a href="http://www.rfc-editor.org/rfc/rfc2616.txt>Hypertext
          Transfer Protocol -- HTTP/1.1</a></li>
      </ul>
  
    </subsection>
  
  
    <subsection name="Implementation Requirements">
  
      <p>The implementation of this functionality shall conform to the
      following requirements:</p>
      <ul>
      <li>Must be implemented as a servlet.</li>
      <li>Must support configurable parameters for debugging detail level,
          input buffer size, output buffer size, whether or not to produce
          directory listings when no welcome file is present, and whether or not
          modifications are supported via DELETE and PUT.</li>
      <li>Log debugging and operational messages (suitably internationalized)
          via the <code>getServletContext().log()</code> method.</li>
      </ul>
  
    </subsection>
  
  
  </section>
  
  
  <section name="Dependencies">
  
  
    <subsection name="Environmental Dependencies">
  
      <p>The following environmental dependencies must be met in order for
      the default servlet to operate correctly:</p>
      <ul>
      <li>The default servlet must be registered in the application deployment
          descriptor (or the default deployment descriptor in file
          <code>$CATALINA_HOME/conf/web.xml</code>) using a "default servlet"
          servlet mapping, signified by URL pattern "/".</li>
      </ul>
  
    </subsection>
  
  
    <subsection name="Container Dependencies">
  
      <p>Correct operation of the default servlet depends on the following
      specific features of the surrounding container:</p>
      <ul>
      <li>The container shall provide a servlet context attribute that
          lists the welcome file names that have been defined for this
          web application.</li>
      <li>The container shall provide a servlet context attribute that
          contains a <code>javax.naming.directory.DirContext</code>
          implementation representing the static resources of this
          web application.</li>
      </ul>
  
    </subsection>
  
  
  </section>
  
  
  <section name="Functionality">
  
  
    <subsection name="Initialization Functionality">
  
      <p>The following processing must be performed when the <code>init()</code>
      method of the invoker servlet is called:</p>
      <ul>
      <li>Process and sanity check configuration parameters.</li>
      </ul>
  
    </subsection>
  
  
    <subsection name="Per-Request Functionality">
  
  
      <p>For all HTTP request methods, the resource path is determined from
      the path information provided to this request, either as request attribute
      <code>javax.servlet.include.path_info</code> (for a request dispatcher
      access to a static resource) or by calling
      <code>request.getPathInfo()</code> directly.</p>
  
      <p>On each HTTP DELETE request processed by this servlet, the following
      processing shall be performed:</p>
      <ul>
      <li>If modifications to the static resources are not allowed (set by a
          configuration parameter), return HTTP status 403 (forbidden).</li>
      <li>If an attempt is made to delete a resource from <code>/META-INF</code>
          or <code>/WEB-INF</code>, return HTTP status 403 (forbidden).</li>
      <li>If the requested resource does not exist, return HTTP status 404
          (not found)</li>
      <li>Unbind the resource from the directory context containing the
          static resources for this web application.  If successful, return
          HTTP status 204 (no content).  Otherwise, return HTTP status 405
          (method not allowed).</li>
      </ul>
  
  
      <p>On each HTTP GET request processed by this servlet, the following
      processing shall be performed:</p>
      <ul>
      <li>If the request is for a resource under <code>/META-INF</code> or
          <code>/WEB-INF</code>, return HTTP status 404 (not found).</li>
      <li>If the requested resource does not exist, return HTTP status 404
          (not found).</li>
      <li>If the requested resource is not a directory, but the resource
          path ends in "/" or "\", return HTTP status 404 (not found).</li>
      <li>If the requested resource is a directory:
          <ul>
          <li>If the request path does not end with "/", redirect to a
              corresponding path with "/" appended so that relative references
              in welcome files are resolved correctly.</li>
          <li>If one of the specified welcome files exists, redirect to the
              path for that welcome file so that it will be served explicitly.
              </li>
          </ul>
      <li>If the request being processed contains an <code>If-Range</code>
          header, perform the processing described in the HTTP/1.1 specification
          to determine whether the client's information is up to date.</li>
      <li>Determine the content type of the response, by looking up the
          corresponding MIME type in our servlet context.</li>
      <li>If the requested resource is a directory:
          <ul>
          <li>If directory listings are suppressed, return HTTP status 404
              (not found).</li>
          <li>Set the content type to <code>text/html</code>.</li>
          </ul>
      <li>Determine the range(s) to be returned, based on the existence of
          any <code>If-Range</code> and <code>Range</code> headers.</li>
      <li>If the requested resource is a directory, include an <code>ETag</code>
          header in the response, with the value calculated based on the content
          of the directory.</li>
      <li>Include a <code>Last-Modified</code> header in the response documenting
          the date/time that the resource was last modified.</li>
      <li>Unless we are processing a HEAD request, include the appropriate
          content (or content ranges) in the response.</li>
      </ul>
  
      <p>On each HTTP HEAD request processed by this servlet, the following
      processing shall be performed:</p>
      <ul>
      <li>Processed identically to an HTTP GET request, except that the data
          content is not transmitted after the headers.</li>
      </ul>
  
      <p>On each HTTP POST request processed by this servlet, the following
      processing shall be performed:</p>
      <ul>
      <li>Processed identically to an HTTP GET request.</li>
      </ul>
  
  
      <p>On each HTTP PUT request processed by this servlet, the following
      processing shall be perfomred:</p>
      <ul>
      <li>If modifications to the static resources are not allowed (set by a
          configuration parameter), return HTTP status 403 (forbidden).</li>
      <li>If an attempt is made to delete a resource from <code>/META-INF</code>
          or <code>/WEB-INF</code>, return HTTP status 403 (forbidden).</li>
      <li>Create a new resource from the body of this request.</li>
      <li>Bind or rebind the specified path to the new resource (depending on
          whether it currently exists or not).  Return HTTP status as follows:
          <ul>
          <li>If binding was unsuccessful, return HTTP status 409 (conflict).
              </li>
          <li>If binding was successful and the resource did not previously
              exist, return HTTP status 201 (created).</li>
          <li>If binding was successful and the resource previously existed,
              return HTTP status 204 (no content).</li>
          </ul></li>
      </ul>
  
    </subsection>
  
  
    <subsection name="Finalization Functionality">
  
      <p>No specific processing is required when the <code>destroy()</code>
      method is called:</p>
  
    </subsection>
  
  
  </section>
  
  
  <section name="Testable Assertions">
  
    <p>In addition the the assertions implied by the functionality requirements
    listed above, the following additional assertions shall be tested to
    validate the behavior of the invoker servlet:</p>
    <ul>
    <li>Requests for resources that do not exist in the web application must
        return HTTP status 404 (not found).</li>
    <li>The default servlet must operate identically for web applications that
        are run out of a WAR file directly, or from an unpacked directory
        structure.</li>
    <li>If the web application is running out of an unpacked directory
        structure, the default servlet must recognize cases where the resource
        has been updated through external means.</li>
    </ul>
  
  </section>
  
  
  </body>
  
  </document>
  
  
  
  1.1                  jakarta-tomcat-4.0/catalina/docs/dev/xdocs/fs-invoker.xml
  
  Index: fs-invoker.xml
  ===================================================================
  <?xml version="1.0"?>
  <document>
  
    <properties>
      <author email="craigmcc@apache.org">Craig McClanahan</author>
      <title>Invoker Servlet - Functional Specification</title>
      <revision>$Id: fs-invoker.xml,v 1.1 2001/05/18 20:58:09 craigmcc Exp $</revision>
    </properties>
  
  <body>
  
  
  <section name="Overview">
  
  
    <subsection name="Introduction">
  
      <p>The purpose of the <strong>Invoker Servlet</strong> is to allow a
      web application to dynamically register new <em>servlet definitions</em>
      that correspond with a <code>&lt;servlet&gt;</code> element in the
      <code>/WEB-INF/web.xml</code> deployment descriptor, and execute
      requests utilizing the new servlet definitions.  From the perspective
      of the newly registered servlets, all servlet lifecycle requirements
      of the Servlet Specification (such as calling <code>init()</code> and
      <code>destroy()</code> at the correct times) will be respected.</p>
  
    </subsection>
  
  
    <subsection name="External Specifications">
  
      <p>I do not know of any formal specification of the behavior of an
      invoker servlet that is publicly available.  Anyone know of one?</p>
  
    </subsection>
  
  
    <subsection name="Implementation Requirements">
  
      <p>The implementation of this functionality shall conform to the
      following requirements:</p>
      <ul>
      <li>Implemented as a servlet.</li>
      <li>Exist in the <code>org.apache.catalina.servlets</code> package
          so that it can be loaded by the Catalina class loader.</li>
      <li>Implement the <code>org.apache.catalina.ContainerServlet</code>
          interface, so that it gains knowledge of the <code>Wrapper</code>
          that is responsible for itself and, therefore, access to other
          internal Catalina components.</li>
      <li>Support a configurable debugging detail level.</li>
      <li>Log debugging and operational messages (suitably internationalized)
          via the <code>getServletContext().log()</code> method.</li>
      </ul>
  
    </subsection>
  
  
  </section>
  
  
  <section name="Dependencies">
  
  
    <subsection name="Environmental Dependencies">
  
      <p>The following environmental dependencies must be met in order for
      the Invoker servlet to operate correctly:</p>
      <ul>
      <li>The invoker servlet must be registered in the application deployment
          descriptor (or the default deployment descriptor in file
          <code>$CATALINA_HOME/conf/web.xml</code>) using a "path mapped"
          servlet mapping.  The historical default mapping is to URL pattern
          "<code>/servlet/*</code>", although the invoker servlet must operate
          correctly with an arbitrary mapping.</li>
      </ul>
  
    </subsection>
  
  
    <subsection name="Container Dependencies">
  
      <p>Correct operation of the invoker servlet depends on the following
      specific features of the surrounding container:</p>
      <ul>
      <li>Correct support for the <code>ContainerServlet</code> interface,
          including calling <code>setWrapper()</code> <strong>before</strong>
          the <code>init()</code> method of the invoker servlet is called.</li>
      <li>The web application class loader must be stored as the context
          class loader of the request processing thread.</li>
      </ul>
  
    </subsection>
  
  
  </section>
  
  
  <section name="Functionality">
  
  
    <subsection name="Initialization Functionality">
  
      <p>The following processing must be performed when the <code>init()</code>
      method of the invoker servlet is called:</p>
      <ul>
      <li>Ensure that the container has called <code>setWrapper()</code>.  If
          not, throw a permanent <code>UnavailableException</code>.
      <li>Look up and cache the <code>Context</code> that corresponds to our
          <code>Wrapper</code>.  This is the component with which new servlet
          definitions and mappings will be registered.</li>
      </ul>
  
    </subsection>
  
  
    <subsection name="Per-Request Functionality">
  
      <p>On each request, the following processing shall be performed:</p>
      <ol>
      <li>Calculate the <code>{ServletPath}</code> for this request, either from
          request attribute <code>javax.servlet.include.servlet_path</code> or
          by calling <code>request.getServletPath()</code>.</li>
      <li>Calculate the <code>{PathInfo}</code> for this request, either from
          request attribute <code>javax.servlet.include.path_info</code> or
          by calling <code>request.getPathInfo()</code>.  If the calculated
          <code>{PathInfo}</code> is null, return HTTP status 400
          (bad request).</li>
      <li>Parse the calculated <code>{PathInfo}</code> value as follows:
          <ol>
          <li>Ignore the leading slash character.</li>
          <li>Accumulate characters up to the next '/' (if any) as the
              <code>{ServletSelector}</code>.</li>
          <li>If a '/' was encountered, accumulate all characters from that
              slash (inclusive) to the end of the string as
              <code>{PathRemainder}</code>.  If no slash was encountered,
              set <code>{PathRemainder}</code> to a zero-length string.</li>
          </ol></li>
      <li>Determine whether <code>{ServletSelector}</code> is the name of an
          existing servlet definition, and process it as follows:
          <ol>
          <li>Ask our associated <code>Context</code> to find and return a
              child <code>Wrapper</code> named <code>{ServletSelector}</code>.
              <li>
          <li>If there is no such child, skip to the next major step.</li>
          <li>Register a new servlet mapping for this <code>Wrapper</code>,
              using a URL pattern calculated as follows:
              <code>{ServletPath}</code> + "/" + <code>{ServletSelector}</code>
              + "/*"</li>
          <li>Create a request dispatcher using a path calculated as follows:
              <code>{ServletPath}</code> + "/" + <code>{ServletSelector}</code>
              + <code>{PathRemainder}</code></li>
          <li>Forward this request to the created request dispatcher, and
              exit from this request.</li>
          </ol></li>
      <li>Assume that <code>{ServletSelector}</code> is the fully qualified
          name of a Java class that implements <code>javax.servlet.Servlet</code>
          and process it as follows:
          <ol>
          <li>Synthesize a new <code>{ServletName}</code> for the servlet
              definition that will be created.</li>
          <li>If there is already a child <code>Wrapper</code> associated with
              this name, return HTTP status 500 (internal server error), because
              a mapping should have already been created for this servlet.</li>
          <li>Attempt to load a class named <code>{ServletSelector}</code> from
              the web application class loader (i.e. the context class loader
              for our current thread).  If this fails, return HTTP status 404
              (not found).</li>
          <li>Instantiate an instance of this class.  If an error occurs,
              return HTTP status 404 (not found).</li>
          <li>If this class does not implement the
              <code>javax.servlet.Servlet</code> interface, return HTTP status
              404 (not found).</li>
          <li>Create and register a new <code>Wrapper</code> child with our
              <code>Context</code>, under name <code>{ServletName}</code>.</li>
          <li>Register a new servlet mapping for this <code>Wrapper</code>,
              using a URL pattern calculated as follows:
              <code>{ServletPath}</code> + "/" + <code>{ServletSelector}</code>
              + "/*"</li>
          <li>Create a request dispatcher using a path calculated as follows:
              <code>{ServletPath}</code> + "/" + <code>{ServletSelector}</code>
              + <code>{PathRemainder}</code></li>
          <li>Forward this request to the created request dispatcher, and
              exit from this request.</li>
          </ol></li>
      </ol>
  
    </subsection>
  
  
    <subsection name="Finalization Functionality">
  
      <p>No specific processing is required when the <code>destroy()</code>
      method is called:</p>
  
    </subsection>
  
  
  </section>
  
  
  <section name="Testable Assertions">
  
    <p>In addition the the assertions implied by the functionality requirements
    listed above, the following additional assertions shall be tested to
    validate the behavior of the invoker servlet:</p>
    <ul>
    <li>It is possible to access an existing servlet definition by name
        through the invoker.  The existing servlet definition can include
        either a <code>&lt;servlet-class&gt;</code> or
        <code>&lt;jsp-file&gt;</code> subelement.</li>
    <li>When an existing servlet definition is accessed by name, the request
        will be ultimately processed by the same servlet instance that would
        have processed it had a mapping to that servlet definition been used
        on the request directly.
    <li>It is possible to access an anonymous servlet by class name
        through the invoker.</li>
    <li>When an anonymous servlet is accessed, the servlet instance is processed
        according to the lifecycle requirements of the Servlet Specification.
        </li>
    <li>When an anonymous servlet is accessed, the servlet instance receives
        a <code>ServletConfig</code> instance with no servlet initialization
        parameters.</li>
    <li>It is possible to utilize the invoker servlet via a direct request.</li>
    <li>It is possible to utilize the invoker servlet via a call to
        <code>RequestDispatcher.forward()</code>, or the corresponding
        <code>&lt;jsp:forward&gt;</code> tag in a JSP page.</li>
    <li>It is possible to utilize the invoker servlet via a call to
        <code>RequestDispatcher.include()</code>, or the corresponding
        <code>&lt;jsp:include&gt;</code> tag in a JSP page.</li>
    <li>It is possible to use any HTTP method (including GET and POST) that
        is supported by the Servlet class that is ultimately executed.</li>
    <li>The invoker servlet should never be asked to process a second or
        subsequent request for the same <code>{ServletSelector} (because it
        will have registered an appropriate servlet mapping.</li>
    </ul>
  
  </section>
  
  
  </body>
  
  </document>
  
  
  
  1.1                  jakarta-tomcat-4.0/catalina/docs/dev/xdocs/index.xml
  
  Index: index.xml
  ===================================================================
  <?xml version="1.0"?>
  <document>
  
    <properties>
      <author email="craigmcc@apache.org">Craig McClanahan</author>
      <title>Catalina Developer Documentation</title>
      <revision>$Id: index.xml,v 1.1 2001/05/18 20:58:10 craigmcc Exp $</revision>
    </properties>
  
  <body>
  
  
  <section name="The Catalina Servlet Container">
  
  
    <p><strong>Catalina</strong> is the servlet container portion of
    <a href="http://jakarta.apache.org/tomcat">Tomcat 4.0</a>.  It
    implements the Servlet Specification, version 2.3 (Proposed Final
    Draft 2), which is available for download
    <a href="http://java.sun.com/products/servlet/download.html">here</a>.</p>
  
    <p>The navigation links to the left take you to portions of the
    Catalina documentation that is interesting to developers working on
    enhancing (or fixing bugs in) Tomcat.  In addition, you will find
    the source code of the project to be liberally commented and easy
    to follow, once you become familiar with the overall architecture.</p>
  
  </section>
  
  
  </body>
  
  </document>
  
  
  
  1.1                  jakarta-tomcat-4.0/catalina/docs/dev/xdocs/stylesheets/project.xml
  
  Index: project.xml
  ===================================================================
  <?xml version="1.0" encoding="ISO-8859-1"?>
  <project name="Catalina Developer Documentation"
          href="http://jakarta.apache.org/tomcat/">
  
      <title>Catalina Developer Documentation</title>
      <!-- uncomment and put your project logo here!
      <logo href="http://jakarta.apache.org/images/jakarta-logo.gif">The Jakarta Project</logo>
      -->
      
      <body>
      <menu name="Overview">
          <item name="Front Page"            href="/index.html"/>
  <!--
          <item name="Architecture"          href="FIXME"/>
  -->
          <item name="Building"              href="/building.html"/>
          <item name="Class Loaders"         href="/classloaders.html"/>
  <!--
          <item name="Javadocs"              href="FIXME"/>
          <item name="Source Organization"   href="FIXME"/>
  -->
      </menu>
  
      <menu name="Functional Specs">
          <item name="Default Servlet"       href="/fs-default.html"/>
          <item name="Invoker Servlet"       href="/fs-invoker.html"/>
      </menu>
  
      </body>
  </project>
  
  
  

Mime
View raw message