You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by re...@apache.org on 2001/02/14 23:26:38 UTC
cvs commit: jakarta-tomcat-4.0/catalina/docs/appdev/sample/web/images tomcat.gif
remm 01/02/14 14:26:38
Modified: catalina/docs index.html
Added: catalina/docs/appdev build.xml.txt contents.html
deployment.html footer.html header.html index.html
installation.html introduction.html processes.html
source.html tomcat.gif web.xml.txt
catalina/docs/appdev/sample build.bat build.sh build.xml
catalina/docs/appdev/sample/etc web.xml
catalina/docs/appdev/sample/src Hello.java
catalina/docs/appdev/sample/web hello.jsp index.html
catalina/docs/appdev/sample/web/images tomcat.gif
Log:
- Commit the Application development documentation, originally written for
Tomcat 3.x, and which has been adapted for Tomcat 4.x by Amy Roh
(amyroh@eng.sun.com). Some more small updates are probably needed.
Revision Changes Path
1.5 +5 -0 jakarta-tomcat-4.0/catalina/docs/index.html
Index: index.html
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/catalina/docs/index.html,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- index.html 2001/01/14 04:26:10 1.4
+++ index.html 2001/02/14 22:26:32 1.5
@@ -25,6 +25,11 @@
<li><a href="dev/README.html">Developer Documentation</a></li>
</ul>
+<h1>Application Developer Documentation</h1>
+<ul>
+<li><a href="appdev/index.html">Developing Applications With Tomcat</a></li>
+</ul>
+
</body>
</html>
1.1 jakarta-tomcat-4.0/catalina/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 by convention in this
build file. The values specified can be overridden at run time by
adding a "-Dname=value" argument to the command line that invokes Ant.
This technique is normally used to copy the values of the ANT_HOME
and TOMCAT_HOME environment variables into the "ant.home" and
"tomcat.home" properties, which are normally not defined explicitly.
app.name Base name of this application, used to
construct filenames and directories.
deploy.home The name of the directory into which the
deployment hierarchy will be created.
Normally, this will be the name of a
subdirectory under $TOMCAT_HOME/webapps.
dist.home The name of the base directory in which
distribution files are created.
dist.src The name of the distribution JAR file
containing the application source code,
to be stored in the "dist.home" directory.
This filename should end with ".jar".
dist.war The name of the Web ARchive (WAR) file
containing our deployable application.
This filename should end with ".war".
javadoc.home The name of the base directory in which
the JavaDoc documentation for this application
is generated.
tomcat.home The name of the base directory in which
Tomcat has been installed. This value is
normally set automatically from the value
of the TOMCAT_HOME environment variable.
In the example below, the application being developed will be deployed
to a subdirectory named "myapp", and will therefore be accessible at:
http://localhost:8080/myapp
-->
<property name="app.name" value="myapp"/>
<property name="deploy.home" value="${tomcat.home}/webapps/${app.name}"/>
<property name="dist.home" value="${deploy.home}"/>
<property name="dist.src" value="${app.name}.jar"/>
<property name="dist.war" value="${app.name}.war"/>
<property name="javadoc.home" value="${deploy.home}/javadoc"/>
<!-- The "prepare" target is used to construct the deployment home
directory structure (if necessary), and to copy in static files
as required. In the example below, Ant is instructed to create
the deployment directory, copy the contents of the "web/" source
hierarchy, and set up the WEB-INF subdirectory appropriately.
-->
<target name="prepare">
<mkdir dir="${deploy.home}"/>
<copy todir="${deploy.home}">
<fileset dir="web"/>
</copy>
<mkdir dir="${deploy.home}/WEB-INF"/>
<copy file="etc/web.xml" tofile="${deploy.home}/WEB-INF/web.xml"/>
<mkdir dir="${deploy.home}/WEB-INF/classes"/>
<mkdir dir="${deploy.home}/WEB-INF/lib"/>
<copy todir="${deploy.home}/WEB-INF/lib">
<fileset dir="lib"/>
</copy>
<mkdir dir="${javadoc.home}"/>
</target>
<!-- The "clean" target removes the deployment home directory structure,
so that the next time the "compile" target is requested, it will need
to compile everything from scratch.
-->
<target name="clean">
<delete dir="${deploy.home}"/>
</target>
<!-- The "compile" target is used to compile (or recompile) the Java classes
that make up this web application. The recommended source code directory
structure makes this very easy because the <javac> task automatically
works its way down a source code hierarchy and compiles any class that
has not yet been compiled, or where the source file is newer than the
class file.
Feel free to adjust the compilation option parameters (debug,
optimize, and deprecation) to suit your requirements. It is also
possible to base them on properties, so that you can adjust this
behavior at runtime.
The "compile" task depends on the "prepare" task, so the deployment
home directory structure will be created if needed the first time.
-->
<target name="compile" depends="prepare">
<javac srcdir="src" destdir="${deploy.home}/WEB-INF/classes"
classpath="${deploy.home}/WEB-INF/classes"
debug="on" optimize="off" deprecation="off"/>
<copy todir="${deploy.home}/WEB-INF/classes">
<fileset dir="src" includes="**/*.properties"/>
</copy>
</target>
<!-- The "javadoc" target is used to create the Javadoc API documentation
for the Java classes in this web application. It is assumed that
this documentation is included in the deployed application, so the
example below generates the Javadoc HTML files in a subdirectory under
the deployment home directory. Feel free to customize the options for
the JavaDoc task, after consulting the Ant documentation.
-->
<target name="javadoc" depends="prepare">
<javadoc sourcepath="src" packagenames="*"
destdir="${javadoc.home}"/>
</target>
<!-- The "all" target rebuilds everything by executing the "clean"
target first, which forces the "compile" target to compile all
source code instead of just the files that have been changed.
-->
<target name="all" depends="clean,prepare,compile,javadoc"/>
<!-- The "dist" target builds the distribution Web ARchive (WAR) file
for this application, suitable for distribution to sites that wish
to install your application. It also creates a JAR file containing
the source code for this application, if you wish to distribute
that separately.
-->
<target name="dist" depends="prepare,compile">
<jar jarfile="${dist.home}/${dist.src}"
basedir="."/>
<jar jarfile="${dist.home}/${dist.war}"
basedir="${deploy.home}"/>
</target>
</project>
1.1 jakarta-tomcat-4.0/catalina/docs/appdev/contents.html
Index: contents.html
===================================================================
<html>
<head>
<title>Developing Applications With Tomcat -- Contents</title>
</head>
<body bgcolor="white">
<!-- Navigation Links -->
<table border=0 width="100%">
<tr>
<td align="left" width="25%">
Previous
</td>
<td align="center" width="50%">
<a href="contents.html">Top</a>
</td>
<td align="right" width="25%">
<a href="introduction.html">Next</a>
</td>
</tr>
<tr>
<td align="center" colspan=3>
<a href="#Credits">Credits</a>
<a href="#Contents">Contents</a>
<a href="#Sample">Sample</a>
</td>
</tr>
</table>
<h1>0. PREFACE</h1>
<!-- 0.1 Credits -->
<a name="Credits"></a>
<h2>0.1 Credits</h2>
<p>This manual includes contributions from many members of the Jakarta Project
developer community. The following authors have provided significant content:
<ul>
<li>Craig R. McClanahan
(<a href="mailto:Craig.McClanahan@eng.sun.com">Craig.McClanahan@eng.sun.com</a>)
</ul>
<!-- 0.2 Contents -->
<a name="Contents"></a>
<h2>0.2 Contents</h2>
<p>The information presented is divided into the following sections:
<ul>
<li><a href="introduction.html"><b>Introduction</b></a> -
Briefly describes the information covered here, with
links and references to other sources of information.
<li><a href="installation.html"><b>Installation</b></a> -
Covers acquiring and installing the required software
components to use Tomcat for web application development.
<li><a href="deployment.html"><b>Deployment Organization</b></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><a href="source.html"><b>Source Organization</b></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><a href="processes.html"><b>Development Processes</b></a> -
Provides brief descriptions of typical development processes
utilizing the recommended deployment and source organizations.
</ul>
<!-- 0.3 Sample -->
<a name="Sample"></a>
<h2>0.3 Sample Application</h2>
<p>The <a href="sample" target="_new">sample</a> directory contains a
complete, but very simple, "Hello, World" application built according
to the principles described in this manual. You can use this application
to practice using the described techniques.
</body>
</html>
1.1 jakarta-tomcat-4.0/catalina/docs/appdev/deployment.html
Index: deployment.html
===================================================================
<html>
<head>
<title>Developing Applications With Tomcat -- Deployment</title>
</head>
<body bgcolor="white">
<!-- Navigation Links -->
<table border=0 width="100%">
<tr>
<td align="left" width="25%">
<a href="installation.html">Previous</a>
</td>
<td align="center" width="50%">
<a href="contents.html">Top</a>
</td>
<td align="right" width="25%">
<a href="source.html">Next</a>
</td>
</tr>
<tr>
<td align="center" colspan=3>
<a href="#Background">Background</a>
<a href="#Layout">Layout</a>
<a href="#Descriptor">Descriptor</a>
<a href="#Integration">Integration</a>
</td>
</tr>
</table>
<h1>3. DEPLOYMENT ORGANIZATION</h1>
<!-- 3.1 Background -->
<a name="Background"></a>
<h2>3.1 Background</h2>
<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 specification are required to accept a <i>Web Application
Archive</i> in a standard format, which is discussed further below.
<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>The top-level directory of your web application hierarchy is also the
<i>document root</i> 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 <i>context path</i> to your application. 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.
<!-- 3.2 Layout -->
<a name="Layout"></a>
<h2>3.2 Standard Directory Layout</h2>
<p>To facilitate creation of a Web Application Archive file in the required
format, it is convenient to arrange the "executable" version 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:
<ul>
<li><b>*.html, *.jsp, etc.</b> - The HTML and JSP pages, along with other
files that must be visible to the client browser (such as JavaScript
and stylesheet files) 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><b>WEB-INF/web.xml</b> - The <i>Web Application Deployment Descriptor</i>
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><b>WEB-INF/classes/</b> - 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><b>WEB-INF/lib/</b> - 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.
</ul>
<p>When you install an application into Tomcat (or any other 2.2-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 added to the class path for 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 will be necessary.
<p>Much of this information was extracted from Chapter 9 of the Servlet
API Specification, version 2.2, which you should consult for more details.
<!-- 3.3 Descriptor -->
<a name="Descriptor"></a>
<h2>3.3 Web Application Deployment Descriptor</h2>
<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 <i>context path</i>,
which is assigned by the system administrator when the application is
deployed).
<p>The complete syntax and semantics for the deployment descriptor is defined
in Chapter 13 of the Servlet API Specification, version 2.2. 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.
<!-- 3.4 Integration -->
<a name="Integration"></a>
<h2>3.4 Integration With Tomcat</h2>
<p>In order to be executed, a web application must be integrated with,
or installed in, a servlet container. This is true even during development.
We will describe using Tomcat to provide the execution environment.
A web application can be deployed in Tomcat by one of three different
approaches:
<ul>
<li><i>Copy unpacked directory hierarchy into a subdirectory in directory
<code>$TOMCAT_HOME/webapps/</code></i>. 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.
<br><br>
<li><i>Copy the web application archive file into directory
<code>$TOMCAT_HOME/webapps/</code></i>. 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><i>Add a <code><Context></code> entry in the Tomcat
<code>server.xml</code> configuration file</i>. 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>$TOMCAT_HOME/webapps/</code> directory. Doing this requires
the following steps (for Tomcat 4.0):
</ul>
<p>Adding a new <code><Context></code> entry in Tomcat's
<code>server.xml</code> file involves the following steps (for Tomcat 4.0):
<ul>
<li>Open file <code>$TOMCAT_HOME/conf/server.xml</code> in an editor.
<br><br>
<li>Navigate to the bottom of the file (after the last existing
<code><Context></code> element).
<br><br>
<li>Add a new <code><Context></code> element for your application,
using the existing examples as a guide. The following attributes are
supported:
<ul>
<li><b>path</b>. The <i>context path</i> for your application, which
is the prefix of a request URI that tells Tomcat which application
should be used to process this request. For example, if you set
your path to "/catalog", any request URI beginning with "/catalog"
will be processed by this application. This attribute is requrired,
and must start with a slash ('/') character.
<li><b>docBase</b>. The <i>document root</i> directory for this web
application. This can be a relative path (relative to the
directory in which Tomcat is started), or an absolute path, to the
directory containing your app. On a Windows platform, you
<strong>MUST</strong>
use the drive prefix and a colon when specifying an absolute path.
This attribute is required.
<li><b>debug</b>. Debugging detail level (from "0" to "9") that defines
how verbose Tomcat's logging messages will be when your application
is initialized, started, and shut down. The default value is "0"
(minimal logging) if you do not specify a different value.
<li><b>reloadable</b>. Set to "true" if you want Tomcat to watch for
changes to Java class files in the WEB-INF/classes directory, or
JAR files in the WEB-INF/lib directory. If such a change is noted,
Tomcat will shut down and reload your application automatically,
picking up these changes. The default value ("false") means that
such changes will be ignored. NOTE: While this feature is very
useful during development, it requires overhead to do the checking.
This capability should generally <i>not</i> be used in deployed
production applications.
</ul>
</ul>
<p>Integrating your app with other servlet containers will be specific to each
container, but all containers compatible with the Servlet API Specification
(version 2.2) are required to accept a web application archive file.
</body>
</html>
1.1 jakarta-tomcat-4.0/catalina/docs/appdev/footer.html
Index: footer.html
===================================================================
<html>
<head>
<title>Developing Applications With Tomcat - Footer</title>
</head>
<body bgcolor="white">
<div align="center">
<br>
<font size=2>
Copyright © 2000, Apache Software Foundation - All Rights Reserved
</font>
</div>
</body>
</html>
1.1 jakarta-tomcat-4.0/catalina/docs/appdev/header.html
Index: header.html
===================================================================
<html>
<head>
<title>Developing Applications With Tomcat -- Header</title>
</head>
<body bgcolor="white">
<table border=0 width="100%" cellpadding=5 cellspacing=0><tr>
<td align="left" width="50%">
<img src="tomcat.gif" border=0>
</td>
<td align="right" width="50%">
<h1>Developing Applications With Tomcat</h1>
</td>
</tr></table>
</body>
</html>
1.1 jakarta-tomcat-4.0/catalina/docs/appdev/index.html
Index: index.html
===================================================================
<html>
<head>
<title>Developing Applications With Tomcat</title>
</head>
<frameset rows="91,*,50" border=0>
<frame name="HEADER" src="header.html"
frameborder=0 marginheight=0 marginwidth=0 noresize scrolling="no">
<frame name="MAIN" src="contents.html"
frameborder=0 marginheight=0 marginwidth=0 noresize scrolling="auto">
<frame name="FOOTER" src="footer.html"
frameborder=0 marginheight=0 marginwidth=0 noresize scrolling="no">
</frameset>
</html>
1.1 jakarta-tomcat-4.0/catalina/docs/appdev/installation.html
Index: installation.html
===================================================================
<html>
<head>
<title>Developing Applications With Tomcat -- Installation</title>
</head>
<body bgcolor="white">
<!-- Navigation Links -->
<table border=0 width="100%">
<tr>
<td align="left" width="25%">
<a href="introduction.html">Previous</a>
</td>
<td align="center" width="50%">
<a href="contents.html">Top</a>
</td>
<td align="right" width="25%">
<a href="deployment.html">Next</a>
</td>
</tr>
<tr>
<td align="center" colspan=3>
<a href="#JDK">JDK</a>
<a href="#Tomcat">Tomcat</a>
<a href="#Ant">Ant</a>
<a href="#CVS">CVS</a>
</td>
</tr>
</table>
<h1>2. INSTALLATION</h1>
<!-- 2.1 JDK -->
<a name="JDK"></a>
<h2>2.1 Java Development Kit</h2>
<p>Tomcat will operate under any Java Development Kit (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.
<p>Compatible JDKs for many platforms (or links to where they can be found)
are available at
<a href="http://java.sun.com/j2se/" target="_top">http://java.sun.com/j2se/</a>.
<!-- 2.2 Tomcat -->
<a name="Tomcat"></a>
<h2>2.2 Jakarta Tomcat</h2>
<p>Binary downloads of the Tomcat server are available from the
<a href="http://jakarta.apache.org/downloads/binindex.html">http://jakarta.apache.org/downloads/binindex.html</a>
page. This manual assumes you are using the most recent milestone,
beta, or release of Tomcat 4.0.
<p>The shell command line examples in this manual assume that you have
set up your environment as follows:
<ul>
<li>The <code>JAVA_HOME</code> environment variable points at the base
directory where you have installed the JDK (for example,
<code>/usr/local/jdk1.3</code>).
<li>You have added directory <code>$JAVA_HOME/bin</code> to your
<code>PATH</code> environment variable, so that the <code>java</code>
command is recognized and executed.
<li>The <code>TOMCAT_HOME</code> environment variable points at the base
directory where you have installed Tomcat (for example,
<code>/opt/tomcat</code> or <code>/usr/local/tomcat</code>).
</ul>
<p>Normally, any changes required to the <code>CLASSPATH</code> environment
variable are handled for you by the development scripts. However, if you
are defining your own scripts, you may need to add file
<code>$JAVA_HOME/lib/tools.jar</code> to your <code>CLASSPATH</code>.
<!-- 2.3 Ant -->
<a name="Ant"></a>
<h2>2.3 Jakarta Ant</h2>
<p>Although Tomcat includes a binary distribution of the Ant development
tool, it does not include the Ant developer documentation. This can be
acquired by downloading the complete Ant release from
<a href="http://jakarta.apache.org/downloads/binindex.html">http://jakarta.apache.org/downloads/binindex.html</a>
page. The example application build scripts assume that you have
<strong>Ant 1.2</strong> or later.</p>
<!-- 2.4 CVS -->
<a name="CVS"></a>
<h2>2.4 Concurrent Version System (CVS)</h2>
<p>Besides the required tools described above, you are strongly encouraged
to download and install a <i>source code control</i> system, such as 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>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>.
</body>
</html>
1.1 jakarta-tomcat-4.0/catalina/docs/appdev/introduction.html
Index: introduction.html
===================================================================
<html>
<head>
<title>Developing Applications With Tomcat -- Introduction</title>
</head>
<body bgcolor="white">
<!-- Navigation Links -->
<table border=0 width="100%">
<tr>
<td align="left" width="25%">
<a href="contents.html">Previous</a>
</td>
<td align="center" width="50%">
<a href="contents.html">Top</a>
</td>
<td align="right" width="25%">
<a href="installation.html">Next</a>
</td>
</tr>
<tr>
<td align="center" colspan=3>
<a href="#Overview">Overview</a>
<a href="#Links">Links</a>
<a href="#References">References</a>
</td>
</tr>
</table>
<h1>1. INTRODUCTION</h1>
<!-- 1.1 Overview -->
<a name="Overview"></a>
<h2>1.1 Overview</h2>
<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>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>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.
<!-- 1.2 Links -->
<a name="Links"></a>
<h2>1.2 Links</h2>
<p>The following links provide access to selected sources of online
information, documentation, and software that is useful in developing
web applications with Tomcat.
<ul>
<li><a href="http://java.sun.com/products/jsp/download.html" target="_top">http://java.sun.com/products/jsp/download.html</a> -
<i>JavaServer Pages (JSP) Specfication, Version 1.1</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 4), tag extensions (Chapter 5),
and packaging JSP pages (Appendix C) is useful. The Javadoc
API Documentation is included with the Tomcat download.
<br><br>
<li><a href="http://java.sun.com/products/servlet/download.html" target="_top">http://java.sun.com/products/servlet/download.html</a> -
<i>Servlet API Specification, Version 2.2</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 10), container managed
security (Chapter 11), and the syntax of the <code>web.xml</code>
Web Application Deployment Descriptor (Chapter 13). The Javadoc
<a href="http://java.sun.com/products/servlet/2.2/javadoc/" target="_top">
API Documentation</a> is available online, as well as being part of the
Tomcat download.
<br><br>
<li><a href="http://java.sun.com/j2ee/blueprints/" target="_top">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><a href="../dev/README.html" target="_top">../dev/README.html</a> -
<i>Tomcat - README.html </i>. Developer documentation including useful information on "Original Proposal for Catalina",
"Architecture of Catalina", "Building Catalina", and "JavaDocs".
<br><br>
<li><b>TODO</b> -- Add more entries here!
</ul>
<!-- 1.3 References -->
<a name="References"></a>
<h2>1.3 References</h2>
<p>The following list includes references to books, articles, and
other relevant information about web application design and development:
<ul>
<li><b>TODO</b> -- Add more entries here!
<br><br>
</ul>
</body>
</html>
1.1 jakarta-tomcat-4.0/catalina/docs/appdev/processes.html
Index: processes.html
===================================================================
<html>
<head>
<title>Developing Applications With Tomcat -- Processes</title>
</head>
<body bgcolor="white">
<!-- Navigation Links -->
<table border=0 width="100%">
<tr>
<td align="left" width="25%">
<a href="source.html">Previous</a>
</td>
<td align="center" width="50%">
<a href="contents.html">Top</a>
</td>
<td align="right" width="25%">
Next
</td>
</tr>
<tr>
<td align="center" colspan=3>
<a href="#Create">Create</a>
<a href="#Configure">Configure</a>
<a href="#Edit">Develop</a>
<a href="#Build">Build</a>
<a href="#Test">Test</a>
<a href="#Deploy">Deploy</a>
</td>
</tr>
</table>
<h1>5. Development Processes</h1>
<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>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.
<!-- 5.1 Create -->
<a name="Create"></a>
<h2>5.1 Create Project Source Directory</h2>
<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">Section 4</a>, or you can
use the <a href="sample" target="_new">sample</a> application as a starting
point.
<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:
<pre>
cd {my home directory}
mkdir myapp <-- Assumed "project source directory"
cd myapp
mkdir etc
mkdir lib
mkdir src
mkdir web
cvs import -m "Initial Project Creation" {project} \
{username} start
</pre>
<p>Now, to verify that it was created correctly in CVS, we will perform a
checkout of the new project:
<pre>
cd ..
mv myapp myapp.bu
cvs checkout {project}
</pre>
<p>Next, you will need to create and check in an initial version of the
<code>build.xml</code> and <code>build</code> or <code>build.bat</code>
script to be used for development. You can base <code>build.xml</code> on the
<a href="build.xml.txt" target="_new">basic build.xml file</a>,
or code it from scratch.
<pre>
cd {my home directory}
cd myapp
emacs build.xml <-- if you want a real editor :-)
cvs add build.xml
emacs build <-- or build.bat on Windows
chmod +x build <-- on Unix, make it executable
cvs add build <-- or build.bat on Windows
cvs commit
</pre>
<p>So far, all the editing you've done to the <code>build.xml</code> file,
and the corresponding build script, is local to your development directory.
Committing the changes makes them visible to other developers.
<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" target="_new">basic web.xml file</a>,
or code it from scratch.
<pre>
cd {my home directory}
cd myapp/etc <-- Ultimate destination will be WEB-INF
emacs web.xml
cvs add web.xml
cvs commit
</pre>
<!-- 5.2 Configure -->
<a name="Configure"></a>
<h2>5.2 Configure Tomcat To Recognize Your Application</h2>
<p>In order for Tomcat to recognize your application, you must integrate
it as described in <a href="deployment.html#Integration">Section 3.4</a>.
Any of the proposed techniques can be used. For our purposes, we will assume
that you are using the first approach (unpacked hierarchy), because we set
the deployment home to be an appropriate directory under the
<code>$TOMCAT_HOME/webapps</code> directory. With multiple developers, it
is easiest to install Tomcat separately for each of them, so that they can
have their own TOMCAT_HOME (as well as start and stop Tomcat) independently.
<!-- 5.3 Edit -->
<a name="Edit"></a>
<h2>5.3 Edit Source Code and Pages</h2>
<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">Section 4</a>, newly created
source files should be located in the appropriate subdirectory, under your
project source directory.
<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:
<pre>
cd {my home directory}
cd myapp
cvs update -d <-- -d means create dirs if necessary
</pre>
<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:
<pre>
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
</pre>
<p>Java source code that is defined in packages should be organized in a
directory hierarchy (under the <b>src/</b> 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> under your project
source directory. Whenever you create a new subdirectory, don't forget to
register it with CVS.
<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.
<!-- 5.4 Build -->
<a name="Build"></a>
<h2>5.4 Build The Web Application</h2>
<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):
<pre>
cd {my home directory}
cd myapp <-- Normally leave a window open here
build <-- (Windows) Defaults to "build compile"
./build.sh <-- (Unix) Defaults to "build compile"
</pre>
<p>The Ant tool will be utilized to 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>To force the recompilation of your entire application, do this instead:
<pre>
cd {my home directory}
cd myapp
build all <-- (Windows)
./build.sh all <-- (Unix)
</pre>
<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.
<!-- 5.5 Test -->
<a name="Test"></a>
<h2>5.5 Test Your Web Application</h2>
<p>To test your application, you will want to execute it under Tomcat.
Assuming you have integrated your application as described earlier, this
is very simple. Under Unix, simply execute:
<pre>
$TOMCAT_HOME/bin/startup.sh
</pre>
<p>or, under Windows, execute:
<pre>
%TOMCAT_HOME%\bin\startup
</pre>
<p>This command starts Tomcat as a background process. Now, point your
web browser at the home page for your application, by opening the following
URL (where "/myapp" is the context path you have assigned to it):
<pre>
http://localhost:8080/myapp
</pre>
<p>Now, you can exercize your application to verify that it operates
correctly. When you discover something that needs to change, fix it as
follows:
<ul>
<li>To change a JSP page, modify it in the <b>source</b> directory and
then re-execute the <code>build</code> script. The updated
page will be recopied, and Tomcat will recognize this the next time
that page is accessed -- the page will then be recompiled automatically.
<li>Changing a servlet or other Java class is similar, but the effort
required depends on whether you selected the "autoreload" attribute
for this context when you integrated with Tomcat. First, edit the
file in its <b>source</b> directory, and re-execute the
<code>build</code> script. The updated Java class will be recompiled.
If autoreloading is selected, Tomcat will notice this change the next
time this class is referenced, and will automatically unload and reload
your application. Otherwise, you will need to manually stop and restart
Tomcat before continuing.
</ul>
<p>Using a debugger on servlets and JSP pages is currently outside the scope
of this document. Enhancements to describe these procedures is requested.
<p>Do not forget to commit your changes to the source code repository when
you have completed your testing!
<!-- 5.6 Deploy -->
<a name="Deploy"></a>
<h2>5.6 Deploy Your Web Application</h2>
<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:
<ul>
<li>Issue the command <code>build all</code> from the project source
directory, to rebuild everything from scratch one last time.
<li>Issue the command <code>build dist</code> to create a distributable
web application archive (WAR) file, as well as a JAR file containing
the corresponding source code.
<li>Give the WAR file to the system administrator of your production
server environment, so that he or she can install it.
</ul>
</body>
</html>
1.1 jakarta-tomcat-4.0/catalina/docs/appdev/source.html
Index: source.html
===================================================================
<html>
<head>
<title>Developing Applications With Tomcat -- Source</title>
</head>
<body bgcolor="white">
<!-- Navigation Links -->
<table border=0 width="100%">
<tr>
<td align="left" width="25%">
<a href="deployment.html">Previous</a>
</td>
<td align="center" width="50%">
<a href="contents.html">Top</a>
</td>
<td align="right" width="25%">
<a href="processes.html">Next</a>
</td>
</tr>
<tr>
<td align="center" colspan=3>
<a href="#Directory">Directory</a>
<a href="#CVS">CVS</a>
<a href="#Build">BUILD.XML</a>
<a href="#Scripts">Scripts</a>
</td>
</tr>
</table>
<h1>4. SOURCE ORGANIZATION</h1>
<!-- 4.1 Directory -->
<a name="Directory"></a>
<h2>4.1 Directory Structure</h2>
<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:
<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>Source code control is easier to manage on directories that contain
only source files.
<br><br>
<li>The files that make up an installable distribution of your
application are much easier to select when the deployment
hierarchy is separate.
</ul>
<p>As we will see, the <code>ant</code> development tool makes the creation
and processing of such directory hierarchies nearly painless.
<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
<i>project source directory</i> for your application:
<ul>
<li><b>etc/</b> - Directory containing special files related to your
application that will be copied to the <code>WEB-INF</code> directory.
In all cases, this will include the application deployment
descriptor file (<code>web.xml</code>), but may include others as well.
<br><br>
<li><b>lib/</b> - Directory containing JAR files that will be copied to
the <code>WEB-INF/lib</code> deployment directory.
<br><br>
<li><b>src/</b> - Java source files that generate the servlets, beans,
and other Java classes required by your application. If your source
code is organized into packages (highly recommended for large projects),
the package hierarchy should be reflected as a directory structure
underneath this directory.
<br><br>
<li><b>web/</b> - Directory containing the HTML files, JSP pages, and other
resource files (such as JavaScript and stylesheet files) that will be
accessible to browser clients. The entire hierarchy underneath this
directory will be copied to the document root directory of your
deployment home.
</ul>
<!-- 4.2 CVS -->
<a name="CVS"></a>
<h2>4.2 Source Code Control</h2>
<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>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:
<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 -d</code>.
<br><br>
<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>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>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>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.
</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.
<!-- 4.3 Build -->
<a name="Build"></a>
<h2>4.3 BUILD.XML Configuration File</h2>
<p>We will be using the <code>ant</code> 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. 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.
<p>To give you a head start, a
<a href="build.xml.txt" target="_new">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:
<ul>
<li><b>prepare</b> - This target "prepares" the deployment 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 deployment 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.
<li><b>compile</b> - 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 deployment directory, so
that they can be directly executed when Tomcat is run.
<strong>NOTE</strong> - Previous versions of Ant copied properties files
and other resource files for you as part of the execution of the
<code><javac></code> task. You must now do this explicitly.
<li><b>javadoc</b> - 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,
so it generates the docs in a subdirectory of the deployment directory.
<li><b>all</b> - This target deletes the entire deployment directory and
then recreates everything. It is a good habit to do this after you've
made a bunch of changes, and before you check them in to your source
code repository. In particular, you should perform <code>build all</code>
before you use the "dist" target to create a distribution of your
application, to ensure that the distribution contains no unwanted files.
<li><b>dist</b> - This target creates a web application archive (WAR) file
containing your application, and a JAR file containing all of the
source code. In the example <code>build.xml</code> file, the contents
of the WAR file are based on the most recent build in the deployment
directory.
</ul>
<p>In the following section, scripts will be described that use Ant to
compile your project, based on the contents of the <code>build.xml</code>
file defined here.
<!-- 4.4 Scripts -->
<a name="Scripts"</a>
<h2>4.4 Shell and Batch Scripts</h2>
<p>The primary script we will utilize is generically called the <i>build</i>
script. It executes Ant, which reads and processes the <code>build.xml</code>
file discussed above. Each time you execute the build script, you will
specify the build "target" that you wish to execute. Users of a command
line MAKE tool (which processes a makefile) will recognize this approach.
<p>On UNIX-based systems, the following script should be saved as file
<code>build.sh</code> in the project source directory, with file permissions
that make it executable, and customized as required:
<pre>
#!/bin/sh
# build -- Build Script for the "Hello, World" Application
# $Id: source.html,v 1.1 2001/02/14 22:26:34 remm Exp $
# Identify the custom class path components we need
CP=$TOMCAT_HOME/lib/ant.jar:$TOMCAT_HOME/lib/servlet.jar
CP=$CP:$TOMCAT_HOME/lib/jaxp.jar:$TOMCAT_HOME/lib/parser.jar
CP=$CP:$JAVA_HOME/lib/tools.jar
# Execute ANT to perform the requested build target
java -classpath $CP:$CLASSPATH org.apache.tools.ant.Main \
-Dtomcat.home=$TOMCAT_HOME "$@"
</pre>
<p>On Windows-based systems, the following script should be saved as file
<code>build.bat</code> in the project source directory, and customized
as required:
<pre>
@echo off
rem build.bat -- Build Script for the "Hello, World" Application
rem $Id: source.html,v 1.1 2001/02/14 22:26:34 remm Exp $
set _CP=%CP%
rem Identify the custom class path components we need
set CP=%TOMCAT_HOME%\lib\ant.jar;%TOMCAT_HOME%\lib\servlet.jar
set CP=%TOMCAT_HOME%\lib\jaxp.jar;%TOMCAT_HOME%\lib\parser.jar
set CP=%CP%;%JAVA_HOME%\lib\tools.jar
rem Execute ANT to perform the requird build target
java -classpath %CP%;%CLASSPATH% org.apache.tools.ant.Main -Dtomcat.home=%TOMCAT_HOME% %1 %2 %3 %4 %5 %6 %7 %8 %9
set CP=%_CP%
set _CP=
</pre>
<p>Build script customizations you might consider include:
<ul>
<li>Setting the JAVA_HOME and TOMCAT_HOME environment variables (probably
near the top of the script) if they are not defined already.
<br><br>
<li>Overriding properties defined in the <code>build.xml</code> file
with default values. For example, to change the distribution home
directory (property <code>dist.home</code>), you would include the
following command line option after the word "java":
<b>-Ddist.home=xxxxx</b>.
<br><br>
</ul>
</body>
</html>
1.1 jakarta-tomcat-4.0/catalina/docs/appdev/tomcat.gif
<<Binary file>>
1.1 jakarta-tomcat-4.0/catalina/docs/appdev/web.xml.txt
Index: web.xml.txt
===================================================================
<!DOCTYPE web-app
PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
"http://java.sun.com/j2ee/dtds/web-app_2_2.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/catalina/docs/appdev/sample/build.bat
Index: build.bat
===================================================================
@echo off
rem build.bat -- Build Script for the "Hello, World" Application
rem $Id: build.bat,v 1.1 2001/02/14 22:26:35 remm Exp $
set _CP=%CP%
rem Identify the custom class path components we need
set CP=%TOMCAT_HOME%\lib\ant.jar;%TOMCAT_HOME%\lib\servlet.jar
set CP=%TOMCAT_HOME%\lib\jaxp.jar;%TOMCAT_HOME%\lib\parser.jar
set CP=%CP%;%JAVA_HOME%\lib\tools.jar
rem Execute ANT to perform the requird build target
java -classpath %CP%;%CLASSPATH% org.apache.tools.ant.Main -Dtomcat.home=%TOMCAT_HOME% %1 %2 %3 %4 %5 %6 %7 %8 %9
set CP=%_CP%
set _CP=
1.1 jakarta-tomcat-4.0/catalina/docs/appdev/sample/build.sh
Index: build.sh
===================================================================
#!/bin/sh
# build.sh -- Build Script for the "Hello, World" Application
# $Id: build.sh,v 1.1 2001/02/14 22:26:36 remm Exp $
# Identify the custom class path components we need
CP=$TOMCAT_HOME/lib/ant.jar:$TOMCAT_HOME/lib/servlet.jar
CP=$CP:$TOMCAT_HOME/lib/jaxp.jar:$TOMCAT_HOME/lib/parser.jar
CP=$CP:$JAVA_HOME/lib/tools.jar
# Execute ANT to perform the requested build target
java -classpath $CP:$CLASSPATH org.apache.tools.ant.Main \
-Dtomcat.home=$TOMCAT_HOME "$@"
1.1 jakarta-tomcat-4.0/catalina/docs/appdev/sample/build.xml
Index: build.xml
===================================================================
<project name="Hello, World" default="compile" basedir=".">
<!-- Simple "Hello, World" project to provide a concrete example of
the recommendations in the Application Developer's Guide.
NOTE: Before using this file as is, you should review the
values for the properties that are defined below.
In particular, it is assumed that you wish to install this
application under context path "/${app.name}" in the Tomcat installation
defined by your TOMCAT_HOME environment variable.
-->
<property name="app.name" value="myapp"/>
<property name="deploy.home" value="${tomcat.home}/webapps/${app.name}"/>
<property name="dist.home" value="${deploy.home}"/>
<property name="dist.src" value="${app.name}.jar"/>
<property name="dist.war" value="${app.name}.war"/>
<property name="javadoc.home" value="${deploy.home}/javadoc"/>
<target name="prepare">
<mkdir dir="${deploy.home}"/>
<copy todir="${deploy.home}">
<fileset dir="web"/>
</copy>
<mkdir dir="${deploy.home}/WEB-INF"/>
<copy file="etc/web.xml" tofile="${deploy.home}/WEB-INF/web.xml"/>
<mkdir dir="${deploy.home}/WEB-INF/classes"/>
<!--
<mkdir dir="${deploy.home}/WEB-INF/lib"/>
<copy todir="${deploy.home}/WEB-INF/lib">
<fileset dir="lib"/>
</copy>
-->
<mkdir dir="${javadoc.home}"/>
</target>
<target name="clean">
<delete dir="${deploy.home}"/>
</target>
<target name="compile" depends="prepare">
<javac srcdir="src" destdir="${deploy.home}/WEB-INF/classes"
classpath="${deploy.home}/WEB-INF/classes"
debug="on" optimize="off" deprecation="off"/>
<copy todir="${deploy.home}/WEB-INF/classes">
<fileset dir="src" includes="**/*.properties"/>
</copy>
</target>
<target name="javadoc" depends="prepare">
<javadoc sourcepath="src" packagenames="*"
destdir="${javadoc.home}"/>
</target>
<target name="all" depends="clean,prepare,compile,javadoc"/>
<target name="dist" depends="prepare,compile">
<jar jarfile="${dist.home}/${dist.src}"
basedir="." includes="*"/>
<jar jarfile="${dist.home}/${dist.war}"
basedir="${deploy.home}" includes="*"/>
</target>
</project>
1.1 jakarta-tomcat-4.0/catalina/docs/appdev/sample/etc/web.xml
Index: web.xml
===================================================================
<!DOCTYPE web-app
PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
"http://java.sun.com/j2ee/dtds/web-app_2_2.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>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/catalina/docs/appdev/sample/src/Hello.java
Index: Hello.java
===================================================================
/*
* ====================================================================
*
* The Apache Software License, Version 1.1
*
* Copyright (c) 1999 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution, if
* any, must include the following acknowlegement:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowlegement may appear in the software itself,
* if and wherever such third-party acknowlegements normally appear.
*
* 4. The names "The Jakarta Project", "Tomcat", and "Apache Software
* Foundation" must not be used to endorse or promote products derived
* from this software without prior written permission. For written
* permission, please contact apache@apache.org.
*
* 5. Products derived from this software may not be called "Apache"
* nor may "Apache" appear in their names without prior written
* permission of the Apache Group.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation. For more
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
*
* [Additional notices, if required by prior licensing conditions]
*
*/
// If this class were in a package, it would need to go in the
// corresponding subdirectory
import java.io.IOException;
import java.io.PrintWriter;
import java.util.Enumeration;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
/**
* Simple servlet to validate that the Hello, World example can
* execute servlets. In the web application deployment descriptor,
* this servlet must be mapped to correspond to the link in the
* "index.html" file.
*
* @author Craig R. McClanahan <Cr...@eng.sun.com>
*/
public final class Hello extends HttpServlet {
/**
* Respond to a GET request for the content produced by
* this servlet.
*
* @param request The servlet request we are processing
* @param response The servlet response we are producing
*
* @exception IOException if an input/output error occurs
* @exception ServletException if a servlet error occurs
*/
public void doGet(HttpServletRequest request,
HttpServletResponse response)
throws IOException, ServletException {
response.setContentType("text/html");
PrintWriter writer = response.getWriter();
writer.println("<html>");
writer.println("<head>");
writer.println("<title>Sample Application Servlet Page</title>");
writer.println("</head>");
writer.println("<body bgcolor=white>");
writer.println("<table border=\"0\">");
writer.println("<tr>");
writer.println("<td>");
writer.println("<img src=\"images/tomcat.gif\">");
writer.println("</td>");
writer.println("<td>");
writer.println("<h1>Sample Application Servlet</h1>");
writer.println("This is the output of a servlet that is part of");
writer.println("the Hello, World application. It displays the");
writer.println("request headers from the request we are currently");
writer.println("processing.");
writer.println("</td>");
writer.println("</tr>");
writer.println("</table>");
writer.println("<table border=\"0\" width=\"100%\">");
Enumeration names = request.getHeaderNames();
while (names.hasMoreElements()) {
String name = (String) names.nextElement();
writer.println("<tr>");
writer.println(" <th align=\"right\">" + name + ":</th>");
writer.println(" <td>" + request.getHeader(name) + "</td>");
writer.println("</tr>");
}
writer.println("</table>");
writer.println("</body>");
writer.println("</html>");
}
}
1.1 jakarta-tomcat-4.0/catalina/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/catalina/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/catalina/docs/appdev/sample/web/images/tomcat.gif
<<Binary file>>