You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by cr...@apache.org on 2001/07/29 00:54:13 UTC
cvs commit: jakarta-tomcat-4.0/webapps/tomcat-docs/appdev/sample/web/images tomcat.gif
craigmcc 01/07/28 15:54:13
Added: webapps/tomcat-docs index.xml project.xml
webapps/tomcat-docs/appdev build.xml.txt deployment.xml
index.xml installation.xml introduction.xml
processes.xml project.xml source.xml tomcat.gif
web.xml.txt
webapps/tomcat-docs/appdev/sample/docs README.txt
webapps/tomcat-docs/appdev/sample/web hello.jsp index.html
webapps/tomcat-docs/appdev/sample/web/WEB-INF web.xml
webapps/tomcat-docs/appdev/sample/web/images tomcat.gif
Log:
Add the following contents to the "tomcat-docs" web app:
* Application developer's guide (converted from HTML, and updated
for taking advantage of the capabilities of Ant 1.3)
* Servlet/JSP Javadocs (copied from jakarta-servletapi-4/dist/docs/api)
* Catalina and Jasper Javadocs
This conversion has illustrated some clumsiness in trying to use the
"site.xsl" stylesheet from jakarta-site2 directly. Further work is
needed to make that more gracefully.
Revision Changes Path
1.1 jakarta-tomcat-4.0/webapps/tomcat-docs/index.xml
Index: index.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<author email="craigmcc@apache.org">Craig R. McClanahan</author>
<title>Documentation Index</title>
</properties>
<body>
<section name="Introduction">
<p>This is the top-level entry point of the documentation bundle for the
<strong>Tomcat 4</strong> Servlet/JSP container. Tomcat 4 implements the
<a href="http://java.sun.com/products/servlet/">Servlet 2.3</a> and
<a href="http://java.sun.com/products/jsp/">JavaServer Pages 1.2</a>
specifications from Java Software, and includes many additional features that
make it a useful platform for developing and deploying web applications and
web services.</p>
<p>Select one of the links from the navigation menu (to the left) to drill
down to the more detailed documenation that is available. Each available
manual is described in more detail below.</p>
</section>
<section name="Getting Started">
<p>The following documents will assist you in downloading and installing
Tomcat 4, and (if you wish to) building a distribution from the source code.
</p>
<ul>
<li><a href="README.txt"><strong>README.txt</strong></a> - Describes the
contents and directory structure of a Tomcat 4 binary distribution.</li>
<li><a href="RUNNING.txt"><strong>RUNNING.txt</strong></a> - Documents the
steps necessary to download, install, start, and stop a Tomcat 4 server.
</li>
<li><a href="BUILDING.txt"><strong>BUILDING.txt</strong></a> - Details the
steps necessary to download Tomcat 4 source code (and the other packages
that it depends on), and build a binary distribution from those sources.
</li>
</ul>
</section>
<section name="Administrators">
<p>The following documents are aimed at <em>System Administrators</em> who
are responsible for installing, configuring, and operating a Tomcat 4 server.
</p>
</section>
<section name="App Developers">
<p>The following documents are aimed at <em>Application Developers</em> who
are constructing web applications or web services that will run on Tomcat.</p>
<ul>
<li><a href="appdev/index.html"><strong>Application Developer's Guide</strong></a>
- An introduction to the concepts of a <em>web application</em> as defined
in the <a href="http://java.sun.com/products/servlet/download.html">Servlet
2.3 Specification</a>. Covers basic organization of your web application
source tree, the structure of a web application archive, and an
introduction to the web application deployment descriptor
(<code>/WEB-INF/web.xml</code>).</li>
<li><a href="servletapi/index.html"><strong>Servlet/JSP Javadocs</strong></a> -
The Servlet 2.3 and JSP 1.2 API Javadocs.</li>
</ul>
</section>
<section name="Tomcat Developers">
<p>The following documents are for Java developers who wish to contribute to
the development of Tomcat itself, or to better understand its internal
architecture and operation.</p>
<ul>
<li><a href="catalina/docs/api/index.html"><strong>Catalina Javadocs</strong></a>
- Javadoc API documentation for the <em>Catalina</em> servlet container
portion of Tomcat 4.</li>
<li><a href="jasper/docs/api/index.html"><strong>Jasper Javadocs</strong></a>
- Javadoc API documentation for the <em>Jasper</em> JSP container
portion of Tomcat 4.</li>
</ul>
</section>
</body>
</document>
1.1 jakarta-tomcat-4.0/webapps/tomcat-docs/project.xml
Index: project.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<project name="Tomcat Documentation - Top Level Directory"
href="http://jakarta.apache.org/tomcat/">
<title>The Tomcat 4 Servlet/JSP Container</title>
<logo href="http://jakarta.apache.org/tomcat/images/tomcat.gif">
The Tomcat Servlet/JSP Container
</logo>
<body>
<menu name="Getting Started">
<item name="Docs Home" href="/index.html"/>
<item name="READ ME" href="/README.txt"/>
<item name="Install and Run" href="/RUNNING.txt"/>
<item name="Building from Source" href="/BUILDING.txt"/>
</menu>
<menu name="Administrators">
<!--
<item name="Configuration" href="/config/index.html"/>
-->
</menu>
<menu name="App Developers">
<item name="App Developer Guide" href="/appdev/index.html"/>
<item name="Servlet/JSP Javadocs" href="/servletapi/index.html"/>
</menu>
<menu name="Tomcat Developers">
<item name="Catalina Javadocs" href="/catalina/docs/api/index.html"/>
<item name="Jasper Javadocs" href="/jasper/docs/api/index.html"/>
</menu>
</body>
</project>
1.1 jakarta-tomcat-4.0/webapps/tomcat-docs/appdev/build.xml.txt
Index: build.xml.txt
===================================================================
<!-- A "project" describes a set of targets that may be requested
when Ant is executed. The "default" attribute defines the
target which is executed if no specific target is requested,
and the "basedir" attribute defines the current working directory
from which Ant executes the requested task. This is normally
set to the current working directory.
-->
<project name="My Project" default="compile" basedir=".">
<!-- ===================== Property Definitions =========================== -->
<!--
Each of the following properties are used in the build script.
Values for these properties are set by the first place they are
defined, from the following list:
* Definitions on the "ant" command line (ant -Ddeploy.home=xyz compile)
* Definitions from a "build.properties" file in the top level
source directory
* Definitions from a "build.properties" file in the developer's
home directory
* Default definitions in this build.xml file
You will note below that property values can be composed based on the
contents of previously defined properties. This is a powerful technique
that helps you minimize the number of changes required when your development
environment is modified. Note that property composition is allowed within
"build.properties" files as well as in the "build.xml" script.
-->
<!-- ==================== File and Directory Names ======================== -->
<!--
These properties generally define file and directory names (or paths) that
affect where the build process stores its outputs.
app.name Base name of this application, used to
construct filenames and directories.
Defaults to "myapp".
app.version Version identifier for this application.
build.home The directory into which the "prepare" and
"compile" targets will generate their output.
Defaults to "build".
catalina.home The directory in which you have installed
a binary distribution of Tomcat 4. This will
be used by the "deploy" target.
deploy.home The name of the directory into which the
deployment hierarchy will be created, and into
which the build directory will be copied.
Defaults to "${catalina.home}/webapps/${app.name}".
dist.home The name of the base directory in which
distribution files are created.
Defaults to "dist".
-->
<property name="app.name" value="myapp"/>
<property name="app.version" value="1.0"/>
<property name="build.home" value="build"/>
<property name="catalina.home" value="../../../.."/> <!-- UPDATE THIS! -->
<property name="deploy.home" value="${catalina.home}/webapps/${app.name}"/>
<property name="dist.home" value="dist"/>
<!-- ==================== Compilation Control Options ==================== -->
<!--
These properties control option settings on the Javac compiler when it
is invoked using the <javac> task.
compile.debug Should compilation include the debug option?
compile.deprecation Should compilation include the deprecation option?
compile.optimize Should compilation include the optimize option?
-->
<property name="compile.debug" value="true"/>
<property name="compile.deprecation" value="false"/>
<property name="compile.optimize" value="true"/>
<!-- ==================== External Dependencies =========================== -->
<!--
Use property values to define the locations of external JAR files on which
your application will depend. In general, these values will be used for
two purposes:
* Inclusion on the classpath that is passed to the Javac compiler
* Being copied into the "/WEB-INF/lib" directory during execution
of the "deploy" target.
For the purposes of this example, the "servlet.jar" property should be set
to the pathname of the "servlet.jar" file included in your Tomcat 4 release.
It is included on the compiler classpath (because this is required in order
to compile a servlet), but is not copied to the deployment directory because
servlet containers already provide it at runtime.
This example also includes a dummy "foo.jar" property, used to illustrate
where you would make customizations for your own external dependencies
in order to use them for compilation and/or deployment.
-->
<!-- Dummy external dependency -->
<!--
<property name="foo.jar"
value="/path/to/foo.jar"/>
-->
<property name="servlet.jar"
value="${catalina.home}/common/lib/servlet.jar"/>
<!-- ==================== Compilation Classpath =========================== -->
<!--
Rather than relying on the CLASSPATH environment variable, Ant includes
features that makes it easy to dynamically construct the classpath you
need for each compilation. The example below constructs the compile
classpath to include the servlet.jar file, and includes comments on where
you would insert your own additional JAR files. Such references should
be based on external dependency properties, as described above, so that
you can customize the actual location of the JAR files using build.properties
files.
-->
<path id="compile.classpath">
<!-- Include for the servlet.jar file -->
<pathelement location="${servlet.jar}"/>
<!-- Dummy include for our foo.jar file -->
<!--
<pathelement location="${foo.jar}"/>
-->
</path>
<!-- ==================== All Target ====================================== -->
<!--
The "all" target is a shortcut for running the "clean" target followed
by the "compile" target, to force a complete recompile.
-->
<target name="all" depends="clean,compile"
description="Clean build and dist, then compile"/>
<!-- ==================== Clean Target ==================================== -->
<!--
The "clean" target deletes any previous "build" and "dist" directory,
so that you can be ensured the application can be built from scratch.
-->
<target name="clean"
description="Delete old build and dist directories">
<delete dir="${build.home}"/>
<delete dir="${dist.home}"/>
</target>
<!-- ==================== Compile Target ================================== -->
<!--
The "compile" target transforms source files (from your "src" directory)
into object files in the appropriate location in the build directory.
This example assumes that you will be including your classes in an
unpacked directory hierarchy under "/WEB-INF/classes".
-->
<target name="compile" depends="prepare"
description="Compile Java sources">
<!-- Compile Java classes as necessary -->
<mkdir dir="${build.home}/WEB-INF/classes"/>
<javac srcdir="src"
destdir="${build.home}/WEB-INF/classes"
debug="${compile.debug}"
deprecation="${compile.deprecation}"
optimize="${compile.optimize}">
<classpath refid="compile.classpath"/>
</javac>
<!-- Copy associated resource files -->
<copy todir="${build.home}/library/classes">
<fileset dir="src" includes="**/*.properties"/>
</copy>
</target>
<!-- ==================== Deploy Target =================================== -->
<!--
The "deploy" target copies the contents of the build directory into a
location required by our servlet container, and picks up any external
dependencies along the way. AFter restarting the servlet container, you
can now test your web application.
-->
<target name="deploy" depends="compile"
description="Deploy application to servlet container">
<!-- Copy the contents of the build directory -->
<mkdir dir="${deploy.home}"/>
<copy todir="${deploy.home}">
<fileset dir="${build.home}"/>
</copy>
<!-- Pick up external dependencies as required -->
<mkdir dir="${deploy.home}/WEB-INF/lib"/>
<!--
<copy tofile="${deploy.home}/WEB-INF/lib/foo.jar"
file="${foo.jar}"/>
-->
</target>
<!-- ==================== Dist Target ===================================== -->
<!--
The "dist" target creates a binary distribution of your application
in a directory structure ready to be archived in a tar.gz or zip file.
Note that this target depends on two others:
* "deploy" so that the entire web application (including external
dependencies) will have been assembled
* "javadoc" so that the application Javadocs will have been created
-->
<target name="dist" depends="deploy,javadoc"
description="Create binary distribution">
<!-- Copy documentation subdirectory -->
<copy todir="${dist.home}/docs">
<fileset dir="docs"/>
</copy>
<!-- Create application JAR file -->
<jar jarfile="${dist.home}/${app.name}.war"
basedir="${deploy.home}"/>
<!-- Copy additional files to ${dist.home} as necessary -->
</target>
<!-- ==================== Javadoc Target ================================== -->
<!--
The "javadoc" target creates Javadoc API documentation for the Java
classes included in your application. Normally, this is only required
when preparing a distribution release, but is available as a separate
target in case the developer wants to create Javadocs independently.
-->
<target name="javadoc" depends="compile"
description="Create Javadoc API documentation">
<mkdir dir="${dist.home}/docs/api"/>
<javadoc sourcepath="src"
destdir="${dist.home}/docs/api"
packagenames="mypackage.*"/>
</target>
<!-- ==================== Prepare Target ================================== -->
<!--
The "prepare" target is used to create the "build" destination directory,
and copy the static contents of your web application to it. If you need
to copy static files from external dependencies, you can customize the
contents of this task.
Normally, this task is executed indirectly when needed.
-->
<target name="prepare">
<!-- Create build directory and copy static content -->
<mkdir dir="${build.home}"/>
<copy todir="${build.home}">
<fileset dir="web"/>
</copy>
<!-- Copy static files from external dependencies as needed -->
</target>
</project>
1.1 jakarta-tomcat-4.0/webapps/tomcat-docs/appdev/deployment.xml
Index: deployment.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<author email="craigmcc@apache.org">Craig R. McClanahan</author>
<title>Deployment</title>
</properties>
<body>
<section name="Background">
<p>Before describing how to organize your source code directories,
it is useful to examine the runtime organization of a web application.
Prior to the Servlet API Specification, version 2.2, there was little
consistency between server platforms. However, servers that conform
to the 2.2 (or later) specification are required to accept a
<em>Web Application Archive</em> in a standard format, which is discussed
further below.</p>
<p>A web application is defined as a hierarchy of directories and files
in a standard layout. Such a hierarchy can be accessed in its "unpacked"
form, where each directory and file exists in the filesystem separately,
or in a "packed" form known as a Web ARchive, or WAR file. The former format
is more useful during development, while the latter is used when you
distribute your application to be installed.</p>
<p>The top-level directory of your web application hierarchy is also the
<em>document root</em> of your application. Here, you will place the HTML
files and JSP pages that comprise your application's user interface. When the
system administrator deploys your application into a particular server, he
or she assigns a <em>context path</em> to your application (a later section
of this manual describes deployment on Tomcat). Thus, if the
system administrator assigns your application to the context path
<code>/catalog</code>, then a request URI referring to
<code>/catalog/index.html</code> will retrieve the <code>index.html</code>
file from your document root.</p>
</section>
<section name="Standard Directory Layout">
<p>To facilitate creation of a Web Application Archive file in the required
format, it is convenient to arrange the "executable" files of your web
application (that is, the files that Tomcat actually uses when executing
your app) in the same organization as required by the WAR format itself.
To do this, you will end up with the following contents in your
application's "document root" directory:</p>
<ul>
<li><strong>*.html, *.jsp, etc.</strong> - The HTML and JSP pages, along
with other files that must be visible to the client browser (such as
JavaScript, stylesheet files, and images) for your application.
In larger applications you may choose to divide these files into
a subdirectory hierarchy, but for smaller apps, it is generally
much simpler to maintain only a single directory for these files.
<br/><br/></li>
<li><strong>/WEB-INF/web.xml</strong> - The <em>Web Application Deployment
Descriptor</em> for your application. This is an XML file describing
the servlets and other components that make up your application,
along with any initialization parameters and container-managed
security constraints that you want the server to enforce for you.
This file is discussed in more detail in the following subsection.
<br/><br/></li>
<li><strong>/WEB-INF/classes/</strong> - This directory contains any Java
class files (and associated resources) required for your application,
including both servlet and non-servlet classes, that are not combined
into JAR files. If your classes are organized into Java packages,
you must reflect this in the directory hierarchy under
<code>/WEB-INF/classes/</code>. For example, a Java class named
<code>com.mycompany.mypackage.MyServlet</code>
would need to be stored in a file named
<code>/WEB-INF/classes/com/mycompany/mypackage/MyServlet.class</code>.
<br/><br/></li>
<li><strong>/WEB-INF/lib/</strong> - This directory contains JAR files that
contain Java class files (and associated resources) required for your
application, such as third party class libraries or JDBC drivers.</li>
</ul>
<p>When you install an application into Tomcat (or any other
2.2/2.3-compatible server), the classes in the <code>WEB-INF/classes/</code>
directory, as well as all classes in JAR files found in the
<code>WEB-INF/lib/</code> directory, are made visible to other classes
within your particular web application. Thus, if
you include all of the required library classes in one of these places (be
sure to check licenses for redistribution rights for any third party libraries
you utilize), you will simplify the installation of your web application --
no adjustment to the system class path (or installation of global library
files in your server) will be necessary.</p>
<p>Much of this information was extracted from Chapter 9 of the Servlet
API Specification, version 2.3, which you should consult for more details.</p>
</section>
<section name="Web Application Deployment Descriptor">
<p>As mentioned above, the <code>/WEB-INF/web.xml</code> file contains the
Web Application Deployment Descriptor for your application. As the filename
extension implies, this file is an XML document, and defines everything about
your application that a server needs to know (except the <em>context path</em>,
which is assigned by the system administrator when the application is
deployed).</p>
<p>The complete syntax and semantics for the deployment descriptor is defined
in Chapter 13 of the Servlet API Specification, version 2.3. Over time, it
is expected that development tools will be provided that create and edit the
deployment descriptor for you. In the meantime, to provide a starting point,
a <a href="web.xml.txt" target="_new">basic web.xml file</a>
is provided. This file includes comments that describe the purpose of each
included element.</p>
<p><strong>NOTE</strong> - The Servlet Specification includes a Document
Type Descriptor (DTD) for the web application deployment descriptor, and
Tomcat 4 enforces the rules defined here when processing your application's
<code>/WEB-INF/web.xml</code> file. In particular, you <strong>must</strong>
enter your descriptor elements (such as <code><filter></code>,
<code><servlet></code>, and <code><servlet-mapping></code> in
the order defined by the DTD (see Section 13.3).</p>
</section>
<section name="Deployment With Tomcat 4">
<p>In order to be executed, a web application must be deployed on
a servlet container. This is true even during development.
We will describe using Tomcat 4 to provide the execution environment.
A web application can be deployed in Tomcat by one of three different
approaches:</p>
<ul>
<li><em>Copy unpacked directory hierarchy into a subdirectory in directory
<code>$CATALINA_HOME/webapps/</code></em>. Tomcat will assign a
context path to your application based on the subdirectory name you
choose. We will use this technique in the <code>build.xml</code>
file that we construct, because it is the quickest and easiest approach
during development. Be sure to restart Tomcat after installing or
updating your application.
<br/><br/></li>
<li><em>Copy the web application archive file into directory
<code>$CATALINA_HOME/webapps/</code></em>. When Tomcat is started, it will
automatically expand the web application archive file into its unpacked
form, and execute the application that way. This approach would typically
be used to install an additional application, provided by a third party
vendor or by your internal development staff, into an existing
Tomcat installation. <strong>NOTE</strong> - If you use this approach,
and wish to update your application later, you must both replace the
web application archive file <strong>AND</strong> delete the expanded
directory that Tomcat created, and then restart Tomcat, in order to reflect
your changes.
<br/><br/></li>
<li><em>Use the Tomcat 4 "Manager" web application to deploy and undeploy
web applications</em>. Tomcat 4 includes a web application, deployed
by default on context path <code>/manager</code>, that allows you to
deploy and undeploy applications on a running Tomcat server without
restarting it. See the administrator documentation (TODO: hyperlink)
for more information on using the Manager web application.<br/><br/></li>
<li><em>Add a <code><Context></code> entry in the
<code>$CATALINA_HOME/conf/server.xml</code> configuration file</em>.
This approach is described briefly below, and allows you to position
the document root of your web application at some point other than the
<code>$CATALINA_HOME/webapps/</code> directory. You will need to restart
Tomcat to have changes in this configuration file take effect. See the
administrator documentation (TODO: hyperlink) for more information on
configuring new Contexts in this way.</li>
</ul>
<p>Deploying your app on other servlet containers will be specific to each
container, but all containers compatible with the Servlet API Specification
(version 2.2 or later) are required to accept a web application archive file.
Note that other containers are <strong>NOT</strong> required to accept an
unpacked directory structure (as Tomcat does), but this feature is commonly
available.</p>
</section>
</body>
</document>
1.1 jakarta-tomcat-4.0/webapps/tomcat-docs/appdev/index.xml
Index: index.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<author email="craigmcc@apache.org">Craig R. McClanahan</author>
<title>Table of Contents</title>
</properties>
<body>
<section name="Preface">
<p>This manual includes contributions from many members of the Tomcat Project
developer community. The following authors have provided significant content:
</p>
<ul>
<li>Craig R. McClanahan
(<a href="mailto:craigmcc@apache.org">craigmcc@apache.org</a>)</li>
</ul>
</section>
<section name="Table of Contents">
<p>The information presented is divided into the following sections:</p>
<ul>
<li><a href="introduction.html"><strong>Introduction</strong></a> -
Briefly describes the information covered here, with
links and references to other sources of information.</li>
<li><a href="installation.html"><strong>Installation</strong></a> -
Covers acquiring and installing the required software
components to use Tomcat for web application development.</li>
<li><a href="deployment.html"><strong>Deployment Organization</strong></a> -
Discusses the standard directory layout for a web application
(defined in the Servlet API Specification), the Web Application
Deployment Descriptor, and options for integration with Tomcat
in your development environment.</li>
<li><a href="source.html"><strong>Source Organization</strong></a> -
Describes a useful approach to organizing the source code
directories for your project, and introduces the
<code>build.xml</code> used by Ant to manage compilation.</li>
<li><a href="processes.html"><strong>Development Processes</strong></a> -
Provides brief descriptions of typical development processes
utilizing the recommended deployment and source organizations.</li>
<li><a href="sample/" target="_new"><strong>Example Application</strong></a> -
This directory contains a very simple, but functionally complete,
"Hello, World" application built according to the principles
described in this manual. You can use this application to
practice using the described techniques.</li>
</ul>
</section>
</body>
</document>
1.1 jakarta-tomcat-4.0/webapps/tomcat-docs/appdev/installation.xml
Index: installation.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<author email="craigmcc@apache.org">Craig R. McClanahan</author>
<title>Installation</title>
</properties>
<body>
<section name="Installation">
<p>In order to use Tomcat 4 for developing web applications, you must first
install it (and the software it depends on). The required steps are outlined
in the following subsections.</p>
<subsection name="JDK">
<p>Tomcat will operate under any <strong>Java Development Kit</strong> (JDK)
environment that provides a JDK 1.2 (also known as Java2 Standard Edition, or
J2SE) or later platform. You will need a Java Development Kit, as opposed to a
Java Runtime Environment, so that your servlets, other classes, and JSP pages
can be compiled. Tomcat 4 has been extensively tested with JDK 1.3.1, which
is recommended.</p>
<p>Compatible JDKs for many platforms (or links to where they can be found)
are available at
<a href="http://java.sun.com/j2se/">http://java.sun.com/j2se/</a>.</p>
</subsection>
<subsection name="Tomcat">
<p>Binary downloads of the <strong>Tomcat</strong> server are available from
<a href="http://jakarta.apache.org/downloads/binindex.html">http://jakarta.apache.org/downloads/binindex.html</a>.
This manual assumes you are using the most recent release
of Tomcat 4. Detailed instructions for downloading and installing
Tomcat 4 are available <a href="../RUNNING.txt">here</a>.</p>
<p>In the remainder of this manual, example shell scripts assume that you have
set an environment variable <code>CATALINA_HOME</code> that contains the
pathname to the directory in which Tomcat 4 has been installed.</p>
</subsection>
<subsection name="Ant">
<p>Binary downloads of the <strong>Ant</strong> build tool are available from
<a href="http://jakarta.apache.org/downloads/binindex.html">http://jakarta.apache.org/downloads/binindex.html</a>.
This manual assumes you are using Ant 1.3. The instructions should
also be compatible with later versions, but this has not been tested.</p>
<p>Download and install Ant from the distribution directory mentioned above.
Then, add the <code>bin</code> directory of the Ant distribution to your
<code>PATH</code> environment variable, following the standard practices for
your operating system platform. Once you have done this, you will be able to
execute the <code>ant</code> shell command directly.</p>
</subsection>
<subsection name="CVS">
<p>Besides the required tools described above, you are strongly encouraged
to download and install a <em>source code control</em> system, such as the
<strong>Concurrent Version System</strong> (CVS), to maintain historical
versions of the source files that make up your web application. Besides
the server, you will also need appropriate client
tools to check out source code files, and check in modified versions.</p>
<p>Detailed instructions for installing and using source code control
applications is beyond the scope of this manual. However, CVS server and
client tools for many platforms (along with documentation) can be downloaded
from <a href="http://www.cvshome.org">http://www.cvshome.org</a>.</p>
</subsection>
</section>
</body>
</document>
1.1 jakarta-tomcat-4.0/webapps/tomcat-docs/appdev/introduction.xml
Index: introduction.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<author email="craigmcc@apache.org">Craig R. McClanahan</author>
<title>Introduction</title>
</properties>
<body>
<section name="Overview">
<p>Congratulations! You've decided to (or been told to) learn how to
build web applications using servlets and JSP pages, and picked the
Tomcat server to use for your learning and development. But now what
do you do?</p>
<p>This manual is a primer covering the basic steps of using Tomcat to
set up a development environment, organize your source code, and then
build and test your application. It does not discuss architectures or
recommended coding practices for web application development,
or provide in depth instructions on operating the development
tools that are discussed. References to sources of additional information
are included in the following subsections.</p>
<p>The discussion in this manual is aimed at developers who will be using
a text editor along with command line tools to develop and debug their
applications. As such, the recommendations are fairly generic -- but you
should easily be able to apply them in either a Windows-based or Unix-based
development environment. If you are utilizing an Interactive Development
Environment (IDE) tool, you will need to adapt the advice given here to
the details of your particular environment.</p>
</section>
<section name="Links">
<p>The following links provide access to selected sources of online
information, documentation, and software that is useful in developing
web applications with Tomcat.</p>
<ul>
<li><a href="http://java.sun.com/products/jsp/download.html">http://java.sun.com/products/jsp/download.html</a> -
<i>JavaServer Pages (JSP) Specfication, Version 1.2</i>. Describes
the programming environment provided by standard implementations
of the JavaServer Pages (JSP) technology. In conjunction with
the Servlet API Specification (see below), this document describes
what a portable API page is allowed to contain. Specific
information on scripting (Chapter 6), tag extensions (Chapter 7),
and packaging JSP pages (Appendix A) is useful. The Javadoc
API Documentation is included in the specification, and with the
Tomcat download.<br/><br/></li>
<li><a href="http://java.sun.com/products/servlet/download.html">http://java.sun.com/products/servlet/download.html</a> -
<i>Servlet API Specification, Version 2.3</i>. Describes the
programming environment that must be provided by all servlet
containers conforming to this specification. In particular, you
will need this document to understand the web application
directory structure and deployment file (Chapter 9), methods of
mapping request URIs to servlets (Chapter 11), container managed
security (Chapter 12), and the syntax of the <code>web.xml</code>
Web Application Deployment Descriptor (Chapter 13). The Javadoc
API Documentation is included in the specification, and with the
Tomcat download.<br/><br/></li>
<li><a href="http://java.sun.com/j2ee/blueprints/">http://java.sun.com/j2ee/blueprints/</a> -
<i>Sun BluePrints (tm) Design Guidelines for J2EE</i>. Comprehensive
advice and examples on application design for the Java2 Enterprise
Edition (J2EE) platform, which includes servlets and JSP pages. The
chapters on servlet and JSP design are useful even when your application
does not require other J2EE platform components.
<br/><br/></li>
<li><b>TODO</b> -- Add more entries here!</li>
</ul>
</section>
</body>
</document>
1.1 jakarta-tomcat-4.0/webapps/tomcat-docs/appdev/processes.xml
Index: processes.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<author email="craigmcc@apache.org">Craig R. McClanahan</author>
<title>Development Processes</title>
</properties>
<body>
<section name="Development Processes">
<p>Although application development can take many forms, this manual proposes
a fairly generic process for creating web applications using Tomcat. The
following sections highlight the commands and tasks that you, as the developer
of the code, will perform. The same basic approach works when you have
multiple programmers involved, as long as you have an appropriate source code
control system and internal team rules about who is working on what parts
of the application at any given time.</p>
<p>The task descriptions below assume that you will be using CVS for source
code control, and that you have already configured access to the appropriate
CVS repository. Instructions for doing this are beyond the scope of this
manual. If you are using a different source code control environment, you
will need to figure out the corresponding commands for your system.</p>
<subsection name="Create Project Source Code Directory">
<p>The first step is to create a new project source directory, and customize
the <code>build.xml</code> and build script you will be using. The directory
structure is described in <a href="source.html">the previous section</a>,
or you can use the <a href="sample">sample application</a> as a starting
point.</p>
<p>Create your project source directory, and define it within your CVS
repository. This might be done by a series of commands like this, where
<code>{project}</code> is the name under which your project should be
stored in the CVS repository, and {username} is your login username:</p>
<source>
cd {my home directory}
mkdir myapp <-- Assumed "project source directory"
cd myapp
mkdir docs
mkdir src
mkdir web
mkdir web/WEB-INF
cvs import -m "Initial Project Creation" {project} \
{username} start
</source>
<p>Now, to verify that it was created correctly in CVS, we will perform a
checkout of the new project:</p>
<source>
cd ..
mv myapp myapp.bu
cvs checkout {project}
</source>
<p>Next, you will need to create and check in an initial version of the
<code>build.xml</code> script to be used for development. For getting
started quickly and easily, base your <code>build.xml</code> on the
<a href="build.xml.txt">basic build.xml file</a>, included with this manual,
or code it from scratch.</p>
<source>
cd {my home directory}
cd myapp
emacs build.xml <-- if you want a real editor :-)
cvs add build.xml
cvs commit
</source>
<p>Until you perform the CVS commit, your changes are local to your own
development directory. Committing makes those changes visible to other
developers on your team that are sharing the same CVS repository.</p>
<p>Now, create the initial version of the web application deployment
descriptor. You can base <code>web.xml</code> on the
<a href="web.xml.txt">basic web.xml file</a>, or code it from scratch.</p>
<source>
cd {my home directory}
cd myapp/WEB-INF
emacs web.xml
cvs add web.xml
cvs commit
</source>
</subsection>
<subsection name="Customize for Tomcat Location">
<p>In order for Tomcat to recognize your application, you must deploy it
as described under <a href="deployment.html">Deployment</a>. Any of the
proposed techniques can be used. For our purposes, we will assume that
you are using the <em>unpacked directory hierarchy</em> approach, and a
<code>build.xml</code> script based on the example included with this manual.
</p>
<p>In order to successfully execute the <code>deploy</code> target, you
must ensure that the <code>catalina.home</code> property receives the
correct value, which must be the pathname of the directory into which you
have installed Tomcat 4. You can make this customization by one of the
following techniques:</p>
<ul>
<li>Change the property definition in the <code>build.xml</code> file so
that it reflects the Tomcat 4 location. The modified property setting
might look like this:
<source>
<property name="catalina.home" value="/usr/local/jakarta-tomcat-4.0"/>
</source></li>
<li>Set up a <code>build.properties</code> file in your top-level source
directory that defines the location oF Tomcat. For example, the file
might contain:
<source>
catalina.home=/usr/local/jakarta-tomcat-4.0
</source></li>
</ul>
<p>The first technique would be appropriate if all of your developers are
sharing a common copy of Tomcat 4 for their deployment and testing. If,
however, each developer is using their own copy of Tomcat 4, in separate
directories, the latter technique is preferred (because it lets each
developer define their own value for the <code>catalina.home</code>
property.</p>
<p><strong>NOTE</strong> - If you utilize the <code>build.properties</code>
approach, be sure that you do <strong>NOT</strong> check in the
<code>build.properties</code> file for any of your developers in to the
source code archives. For this reason, the <code>.cvsignore</code> file
you created earlier should include this filename.</p>
</subsection>
<subsection name="Edit Source Code and Pages">
<p>The edit/build/test tasks will generally be your most common activities
during development and maintenance. The following general principles apply.
As described in <a href="source.html">Source Organization</a>, newly created
source files should be located in the appropriate subdirectory, under your
project source directory.</p>
<p>Whenever you wish to refresh your development directory to reflect the
work performed by other developers, you will ask CVS to do it for you:</p>
<source>
cd {my home directory}
cd myapp
cvs update -dP
</source>
<p>To create a new file, go to the appropriate directory, create the file,
and register it with CVS. When you are satisfied with it's contents (after
building and testing is successful), commit the new file to the repository.
For example, to create a new JSP page:</p>
<source>
cd {my home directory}
cd myapp/web <-- Ultimate destination is document root
emacs mypage.jsp
cvs add mypage.jsp
... build and test the application ...
cvs commit
</source>
<p>Java source code that is defined in packages must be organized in a
directory hierarchy (under the <strong>src/</strong> subdirectory) that
matches the package names. For example, a Java class named
<code>com.mycompany.mypackage.MyClass.java</code> should be stored in file
<code>src/com/mycompany/mypackage/MyClass.java</code>.
Whenever you create a new subdirectory, don't forget to
register it with CVS.</p>
<p>To edit an existing source file, you will generally just start editing
and testing, then commit the changed file when everything works. Although
CVS can be configured to required you to "check out" or "lock" a file you
are going to be modifying, this is generally not used.</p>
</subsection>
<subsection name="Build the Web Application">
<p>When you are ready to compile the application, issue the following
commands (generally, you will want a shell window open that is set to
the project source directory, so that only the last command is needed):</p>
<source>
cd {my home directory}
cd myapp <-- Normally leave a window open here
ant
</source>
<p>The Ant tool will be execute the default "compile" target in your
<code>build.xml</code> file, which will compile any new or updated Java
code. If this is the first time you compile after a "build clean",
it will cause everything to be recompiled.</p>
<p>To force the recompilation of your entire application, do this instead:</p>
<source>
cd {my home directory}
cd myapp
ant all
</source>
<p>This is a very good habit immediately before checking in changes, to
make sure that you have not introduced any subtle problems that Javac's
conditional checking did not catch.</p>
</subsection>
<subsection name="Test Your Web Application">
<p>To test your application, you will want to deploy it under Tomcat. If you
have customized the <code>catalina.home</code> property as described above,
this is very easy. First, deploy the application into Tomcat:</p>
<source>
cd {my home directory}
cd myapp
ant deploy
</source>
<p>and then restart Tomcat. To access your application, point your
browser at <code>http://localhost:8080/myapp/</code> and begin testing.
When you discover something that needs to change, fix it in
the source directory (not in the Tomcat deployment directory), redeploy,
and restart Tomcat.</p>
<p>Do not forget to commit your changes to the source code repository when
you have completed your testing!</p>
</subsection>
<subsection name="Creating a Release">
<p>When you are through adding new functionality, and you've tested everything
(you DO test, don't you :-), it is time to create the distributable version
of your web application that can be deployed on the production server. The
following general steps are required:</p>
<ul>
<li>Issue the command <code>ant all</code> from the project source
directory, to rebuild everything from scratch one last time.
<br/><br/></li>
<li>Use the <code>cvs tag</code> command to create an identifier for
all of the source files utilized to create this release. This allows
you to reliably reconstruct a release (from sources) at a later
time.</li>
<li>Issue the command <code>ant dist</code> to create a distributable
web application archive (WAR) file, as well as a JAR file containing
the corresponding source code.
<br/><br/></li>
<li>Package the contents of the <code>dist</code> directory using the
<strong>tar</strong> or <strong>zip</strong> utility, according to
the standard release procedures used by your organization.</li>
</ul>
</subsection>
</section>
</body>
</document>
1.1 jakarta-tomcat-4.0/webapps/tomcat-docs/appdev/project.xml
Index: project.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<project name="Application Developer's Guide"
href="http://jakarta.apache.org/tomcat/">
<title>Application Developer's Guide</title>
<logo href="http://jakarta.apache.org/tomcat/images/tomcat.gif">
The Tomcat Servlet/JSP Container
</logo>
<body>
<menu name="Links">
<item name="Docs Home" href="/.."/>
</menu>
<menu name="Contents">
<item name="Contents" href="/index.html"/>
<item name="Introduction" href="/introduction.html"/>
<item name="Installation" href="/installation.html"/>
<item name="Deployment" href="/deployment.html"/>
<item name="Source Code" href="/source.html"/>
<item name="Processes" href="/processes.html"/>
<item name="Example App" href="/sample/"/>
</menu>
</body>
</project>
1.1 jakarta-tomcat-4.0/webapps/tomcat-docs/appdev/source.xml
Index: source.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<author email="craigmcc@apache.org">Craig R. McClanahan</author>
<title>Source Organization</title>
</properties>
<body>
<section name="Directory Structure">
<p>A key recommendation of this manual is to separate the directory
hierarchy containing your source code (described in this section) from
the directory hierarchy containing your deployable application
(described in the preceding section). Maintaining this separation has
the following advantages:</p>
<ul>
<li>The contents of the source directories can be more easily administered,
moved, and backed up if the "executable" version of the application
is not intermixed.
<br/><br/></li>
<li>Source code control is easier to manage on directories that contain
only source files.
<br/><br/></li>
<li>The files that make up an installable distribution of your
application are much easier to select when the deployment
hierarchy is separate.</li>
</ul>
<p>As we will see, the <code>ant</code> development tool makes the creation
and processing of such directory hierarchies nearly painless.</p>
<p>The actual directory and file hierarchy used to contain the source code
of an application can be pretty much anything you like. However, the
following organization has proven to be quite generally applicable, and is
expected by the example <code>build.xml</code> configuration file that
is discussed below. All of these components exist under a top level
<em>project source directory</em> for your application:</p>
<ul>
<li><strong>docs/</strong> - Documentation for your application, in whatever
format your development team is using.<br/><br/></li>
<li><strong>src/</strong> - Java source files that generate the servlets,
beans, and other Java classes that are unique to your application.
If your source code is organized in packages (<strong>highly</strong>
recommended), the package hierarchy should be reflected as a directory
structure underneath this directory.<br/><br/></li>
<li><strong>web/</strong> - The static content of your web site (HTML pages,
JSP pages, JavaScript files, CSS stylesheet files, and images) that will
be accessible to application clients. This directory will be the
<em>document root</em> of your web application, and any subdirectory
structure found here will be reflected in the request URIs required to
access those files.<br/><br/></li>
<li><strong>web/WEB-INF/</strong> - The special configuration files required
for your application, including the web application deployment descriptor
(<code>web.xml</code>), tag library descriptors for custom tag libraries
you have created, and other resource files you wish to include within
your web application. Even though this directory appears to be a
subdirectory of your <em>document root</em>, the Servlet Specification
prohibits serving the contents of this directory (or any file it contains)
directly to a client request. Therefore, this is a good place to store
configuration information that is sensitive (such as database connection
usernames and passwords), but is required for your application to
operate successfully.</li>
</ul>
<p>During the development process, two additional directories will be
created on a temporary basis:</p>
<ul>
<li><strong>build/</strong> - When you execute a default build
(<code>ant</code>), this directory will contain an exact image
of the files in the web application archive for this application.
For containers like Tomcat that allow you to deploy
unpacked directory structures, you need only copy this directory structure
into a subdirectory of <code>$CATALINA_HOME/webapps</code> in order to
deploy and test it.<br/><br/></li>
<li><strong>dist/</strong> - When you execute the <code>ant dist</code>
target, this directory will be created. It will create an exact image
of the binary distribution for your web application, including an license
information, documentation, and README files that you have prepared.</li>
</ul>
<p>Note that these two directories should <strong>NOT</strong> be archived in
your source code control system, because they are deleted and recreated (from
scratch) as needed during development. For that reason, you should not edit
any source files in these directories if you want to maintain a permanent
record of the changes, because the changes will be lost the next time that a
build is performed.</p>
<subsection name="External Dependencies">
<p>What do you do if your application requires JAR files (or other
resources) from external projects or packages? A common example is that
you need to include a JDBC driver in your web application, in order to
operate.</p>
<p>Different developers take different approaches to this problem.
Some will encourage checking a copy of the JAR files you depend on into
the source code control archives for every application that requires those
JAR files. However, this can cause significant management issues when you
use the same JAR in many applications - particular when faced with a need
to upgrade to a different version of that JAR file.</p>
<p>Therefore, this manual recommends that you <strong>NOT</strong> store
a copy of the packages you depend on inside the source control archives
of your applications. Instead, the external dependencies should be
integrated as part of the process of <strong>deploying</strong> your
application. In that way, you can always pick up the appropriate version
of the JAR files from wherever your development system administrator has
installed them, without having to worry about updating your application
every time the version of the dependent JAR file is changed.</p>
<p>In the example Ant <code>build.xml</code> file, we will demonstrate
how to define <em>build properties</em> that let you configure the locations
of the files to be copied, without having to modify <code>build.xml</code>
when these files change. The build properties used by a particular
developer can be customized on a per-application basis, or defaulted to
"standard" build properties stored in the developer's home directory.</p>
</subsection>
</section>
<section name="Source Code Control">
<p>As mentioned earlier, it is highly recommended that you place all of the
source files that comprise your application under the management of a
source code control system like the Concurrent Version System (CVS). If you
elect to do this, every directory and file in the source hierarchy should be
registered and saved -- but none of the generated files. If you register
binary format files (such as images or JAR libraries), be sure to indicate
this to your source code control system.</p>
<p>We recommended (in the previous section) that you should not store the
contents of the <code>build/</code> and <code>dist/</code> directories
created by your development process in the source code control system. An
easy way to tell CVS to ignore these directories is to create a file named
<code>.cvsignore</code> (note the leading period) in your top-level source
directory, with the following contents:</p>
<source>
build
dist
build.properties
</source>
<p>The reason for mentioning <code>build.properties</code> here will be
explained in the <a href="processes.html">Processes</a> section.</p>
<p>Detailed instructions for your source code control environment are beyond
the scope of this manual. However, the following steps are followed when
using a command-line CVS client:</p>
<ul>
<li>To refresh the state of your source code to that stored in the
the source repository, go to your project source directory, and
execute <code>cvs update -dP</code>.
<br/><br/></li>
<li>When you create a new subdirectory in the source code hierarchy, register
it in CVS with a command like <code>cvs add {subdirname}</code>.
<br/><br/></li>
<li>When you first create a new source code file, navigate to the directory
that contains it, and register the new file with a command like
<code>cvs add {filename}</code>.
<br/><br/></li>
<li>If you no longer need a particular source code file, navigate to the
containing directory and remove the file. Then, deregister it in CVS
with a command like <code>cvs remove {filename}</code>.
<br/><br/></li>
<li>While you are creating, modifying, and deleting source files, changes
are not yet reflected in the server repository. To save your changes in
their current state, go to the project source directory
and execute <code>cvs commit</code>. You will be asked to write a brief
description of the changes you have just completed, which will be stored
with the new version of any updated source file.</li>
</ul>
<p>CVS, like other source code control systems, has many additional features
(such as the ability to tag the files that made up a particular release, and
support for multiple development branches that can later be merged). See the
links and references in the <a href="introduction.html">Introduction</a> for
more information.</p>
</section>
<section name="BUILD.XML Configuration File">
<p>We will be using the <strong>ant</strong> tool to manage the compilation of
our Java source code files, and creation of the deployment hierarchy. Ant
operates under the control of a build file, normally called
<code>build.xml</code>, that defines the processing steps required. This
file is stored in the top-level directory of your source code hierarchy, and
should be checked in to your source code control system.</p>
<p>Like a Makefile, the <code>build.xml</code> file provides several
"targets" that support optional development activities (such as creating
the associated Javadoc documentation, erasing the deployment home directory
so you can build your project from scratch, or creating the web application
archive file so you can distribute your application. A well-constructed
<code>build.xml</code> file will contain internal documentation describing
the targets that are designed for use by the developer, versus those targets
used internally. To ask Ant to display the project documentation, change to
the directory containing the <code>build.xml</code> flie and type:</p>
<source>
ant -projecthelp
</source>
<p>To give you a head start, a <a href="build.xml.txt">basic build.xml file</a>
is provided that you can customize and install in the project source directory
for your application. This file includes comments that describe the various
targets that can be executed. Briefly, the following targets are generally
provided:</p>
<ul>
<li><strong>clean</strong> - This target deletes any existing
<code>build</code> and <code>dist</code> directories, so that they
can be reconstructed from scratch. This allows you to guarantee that
you have not made source code modifications that will result in
problems at runtime due to not recompiling all affected classes.
<br/><br/></li>
<li><strong>prepare</strong> - This target "prepares" the <code>build</code>
directory, creating subdirectories as required. A common use of this
target is to copy static files (documentation, HTML pages, and JSP pages)
from the source directory to the build directory. When
executed, this target will only create directories if they do not
exist, and only copy files if the destination file does not exist,
or the source version of the file is newer. This target is generally
invoked indirectly, by virtue of a <code>depends</code> attribute on
some other task.
<br/><br/></li>
<li><strong>compile</strong> - This target is used to compile any source code
that has been changed since the last time compilation took place. The
resulting class files are created in the <code>build</code> directory, so
that they can be executed when the application is deployed. Because
this command is executed so often during development, it is normally
made the "default" target so that a simple <code>ant</code> command will
execute it.
<br/><br/></li>
<li><strong>all</strong> - This target is a short cut for running the
<code>clean</code> target, followed by the <code>compiile</code> target.
Thus, it guarantees that you will recompile the entire application, to
ensure that you have not unknowingly introduced any incompatible changes.
<br/><br/></li>
<li><strong>deploy</strong> - This target is used to install your
application into a servlet container (we will continue to use Tomcat
in our examples) so that it can be tested. If your application requires
external JAR files, they will be copied to the <code>/WEB-INF/lib</code>
directory at deployment time.
<br/><br/></li>
<li><strong>javadoc</strong> - This target creates Javadoc API documentation
for the Java classes in this web application. The example
<code>build.xml</code> file assumes you want to include the API
documentation with your app distribution, so it generates the docs
in a subdirectory of the <code>dist</code> directory. Because you normally
do not need to generate the Javadocs on every compilation, this target is
usually a dependency of the <code>dist</code> target, but not of the
<code>compile</code> target.
<br/><br/></li>
<li><strong>dist</strong> - This target creates a distribution directory for
your application, including any required documentation, the Javadocs for
your Java classes, and a web application archive (WAR) file that will be
delivered to system administrators who wish to install your application.
Because this target also depends on the <code>deploy</code> target, the
web application archive will have also picked up any external dependencies
that were included at deployment time.</li>
</ul>
</section>
</body>
</document>
1.1 jakarta-tomcat-4.0/webapps/tomcat-docs/appdev/tomcat.gif
<<Binary file>>
1.1 jakarta-tomcat-4.0/webapps/tomcat-docs/appdev/web.xml.txt
Index: web.xml.txt
===================================================================
<!DOCTYPE web-app
PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
"http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app>
<!-- General description of your web application -->
<display-name>My Web Application</display-name>
<description>
This is version X.X of an application to perform
a wild and wonderful task, based on servlets and
JSP pages. It was written by Dave Developer
(dave@mycompany.com), who should be contacted for
more information.
</description>
<!-- Context initialization parameters that define shared
String constants used within your application, which
can be customized by the system administrator who is
installing your application. The values actually
assigned to these parameters can be retrieved in a
servlet or JSP page by calling:
String value =
getServletContext().getInitParameter("name");
where "name" matches the <param-name> element of
one of these initialization parameters.
You can define any number of context initialization
parameters, including zero.
-->
<context-param>
<param-name>webmaster</param-name>
<param-value>myaddress@mycompany.com</param-value>
<description>
The EMAIL address of the administrator to whom questions
and comments about this application should be addressed.
</description>
</context-param>
<!-- Servlet definitions for the servlets that make up
your web application, including initialization
parameters. With Tomcat, you can also send requests
to servlets not listed here with a request like this:
http://localhost:8080/{context-path}/servlet/{classname}
but this usage is not guaranteed to be portable. It also
makes relative references to images and other resources
required by your servlet more complicated, so defining
all of your servlets (and defining a mapping to them with
a <servlet-mapping> element) is recommended.
Servlet initialization parameters can be retrieved in a
servlet or JSP page by calling:
String value =
getServletConfig().getInitParameter("name");
where "name" matches the <param-name> element of
one of these initialization parameters.
You can define any number of servlets, including zero.
-->
<servlet>
<servlet-name>controller</servlet-name>
<description>
This servlet plays the "controller" role in the MVC architecture
used in this application. It is generally mapped to the ".do"
filename extension with a <servlet-mapping> element, and all form
submits in the app will be submitted to a request URI like
"saveCustomer.do", which will therefore be mapped to this servlet.
The initialization parameter namess for this servlet are the
"servlet path" that will be received by this servlet (after the
filename extension is removed). The corresponding value is the
name of the action class that will be used to process this request.
</description>
<servlet-class>com.mycompany.mypackage.ControllerServlet</servlet-class>
<init-param>
<param-name>listOrders</paramName>
<param-value>com.mycompany.myactions.ListOrdersAction</param-value>
</init-param>
<init-param>
<param-name>saveCustomer</paramName>
<param-value>com.mycompany.myactions.SaveCustomerAction</param-value>
</init-param>
<!-- Load this servlet at server startup time -->
<load-on-startup>5</load-on-startup>
</servlet>
<servlet>
<servlet-name>graph</servlet-name>
<description>
This servlet produces GIF images that are dynamically generated
graphs, based on the input parameters included on the request.
It is generally mapped to a specific request URI like "/graph".
</description>
</servlet>
<!-- Define mappings that are used by the servlet container to
translate a particular request URI (context-relative) to a
particular servlet. The examples below correspond to the
servlet descriptions above. Thus, a request URI like:
http://localhost:8080/{contextpath}/graph
will be mapped to the "graph" servlet, while a request like:
http://localhost:8080/{contextpath}/saveCustomer.do
will be mapped to the "controller" servlet.
You may define any number of servlet mappings, including zero.
It is also legal to define more than one mapping for the same
servlet, if you wish to.
-->
<servlet-mapping>
<servlet-name>controller</servlet-name>
<url-pattern>*.do</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>graph</servlet-name>
<url-pattern>/graph</url-pattern>
</servlet-mapping>
<!-- Define the default session timeout for your application,
in minutes. From a servlet or JSP page, you can modify
the timeout for a particular session dynamically by using
HttpSession.getMaxInactiveInterval(). -->
<session-config>
<session-timeout>30</session-timeout> <!-- 30 minutes -->
</session-config>
</web-app>
1.1 jakarta-tomcat-4.0/webapps/tomcat-docs/appdev/sample/docs/README.txt
Index: README.txt
===================================================================
This is a dummy README file for the sample
web application.
1.1 jakarta-tomcat-4.0/webapps/tomcat-docs/appdev/sample/web/hello.jsp
Index: hello.jsp
===================================================================
<html>
<head>
<title>Sample Application JSP Page</title>
</head>
<body bgcolor=white>
<table border="0">
<tr>
<td align=center>
<img src="images/tomcat.gif">
</td>
<td>
<h1>Sample Application JSP Page</h1>
This is the output of a JSP page that is part of the Hello, World
application. It displays several useful values from the request
we are currently processing.
</td>
</tr>
</table>
<table border="0" border="100%">
<tr>
<th align="right">Context Path:</th>
<td align="left"><%= request.getContextPath() %></td>
</tr>
<tr>
<th align="right">Path Information:</th>
<td align="left"><%= request.getPathInfo() %></td>
</tr>
<tr>
<th align="right">Query String:</th>
<td align="left"><%= request.getQueryString() %></td>
</tr>
<tr>
<th align="right">Request Method:</th>
<td align="left"><%= request.getMethod() %></td>
</tr>
<tr>
<th align="right">Servlet Path:</th>
<td align="left"><%= request.getServletPath() %></td>
</tr>
</table>
</body>
</html>
1.1 jakarta-tomcat-4.0/webapps/tomcat-docs/appdev/sample/web/index.html
Index: index.html
===================================================================
<html>
<head>
<title>Sample "Hello, World" Application</title>
</head>
<body bgcolor=white>
<table border="0">
<tr>
<td>
<img src="images/tomcat.gif">
</td>
<td>
<h1>Sample "Hello, World" Application</h1>
<p>This is the home page for a sample application used to illustrate the
source directory organization of a web application utilizing the principles
outlined in the Application Developer's Guide.
</td>
</tr>
</table>
<p>To prove that they work, you can execute either of the following links:
<ul>
<li>To a <a href="hello.jsp">JSP page</a>.
<li>To a <a href="hello">servlet</a>.
</ul>
</body>
</html>
1.1 jakarta-tomcat-4.0/webapps/tomcat-docs/appdev/sample/web/WEB-INF/web.xml
Index: web.xml
===================================================================
<!DOCTYPE web-app
PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
"http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app>
<display-name>Hello, World Application</display-name>
<description>
This is a simple web application with a source code organization
based on the recommendations of the Application Developer's Guide.
</description>
<servlet>
<servlet-name>HelloServlet</servlet-name>
<servlet-class>mypackage.Hello</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>HelloServlet</servlet-name>
<url-pattern>/hello</url-pattern>
</servlet-mapping>
</web-app>
1.1 jakarta-tomcat-4.0/webapps/tomcat-docs/appdev/sample/web/images/tomcat.gif
<<Binary file>>