tomcat-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From craig...@apache.org
Subject cvs commit: jakarta-tomcat-4.0/webapps/tomcat-docs/appdev build.xml.txt deployment.xml installation.xml processes.xml source.xml
Date Tue, 29 Jan 2002 19:32:11 GMT
craigmcc    02/01/29 11:32:11

  Modified:    webapps/tomcat-docs/appdev build.xml.txt deployment.xml
                        installation.xml processes.xml source.xml
  Log:
  Update the sample "build.xml" script, and the associated documentation in the
  Application Developer's Guide, to reflect the availability of Ant tasks that
  interact with the Manager webapp to perform on-the-fly installation, reloading,
  and removal of web applications under development.
  
  Revision  Changes    Path
  1.4       +186 -58   jakarta-tomcat-4.0/webapps/tomcat-docs/appdev/build.xml.txt
  
  Index: build.xml.txt
  ===================================================================
  RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/tomcat-docs/appdev/build.xml.txt,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- build.xml.txt	10 Dec 2001 01:15:05 -0000	1.3
  +++ build.xml.txt	29 Jan 2002 19:32:11 -0000	1.4
  @@ -1,3 +1,27 @@
  +<!--
  +     General purpose build script for web applications and web services,
  +     including enhanced support for deploying directly to a Tomcat 4
  +     based server.
  +
  +     This build script assumes that the source code of your web application
  +     is organized into the following subdirectories underneath the source
  +     code directory from which you execute the build script:
  +
  +        docs                 Static documentation files to be copied to
  +                             the "docs" subdirectory of your distribution.
  +
  +        src                  Java source code (and associated resource files)
  +                             to be compiled to the "WEB-INF/classes"
  +                             subdirectory of your web applicaiton.
  +
  +        web                  Static HTML, JSP, and other content (such as
  +                             image files), including the WEB-INF subdirectory
  +                             and its configuration file contents.
  +
  +     $Id: build.xml.txt,v 1.4 2002/01/29 19:32:11 craigmcc Exp $
  +-->
  +
  +
   <!-- 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,
  @@ -6,24 +30,28 @@
        set to the current working directory.
   -->
   
  -
   <project name="My Project" default="compile" basedir=".">
   
   
   
   <!-- ===================== Property Definitions =========================== -->
   
  +
   <!--
   
     Each of the following properties are used in the build script.
     Values for these properties are set by the first place they are
     defined, from the following list:
  -  * Definitions on the "ant" command line (ant -Dcatalina.home=xyz compile)
  +
  +  * Definitions on the "ant" command line (ant -Dfoo=bar compile).
  +
     * Definitions from a "build.properties" file in the top level
  -    source directory
  +    source directory of this application.
  +
     * Definitions from a "build.properties" file in the developer's
  -    home directory
  -  * Default definitions in this build.xml file
  +    home directory.
  +
  +  * Default definitions in this build.xml file.
   
     You will note below that property values can be composed based on the
     contents of previously defined properties.  This is a powerful technique
  @@ -39,6 +67,7 @@
   
   <!-- ==================== File and Directory Names ======================== -->
   
  +
   <!--
   
     These properties generally define file and directory names (or paths) that
  @@ -48,7 +77,11 @@
                          construct filenames and directories.
                          Defaults to "myapp".
   
  -  app.version          Version identifier for this application.
  +  app.path             Context path to which this application should be
  +                       deployed (defaults to "/" plus the value of the
  +                       "app.name" property).
  +
  +  app.version          Version number of this iteration of the application.
   
     build.home           The directory into which the "prepare" and
                          "compile" targets will generate their output.
  @@ -58,24 +91,61 @@
                          a binary distribution of Tomcat 4.  This will
                          be used by the "deploy" target.
   
  -  deploy.home          The name of the directory into which the
  -                       deployment hierarchy will be created, and into
  -                       which the build directory will be copied.
  -                       Defaults to "${catalina.home}/webapps/${app.name}".
  -
     dist.home            The name of the base directory in which
                          distribution files are created.
                          Defaults to "dist".
   
  +  manager.password     The login password of a user that is assigned the
  +                       "manager" role (so that he or she can execute
  +                       commands via the "/manager" web application)
  +
  +  manager.url          The URL of the "/manager" web application on the
  +                       Tomcat installation to which we will deploy web
  +                       applications and web services.
  +
  +  manager.username     The login username of a user that is assigned the
  +                       "manager" role (so that he or she can execute
  +                       commands via the "/manager" web application)
  +
   -->
   
     <property name="app.name"      value="myapp"/>
  -  <property name="app.version"   value="1.0"/>
  -  <property name="build.home"    value="build"/>
  +  <property name="app.path"      value="/${app.name}"/>
  +  <property name="app.version"   value="0.1-dev"/>
  +  <property name="build.home"    value="${basedir}/build"/>
     <property name="catalina.home" value="../../../.."/> <!-- UPDATE THIS! -->
  -  <property name="deploy.home"   value="${catalina.home}/webapps/${app.name}"/>
  -  <property name="dist.home"     value="dist"/>
  +  <property name="dist.home"     value="${basedir}/dist"/>
  +  <property name="docs.home"     value="${basedir}/docs"/>
  +  <property name="manager.url"   value="http://localhost:8080/manager"/>
  +  <property name="src.home"      value="${basedir}/src"/>
  +  <property name="web.home"      value="${basedir}/web"/>
  +
  +
  +<!-- ================== Custom Ant Task Definitions ======================= -->
  +
  +
  +<!--
   
  +  These properties define custom tasks for the Ant build tool that interact
  +  with the "/manager" web application installed with Tomcat 4.  Before they
  +  can be successfully utilized, you must perform the following steps:
  +
  +  - Copy the file "server/lib/catalina-ant.jar" from your Tomcat 4
  +    installation into the "lib" directory of your Ant installation.
  +
  +  - Create a "build.properties" file in your application's top-level
  +    source directory (or your user login home directory) that defines
  +    appropriate values for the "manager.password", "manager.url", and
  +    "manager.username" properties described above.
  +
  +  For more information about the Manager web application, and the functionality
  +  of these tasks, see <http://localhost:8080/tomcat-docs/manager-howto.html>.
  +
  +-->
  +
  +  <taskdef name="install" classname="org.apache.catalina.ant.InstallTask"/>
  +  <taskdef name="reload"  classname="org.apache.catalina.ant.ReloadTask"/>
  +  <taskdef name="remove"  classname="org.apache.catalina.ant.RemoveTask"/>
   
   
   <!--  ==================== Compilation Control Options ==================== -->
  @@ -151,8 +221,8 @@
       <fileset dir="${catalina.home}/common/lib">
         <include name="*.jar"/>
       </fileset>
  -    <pathelement location="${catalina.home}/classes"/>
  -    <fileset dir="${catalina.home}/lib">
  +    <pathelement location="${catalina.home}/shared/classes"/>
  +    <fileset dir="${catalina.home}/shared/lib">
         <include name="*.jar"/>
       </fileset>
   
  @@ -170,7 +240,7 @@
   -->
   
     <target name="all" depends="clean,compile"
  -   description="Clean build and dist, then compile"/>
  +   description="Clean build and dist directories, then compile"/>
   
   
   
  @@ -207,41 +277,17 @@
   
       <!-- Compile Java classes as necessary -->
       <mkdir    dir="${build.home}/WEB-INF/classes"/>
  -    <javac srcdir="src"
  +    <javac srcdir="${src.home}"
             destdir="${build.home}/WEB-INF/classes"
  -           debug="${compile.debug}"
  -     deprecation="${compile.deprecation}"
  -        optimize="${compile.optimize}">
  +            debug="${compile.debug}"
  +      deprecation="${compile.deprecation}"
  +         optimize="${compile.optimize}">
           <classpath refid="compile.classpath"/>
       </javac>
   
  -    <!-- Copy associated resource files -->
  +    <!-- Copy application resources -->
       <copy  todir="${build.home}/WEB-INF/classes">
  -    <fileset dir="src" includes="**/*.properties"/>
  -    </copy>
  -
  -  </target>
  -
  -
  -
  -<!-- ==================== Deploy Target =================================== -->
  -
  -<!--
  -
  -  The "deploy" target copies the contents of the build directory into a
  -  location required by our servlet container, and picks up any external
  -  dependencies along the way.  AFter restarting the servlet container, you
  -  can now test your web application.
  -
  --->
  -
  -  <target name="deploy" depends="compile"
  -   description="Deploy application to servlet container">
  -
  -    <!-- Copy the contents of the build directory -->
  -    <mkdir     dir="${deploy.home}"/>
  -    <copy    todir="${deploy.home}">
  -      <fileset dir="${build.home}"/>
  +      <fileset dir="${src.home}" excludes="**/*.java"/>
       </copy>
   
     </target>
  @@ -256,23 +302,26 @@
     The "dist" target creates a binary distribution of your application
     in a directory structure ready to be archived in a tar.gz or zip file.
     Note that this target depends on two others:
  -  * "deploy" so that the entire web application (including external
  +
  +  * "compile" so that the entire web application (including external
       dependencies) will have been assembled
  +
     * "javadoc" so that the application Javadocs will have been created
   
   -->
   
  -  <target name="dist" depends="deploy,javadoc"
  +  <target name="dist" depends="compile,javadoc"
      description="Create binary distribution">
   
  -    <!-- Copy documentation subdirectory -->
  +    <!-- Copy documentation subdirectories -->
  +    <mkdir   todir="${dist.home}/docs"/>
       <copy    todir="${dist.home}/docs">
  -      <fileset dir="docs"/>
  +      <fileset dir="${docs.home}"/>
       </copy>
   
       <!-- Create application JAR file -->
  -    <jar jarfile="${dist.home}/${app.name}.war"
  -         basedir="${deploy.home}"/>
  +    <jar jarfile="${dist.home}/${app.name}=${app.version}.war"
  +         basedir="${build.home}"/>
   
       <!-- Copy additional files to ${dist.home} as necessary -->
   
  @@ -280,6 +329,37 @@
   
   
   
  +<!-- ==================== Install Target ================================== -->
  +
  +<!--
  +
  +  The "install" target tells the specified Tomcat 4 installation to dynamically
  +  install this web application and make it available for execution.  It does
  +  *not* cause the existence of this web application to be remembered across
  +  Tomcat restarts; if you restart the server, you will need to re-install all
  +  this web application.
  +
  +  If you have already installed this application, and simply want Tomcat to
  +  recognize that you have updated Java classes (or the web.xml file), use the
  +  "reload" target instead.
  +
  +  NOTE:  This target will only succeed if it is run from the same server that
  +  Tomcat is running on.
  +
  +-->
  +
  +  <target name="install" depends="compile"
  +   description="Install application to servlet container">
  +
  +    <install url="${manager.url}"
  +        username="${manager.username}"
  +        password="${manager.password}"
  +            path="${app.path}"
  +             war="file://${build.home}"/>
  +
  +  </target>
  +
  +
   <!-- ==================== Javadoc Target ================================== -->
   
   <!--
  @@ -295,9 +375,9 @@
      description="Create Javadoc API documentation">
   
       <mkdir          dir="${dist.home}/docs/api"/>
  -    <javadoc sourcepath="src"
  +    <javadoc sourcepath="${src.home}"
                   destdir="${dist.home}/docs/api"
  -           packagenames="*"/>
  +           packagenames="*">
         <classpath refid="compile.classpath"/>
       </javadoc>
   
  @@ -320,10 +400,15 @@
   
     <target name="prepare">
   
  -    <!-- Create build directory and copy static content -->
  +    <!-- Create build directories as needed -->
       <mkdir  dir="${build.home}"/>
  +    <mkdir  dir="${build.home}/WEB-INF"/>
  +    <mkdir  dir="${build.home}/WEB-INF/classes"/>
  +
  +
  +    <!-- Copy static content of this web application -->
       <copy todir="${build.home}">
  -      <fileset dir="web"/>
  +      <fileset dir="${web.home}"/>
       </copy>
   
       <!-- Copy external dependencies as required -->
  @@ -334,9 +419,52 @@
   -->
   
       <!-- Copy static files from external dependencies as needed -->
  +    <!-- *** CUSTOMIZE HERE AS REQUIRED BY YOUR APPLICATION *** -->
   
     </target>
   
  +
  +<!-- ==================== Reload Target =================================== -->
  +
  +<!--
  +
  +  The "reload" target tells the specified Tomcat 4 installation to dynamically
  +  reload this web application, to reflect changes in the underlying classes or
  +  the "web.xml" deployment descriptor.
  +
  +-->
  +
  +  <target name="reload"
  +   description="Reload application on servlet container">
  +
  +    <reload url="${manager.url}"
  +       username="${manager.username}"
  +       password="${manager.password}"
  +           path="${app.path}"/>
  +
  +  </target>
  +
  +
  +<!-- ==================== Remove Target =================================== -->
  +
  +<!--
  +
  +  The "remove" target tells the specified Tomcat 4 installation to dynamically
  +  remove this web application from service.
  +
  +  NOTE:  This is the logical opposite of the "install" target.
  +
  +-->
  +
  +  <target name="remove"
  +   description="Remove application on servlet container">
  +
  +    <remove url="${manager.url}"
  +       username="${manager.username}"
  +       password="${manager.password}"
  +           path="${app.path}"/>
  +
  +  </target>
   
   
   </project>
  
  
  
  1.5       +47 -2     jakarta-tomcat-4.0/webapps/tomcat-docs/appdev/deployment.xml
  
  Index: deployment.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/tomcat-docs/appdev/deployment.xml,v
  retrieving revision 1.4
  retrieving revision 1.5
  diff -u -r1.4 -r1.5
  --- deployment.xml	12 Oct 2001 17:09:37 -0000	1.4
  +++ deployment.xml	29 Jan 2002 19:32:11 -0000	1.5
  @@ -100,6 +100,46 @@
   </section>
   
   
  +<section name="Shared Library Files">
  +
  +<p>Like most servlet containers, Tomcat 4 also supports mechanisms to install
  +library JAR files (or unpacked classes) once, and make them visible to all
  +installed web applications (without having to be included inside the web
  +application itself.  The details of how Tomcat locates and shares such
  +classes are described in the
  +<a href="../class-loader-howto.html">Class Loader HOW-TO</a> documentation.
  +For the purposes of our discussion, there are two locations that are commonly
  +used within a Tomcat 4 installation for shared code:</p>
  +<ul>
  +<li><strong>$CATALINA_HOME/common/lib</strong> - JAR files placed here
are
  +    visible both to web applications and internal Tomcat code.  This is a
  +    good place to put JDBC drivers that are required for both your application
  +    and internal Tomcat use (such as for a JDBCRealm).
  +    <br/><br/></li>
  +<li><strong>$CATALINA_HOME/shared/lib</strong> - JAR files placed here
are
  +    visible to all web applications, but not to internal Tomcat code.  This
  +    is the right place for shared libraries that are specific to your
  +    application.<br/><br/></li>
  +</ul>
  +
  +<p>Out of the box, a standard Tomcat 4 installation includes a variety
  +of pre-installed shared library files, including:</p>
  +<ul>
  +<li>The <em>JavaMail 1.2</em> (and associated <em>JavaBeans Activation
  +    Framework</em>) APIs, so you can write mail-enabled web applications.
  +    <br/><br/></li>
  +<li>The <em>JDBC 2.0 Optional Package</em> APIs, which define things
like
  +    <code>javax.sql.DataSource</code>.<br/><br/></li>
  +<li>The <em>Servlet 2.3</em> and <em>JSP 1.2</em> APIs that
are fundamental
  +    to writing servlets and JavaServer Pages.<br/><br/></li>
  +<li>An <em>XML Parser</em> compliant with the JAXP (version 1.1) APIs,
so
  +    your application can perform DOM-based or SAX-based processing of
  +    XML documents.<br/><br/></li>
  +</ul>
  +
  +</section>
  +
  +
   <section name="Web Application Deployment Descriptor">
   
       <blockquote><em>
  @@ -172,6 +212,11 @@
       deploy and undeploy applications on a running Tomcat server without
       restarting it.  See the administrator documentation (TODO: hyperlink)
       for more information on using the Manager web application.<br/><br/></li>
  +<li><em>Use "Manager" Ant Tasks In Your Build Script</em>.  Tomcat 4
  +    includes a set of custom task definitions for the <code>Ant</code>
  +    build tool that allow you to automate the execution of commands to the
  +    "Manager" web application.  These tasks are used in the example
  +    build script discussed later, and are explained there.<br/><br/></li>
   <li><em>Add a <code>&lt;Context&gt;</code> entry in the
       <code>$CATALINA_HOME/conf/server.xml</code> configuration file</em>.
       This approach is described briefly below, and allows you to position
  @@ -186,8 +231,8 @@
   container, but all containers compatible with the Servlet API Specification
   (version 2.2 or later) are required to accept a web application archive file.
   Note that other containers are <strong>NOT</strong> required to accept an
  -unpacked directory structure (as Tomcat does), but this feature is commonly
  -available.</p>
  +unpacked directory structure (as Tomcat does), or to provide mechanisms for
  +shared library files, but these features are commonly available.</p>
   
   </section>
   
  
  
  
  1.3       +1 -1      jakarta-tomcat-4.0/webapps/tomcat-docs/appdev/installation.xml
  
  Index: installation.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/tomcat-docs/appdev/installation.xml,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- installation.xml	5 Aug 2001 03:42:28 -0000	1.2
  +++ installation.xml	29 Jan 2002 19:32:11 -0000	1.3
  @@ -54,7 +54,7 @@
   
   <p>Binary downloads of the <strong>Ant</strong> build tool are available
from
   <a href="http://jakarta.apache.org/downloads/binindex.html">http://jakarta.apache.org/downloads/binindex.html</a>.
  -This manual assumes you are using Ant 1.3.  The instructions should
  +This manual assumes you are using Ant 1.4 or later.  The instructions should
   also be compatible with later versions, but this has not been tested.</p>
   
   <p>Download and install Ant from the distribution directory mentioned above.
  
  
  
  1.4       +89 -65    jakarta-tomcat-4.0/webapps/tomcat-docs/appdev/processes.xml
  
  Index: processes.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/tomcat-docs/appdev/processes.xml,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- processes.xml	14 Nov 2001 00:36:21 -0000	1.3
  +++ processes.xml	29 Jan 2002 19:32:11 -0000	1.4
  @@ -31,13 +31,38 @@
   will need to figure out the corresponding commands for your system.</p>
   
   
  +<subsection name="One-Time Setup of Ant and Tomcat for Development">
  +
  +<p>In order to take advantage of the special Ant tasks that interact with the
  +<em>Manager</em> web application, you need to perform the following tasks
  +once (no matter how many web applications you plan to develop).</p>
  +<ul>
  +<li><em>Configure the Ant custom tasks</em>.  The implementation code
for the
  +    Ant custom tasks is in a JAR file named
  +    <code>$CATALINA_HOME/server/lib/catalina-ant.jar</code>, which must be
  +    copied in to the <code>lib</code> directory of your Ant installation.
  +    <br/><br/></li>
  +<li><em>Define one or more Tomcat users</em>.  The <em>Manager</em>
web
  +    application runs under a security constraint that requires a user to be
  +    logged in, and have the security role <code>manager</code> assigned to
  +    him or her.  How such users are defined depends on which Realm you have
  +    configured in Tomcat's <code>conf/server.xml</code> file -- see the
  +    <a href="../realm-howto.html">Realm Configuration HOW-TO</a> for more
  +    information.  You may define any number of users (with any username
  +    and password that you like) with the <code>manager</code> role.
  +    <br/><br/></li>
  +</ul>
  +
  +</subsection>
  +
  +
   <subsection name="Create Project Source Code Directory">
   
   <p>The first step is to create a new project source directory, and customize
  -the <code>build.xml</code> and build script you will be using.  The directory
  -structure is described in <a href="source.html">the previous section</a>,
  -or you can use the <a href="sample">sample application</a> as a starting
  -point.</p>
  +the <code>build.xml</code> and <code>build.properties</code> files
you will
  +be using.  The directory structure is described in <a href="source.html">the
  +previous section</a>, or you can use the
  +<a href="sample">sample application</a> as a starting point.</p>
   
   <p>Create your project source directory, and define it within your CVS
   repository.  This might be done by a series of commands like this, where
  @@ -80,6 +105,30 @@
   development directory.  Committing makes those changes visible to other
   developers on your team that are sharing the same CVS repository.</p>
   
  +<p>The next step is to customize the Ant <em>properties</em> that are
  +named in the <code>build.xml</code> script.  This is done by creating a
  +file named <code>build.properties</code> in your project's top-level
  +directory.  The supported properties are listed in the comments inside
  +the sample <code>build.xml</code> script.  At a minimum, you will generally
  +need to define the <code>catalina.home</code> property defining where
  +Tomcat 4 is installed, and the manager application username and password.
  +You might end up with something like this:</p>
  +<source>
  +# Context path to install this application on
  +app.path=/hello
  +
  +# Tomcat 4 installation directory
  +catalina.home=/usr/local/jakarta-tomcat-4.0
  +
  +# Manager webapp username and password
  +manager.username=myusername
  +manager.password=mypassword
  +</source>
  +
  +<p>In general, you will <strong>not</strong> want to check the
  +<code>build.properties</code> file in to the CVS repository, because it
  +is unique to each developer's environment.</p>
  +
   <p>Now, create the initial version of the web application deployment
   descriptor.  You can base <code>web.xml</code> on the
   <a href="web.xml.txt">basic web.xml file</a>, or code it from scratch.</p>
  @@ -94,51 +143,6 @@
   </subsection>
   
   
  -<subsection name="Customize for Tomcat Location">
  -
  -<p>In order for Tomcat to recognize your application, you must deploy it
  -as described under <a href="deployment.html">Deployment</a>.  Any of the
  -proposed techniques can be used.  For our purposes, we will assume that
  -you are using the <em>unpacked directory hierarchy</em> approach, and a
  -<code>build.xml</code> script based on the example included with this manual.
  -</p>
  -
  -<p>In order to successfully execute the <code>deploy</code> target, you
  -must ensure that the <code>catalina.home</code> property receives the
  -correct value, which must be the pathname of the directory into which you
  -have installed Tomcat 4.  You can make this customization by one of the
  -following techniques:</p>
  -<ul>
  -<li>Change the property definition in the <code>build.xml</code> file
so
  -    that it reflects the Tomcat 4 location.  The modified property setting
  -    might look like this:
  -<source>
  -&lt;property name="catalina.home" value="/usr/local/jakarta-tomcat-4.0"/&gt;
  -</source></li>
  -<li>Set up a <code>build.properties</code> file in your top-level source
  -    directory that defines the location oF Tomcat.  For example, the file
  -    might contain:
  -<source>
  -catalina.home=/usr/local/jakarta-tomcat-4.0
  -</source></li>
  -</ul>
  -
  -<p>The first technique would be appropriate if all of your developers are
  -sharing a common copy of Tomcat 4 for their deployment and testing.  If,
  -however, each developer is using their own copy of Tomcat 4, in separate
  -directories, the latter technique is preferred (because it lets each
  -developer define their own value for the <code>catalina.home</code>
  -property.</p>
  -
  -<p><strong>NOTE</strong> - If you utilize the <code>build.properties</code>
  -approach, be sure that you do <strong>NOT</strong> check in the
  -<code>build.properties</code> file for any of your developers in to the
  -source code archives.  For this reason, the <code>.cvsignore</code> file
  -you created earlier should include this filename.</p>
  -
  -</subsection>
  -
  -
   <subsection name="Edit Source Code and Pages">
   
   <p>The edit/build/test tasks will generally be your most common activities
  @@ -216,20 +220,42 @@
   
   <subsection name="Test Your Web Application">
   
  -<p>To test your application, you will want to deploy it under Tomcat.  If you
  -have customized the <code>catalina.home</code> property as described above,
  -this is very easy.  First, deploy the application into Tomcat:</p>
  -<source>
  -cd {my home directory}
  -cd myapp
  -ant deploy
  -</source>
  -
  -<p>and then restart Tomcat.  To access your application, point your
  -browser at <code>http://localhost:8080/myapp/</code> and begin testing.
  -When you discover something that needs to change, fix it in
  -the source directory (not in the Tomcat deployment directory), redeploy,
  -and restart Tomcat.</p>
  +<p>To test your application, you will want to install it under Tomcat.  The
  +quickest way to do that is to use the custom Ant tasks that are included in
  +the sample <code>build.xml</code> script.  Using these commands might follow
  +a pattern like this:</p>
  +<ul>
  +<li><em>Start Tomcat 4 if needed</em>.  If Tomcat 4 is not already running,
  +    you will need to start it in the usual way.
  +    <br/><br/></li>
  +<li><em>Compile your application</em>.  Use the <code>ant compile</code>
  +    command (or just <code>ant</code>, since this is the default).  Make
  +    sure that there are no compilation errors.
  +    <br/><br/></li>
  +<li><em>Install the application</em>.  Use the <code>ant install</code>
  +    command.  This tells Tomcat to immediately start running your app on
  +    the context path defined in the <code>app.path</code> build property.
  +    Tomcat does <strong>NOT</strong> have to be restarted for this to
  +    take effect.<br/><br/></li>
  +<li><em>Test the application</em>.  Using your browser or other testing
  +    tools, test the functionality of your application.
  +    <br/><br/></li>
  +<li><em>Modify and rebuild as needed</em>.  As you discover that changes
  +    are required, make those changes in the original <strong>source</strong>
  +    files, not in the output build directory, and re-issue the
  +    <code>ant compile</code> command.  This ensures that your changes will
  +    be available to be saved (via <code>cvs commit</code>) later on --
  +    the output build directory is deleted and recreated as necessary.
  +    <br/><br/></li>
  +<li><em>Reload the application</em>.  Tomcat will recognize changes in
  +    JSP pages automatically, but it will continue to use the old versions
  +    of any servlet or JavaBean classes until the application is reloaded.
  +    You can trigger this by executing the <code>ant reload</code> command.
  +    <br/><br/></li>
  +<li><em>Remove the application when you re done</em>.  When you are through
  +    working on this application, you can remove it from live execution by
  +    running the <code>ant remove</code> command.</li>
  +</ul>
   
   <p>Do not forget to commit your changes to the source code repository when
   you have completed your testing!</p>
  @@ -261,8 +287,6 @@
   </ul>
   
   </subsection>
  -
  -
   
   
   </section>
  
  
  
  1.4       +41 -24    jakarta-tomcat-4.0/webapps/tomcat-docs/appdev/source.xml
  
  Index: source.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/tomcat-docs/appdev/source.xml,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- source.xml	27 Aug 2001 20:22:37 -0000	1.3
  +++ source.xml	29 Jan 2002 19:32:11 -0000	1.4
  @@ -86,10 +86,12 @@
   <li><strong>build/</strong> - When you execute a default build
       (<code>ant</code>), this directory will contain an exact image
       of the files in the web application archive for this application.
  -    For containers like Tomcat that allow you to deploy
  -    unpacked directory structures, you need only copy this directory structure
  -    into a subdirectory of <code>$CATALINA_HOME/webapps</code> in order to
  -    deploy and test it.<br/><br/></li>
  +    Tomcat 4 allows you to deploy an application in an unpacked
  +    directory like this, either by copying it to the
  +    <code>$CATALINA_HOME/webapps</code> directory, or by <em>installing</em>
  +    it via the "Manager" web application.  The latter approach is very
  +    useful during development, and will be illustrated below.
  +    <br/><br/></li>
   <li><strong>dist/</strong> - When you execute the <code>ant dist</code>
       target, this directory will be created.  It will create an exact image
       of the binary distribution for your web application, including an license
  @@ -120,7 +122,7 @@
     <p>Therefore, this manual recommends that you <strong>NOT</strong>
store
     a copy of the packages you depend on inside the source control archives
     of your applications.  Instead, the external dependencies should be
  -  integrated as part of the process of <strong>deploying</strong> your
  +  integrated as part of the process of <strong>building</strong> your
     application.  In that way, you can always pick up the appropriate version
     of the JAR files from wherever your development system administrator has
     installed them, without having to worry about updating your application
  @@ -133,6 +135,12 @@
     developer can be customized on a per-application basis, or defaulted to
     "standard" build properties stored in the developer's home directory.</p>
   
  +  <p>In many cases, your development system administrator will have already
  +  installed the required JAR files into Tomcat 4's <code>common/lib</code>
  +  or <code>shared/lib</code> directories.  If this has been done, you need
  +  to take no actions at all - the example <code>build.xml</code> file
  +  automatically constructs a compile classpath that includes these files.</p>
  +
     </subsection>
   
   </section>
  @@ -233,35 +241,20 @@
       you have not made source code modifications that will result in
       problems at runtime due to not recompiling all affected classes.
       <br/><br/></li>
  -<li><strong>prepare</strong> - This target "prepares" the <code>build</code>
  -    directory, creating subdirectories as required.  A common use of this
  -    target is to copy static files (documentation, HTML pages, and JSP pages)
  -    from the source directory to the build directory.  When
  -    executed, this target will only create directories if they do not
  -    exist, and only copy files if the destination file does not exist,
  -    or the source version of the file is newer.  This target is generally
  -    invoked indirectly, by virtue of a <code>depends</code> attribute on
  -    some other task.
  -    <br/><br/></li>
   <li><strong>compile</strong> - This target is used to compile any source
code
       that has been changed since the last time compilation took place.  The
  -    resulting class files are created in the <code>build</code> directory,
so
  -    that they can be executed when the application is deployed.  Because
  +    resulting class files are created in the <code>WEB-INF/classes</code>
  +    subdirectory of your <code>build</code> directory, exactly where the
  +    structure of a web application requires them to be.  Because
       this command is executed so often during development, it is normally
       made the "default" target so that a simple <code>ant</code> command will
       execute it.
       <br/><br/></li>
   <li><strong>all</strong> - This target is a short cut for running the
  -    <code>clean</code> target, followed by the <code>compiile</code>
target.
  +    <code>clean</code> target, followed by the <code>compile</code>
target.
       Thus, it guarantees that you will recompile the entire application, to
       ensure that you have not unknowingly introduced any incompatible changes.
       <br/><br/></li>
  -<li><strong>deploy</strong> - This target is used to install your
  -    application into a servlet container (we will continue to use Tomcat
  -    in our examples) so that it can be tested.  If your application requires
  -    external JAR files, they will be copied to the <code>/WEB-INF/lib</code>
  -    directory at deployment time.
  -    <br/><br/></li>
   <li><strong>javadoc</strong> - This target creates Javadoc API documentation
       for the Java classes in this web application.  The example
       <code>build.xml</code> file assumes you want to include the API
  @@ -279,6 +272,30 @@
       web application archive will have also picked up any external dependencies
       that were included at deployment time.</li>
   </ul>
  +
  +<p>For interactive development and testing of your web application using
  +Tomcat 4, the following additional targets are defined:</p>
  +<ul>
  +<li><strong>install</strong> - Tell the currently running Tomcat 4 to
make
  +    the application you are developing immediately available for execution
  +    and testing.  This action does not require Tomcat 4 to be restarted, but
  +    it is also not remembered after Tomcat is restarted the next time.
  +    <br/><br/></li>
  +<li><strong>reload</strong> - Once the application is installed, you
can
  +    continue to make changes and recompile using the <code>compile</code>
  +    target.  Tomcat 4 will automatically recognize changes made to JSP pages,
  +    but not to servlet or JavaBean classes - this command will tell Tomcat
  +    to restart the currently installed application so that such changes are
  +    recognized.
  +    <br/><br/></li>
  +<li><strong>remove</strong> - When you have completed your development
and
  +    testing activities, you can optionally tell Tomcat 4 to remove this
  +    application from service.
  +    </li>
  +</ul>
  +
  +<p>Using the development and testing targets requires some additional
  +one-time setup that is described on the next page.</p>
   
   </section>
   
  
  
  

--
To unsubscribe, e-mail:   <mailto:tomcat-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:tomcat-dev-help@jakarta.apache.org>


Mime
View raw message