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="[EMAIL PROTECTED]">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="[EMAIL PROTECTED]">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="[EMAIL PROTECTED]">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="[EMAIL PROTECTED]">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><servlet></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><servlet-class></code> or
<code><jsp-file></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><jsp:forward></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><jsp:include></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="[EMAIL PROTECTED]">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>
![http://jakarta.apache.org/images/jakarta-logo.gif"](http://jakarta.apache.org/images/jakarta-logo.gif"){kind=link}
