tomcat-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From r...@apache.org
Subject cvs commit: jakarta-tomcat-4.0/catalina/docs/appdev/sample/web/images tomcat.gif
Date Wed, 14 Feb 2001 22:26:38 GMT
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>&lt;Context&gt;</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>&lt;Context&gt;</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>&lt;Context&gt;</code> element).
      <br><br>
  <li>Add a new <code>&lt;Context&gt;</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 &copy; 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>&lt;javac&gt;</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 <Craig.McClanahan@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>>
  
  

Mime
View raw message