You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by cr...@locus.apache.org on 2000/03/28 02:44:13 UTC
cvs commit: jakarta-tomcat/src/doc/appdev build.xml.txt contents.html deployment.html installation.html introduction.html processes.html source.html build.html
craigmcc 00/03/27 16:44:13
Modified: src/doc/appdev build.xml.txt contents.html deployment.html
installation.html introduction.html processes.html
source.html
Removed: src/doc/appdev build.html
Log:
General cleanup and enhancement to the Application Developer's Guide.
NOTE: The "sample" application referenced in the Table of Contents does
not currently exist -- that will be added shortly, as soon as it's debugged.
Revision Changes Path
1.2 +7 -9 jakarta-tomcat/src/doc/appdev/build.xml.txt
Index: build.xml.txt
===================================================================
RCS file: /home/cvs/jakarta-tomcat/src/doc/appdev/build.xml.txt,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- build.xml.txt 2000/03/05 05:35:18 1.1
+++ build.xml.txt 2000/03/28 00:44:11 1.2
@@ -28,12 +28,6 @@
and TOMCAT_HOME environment variables into the "ant.home" and
"tomcat.home" properties, which are normally not defined explicitly.
- ant.home The name of the base directory in which
- Ant has been installed.
-
- build.compiler The compiler used by the <javac> task.
- See the ANT documentation for more information.
-
deploy.home The name of the directory into which the
deployment hierarchy will be created.
Normally, this will be the name of a
@@ -45,17 +39,20 @@
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.
+ 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:
@@ -64,7 +61,8 @@
-->
<target name="init"
- <property name="build.compiler" value="classic"/>
+ <!-- Property values defined here can be overridden by defining
+ corresponding Java system properties on the Ant command line. -->
<property name="deploy.home" value="${tomcat.home}/webapps/myapp"/>
<property name="dist.home" value="${deploy.home}"/>
<property name="dist.src" value="myapp.jar"/>
1.2 +14 -6 jakarta-tomcat/src/doc/appdev/contents.html
Index: contents.html
===================================================================
RCS file: /home/cvs/jakarta-tomcat/src/doc/appdev/contents.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- contents.html 2000/03/05 05:35:18 1.1
+++ contents.html 2000/03/28 00:44:11 1.2
@@ -23,6 +23,7 @@
<td align="center" colspan=3>
<a href="#Credits">Credits</a>
<a href="#Contents">Contents</a>
+ <a href="#Sample">Sample</a>
</td>
</tr>
</table>
@@ -37,9 +38,10 @@
developer community. The following authors have provided significant content:
<ul>
<li>Craig R. McClanahan
- (<a href="mailto:cmcclanahan@mytownnet.com">cmcclanahan@mytownnet.com</a>)
+ (<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>
@@ -61,15 +63,21 @@
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="build.html"><b>BUILD.XML Details</b></a> -
- Outlines the structure and contents of a recommended
- <code>build.xml</code> file in detail, based on the
- deployment and source directory organizations described
- in earlier sections.
<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>
1.2 +56 -12 jakarta-tomcat/src/doc/appdev/deployment.html
Index: deployment.html
===================================================================
RCS file: /home/cvs/jakarta-tomcat/src/doc/appdev/deployment.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- deployment.html 2000/03/05 05:35:18 1.1
+++ deployment.html 2000/03/28 00:44:11 1.2
@@ -44,7 +44,7 @@
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, described further below. Such a hierarchy can be
+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,
@@ -68,8 +68,8 @@
<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 format as required by the WAR format itself. To do
-this, you will end up with the following contents in your
+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
@@ -106,7 +106,7 @@
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 require), you will simplify the installation of your web application --
+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
@@ -127,8 +127,8 @@
<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>
+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.
@@ -137,7 +137,10 @@
<a name="Integration"></a>
<h2>3.4 Integration With Tomcat</h2>
-<p>A web application can be deployed in Tomcat by one of three different
+<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
@@ -154,17 +157,58 @@
vendor or by your internal development staff, into an existing
Tomcat installation.
<br><br>
-<li><i>Add a <code><context></code> entry in the Tomcat
+<li><i>Add a <code><Context></code> entry in the Tomcat
<code>server.xml</code> configuration file</i>. This approach is
described briefly below, and allows you to position the document root
of your web application at some point other than the
- <code>$TOMCAT_HOME/webapps/</code> directory.
+ <code>$TOMCAT_HOME/webapps/</code> directory. Doing this requires
+ the following steps (for Tomcat 3.1):
</ul>
-<p>TODO - Describe adding a context to <code>server.xml</code>.
+<p>Adding a new <code><Context></code> entry in Tomcat's
+<code>server.xml</code> file involves the following steps (for Tomcat 3.1):
+<ul>
+<li>Open file <code>$TOMCAT_HOME/conf/server.xml</code> in an editor.
+ <br><br>
+<li>Navigate to the bottom of the file (after the last existing
+ <code><Context></code> element.
+ <br><br>
+<li>Add a new <code><Context></code> element for your application,
+ using the existing examples as a guide. The following attributes are
+ supported:
+ <ul>
+ <li><b>path</b>. The <i>context path</i> for your application, which
+ is the prefix of a request URI that tells Tomcat which application
+ should be used to process this request. For example, if you set
+ your path to "/catalog", any request URI beginning with "/catalog"
+ will be processed by this application. This attribute is requrired,
+ and must start with a slash ('/') character.
+ <li><b>docBase</b>. The <i>document root</i> directory for this web
+ application. This can be a relative path (relative to the
+ directory in which Tomcat is started), or an absolute path, to the
+ directory containing your app. On a Windows platform, you must
+ 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.2 +23 -30 jakarta-tomcat/src/doc/appdev/installation.html
Index: installation.html
===================================================================
RCS file: /home/cvs/jakarta-tomcat/src/doc/appdev/installation.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- installation.html 2000/03/05 05:35:18 1.1
+++ installation.html 2000/03/28 00:44:11 1.2
@@ -43,16 +43,8 @@
<p>Compatible JDKs for many platforms (or links to where they can be found)
are available at
-<a href="http://java.sun.com/jdk/">http://java.sun.com/jdk/</a>.
+<a href="http://java.sun.com/jdk/" target="_top">http://java.sun.com/jdk/</a>.
-<p>The shell command line examples in this manual assume that you have
-set the <code>JAVA_HOME</code> environment variable to point at the base
-directory where you have installed the JDK (such as
-<code>/usr/local/jdk1.2.2</code>), have added the
-<code>$JAVA_HOME/bin</code> directory to your <code>PATH</code>
-environment variable (so that the compiler and other executable
-components can be located), and have initialized the
-<code>CLASSPATH</code> environment variable if necessary.
<!-- 2.2 Tomcat -->
<a name="Tomcat"></a>
@@ -66,33 +58,34 @@
concepts are very similar.
<p>The shell command line examples in this manual assume that you have
-set the <code>TOMCAT_HOME</code> environment variable to point at the
-base directory where you have installed Tomcat (such as
-<code>/usr/local/tomcat</code>), and have added the
-<code>$TOMCAT_HOME/bin</code> directory to your <code>PATH</code>
-environment variable. No adjustment to the <code>CLASSPATH</code>
-environment variable is normally required, unless your application
-requires additional Java classes or JAR files to be added to the
-system classpath.
+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.2.2</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>Binary downloads of the Ant development tool are available from the
+<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. This manual assumes you are using the most recent milestone,
-beta, or release of Tomcat 3.1 -- many of the deployment details
-have changed since Tomcat 3.0 was released, although the general
-concepts are very similar.
-
-<p>The shell command line examples in this manual assume that you have
-set the <code>ANT_HOME</code> environment variable to point at the
-base directory where you have installed Ant (such as
-<code>/usr/local/ant</code>), and have added the
-<code>$ANT_HOME/bin</code> directory to your <code>PATH</code>
-environment variable. No adjustment to the <code>CLASSPATH</code>
-environment variable is normally required.
+page.
<!-- 2.4 CVS -->
1.2 +11 -5 jakarta-tomcat/src/doc/appdev/introduction.html
Index: introduction.html
===================================================================
RCS file: /home/cvs/jakarta-tomcat/src/doc/appdev/introduction.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- introduction.html 2000/03/05 05:35:18 1.1
+++ introduction.html 2000/03/28 00:44:11 1.2
@@ -63,7 +63,7 @@
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">http://java.sun.com/products/jsp/download.html</a> -
+<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
@@ -73,7 +73,7 @@
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">http://java.sun.com/products/servlet/download.html</a> -
+<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
@@ -82,16 +82,22 @@
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/">API
- Documentation</a> is available online, as well as being part of the
+ <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/">http://java.sun.com/j2ee/blueprints/</a> -
+<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="../uguide/tomcat_ug.html" target="_top">../uguide/tomcat_ug.html</a> -
+ <i>Tomcat - A Minimalistic User's Guide</i>. This document covers the
+ detailed steps required to download and install Tomcat, including
+ configuration for a variety of environments. This guide is included
+ with the Tomcat binary downloads, in the "doc/uguide" subdirectory.
<br><br>
<li><b>TODO</b> -- Add more entries here!
</ul>
1.2 +238 -38 jakarta-tomcat/src/doc/appdev/processes.html
Index: processes.html
===================================================================
RCS file: /home/cvs/jakarta-tomcat/src/doc/appdev/processes.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- processes.html 2000/03/05 05:35:18 1.1
+++ processes.html 2000/03/28 00:44:11 1.2
@@ -10,7 +10,7 @@
<table border=0 width="100%">
<tr>
<td align="left" width="25%">
- <a href="build.html">Previous</a>
+ <a href="source.html">Previous</a>
</td>
<td align="center" width="50%">
<a href="contents.html">Top</a>
@@ -21,54 +21,254 @@
</tr>
<tr>
<td align="center" colspan=3>
- <a href="#Credits">Credits</a>
- <a href="#Contents">Contents</a>
+ <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>6. Development Processes</h1>
+<h1>5. Development Processes</h1>
-<!-- 0.1 Credits -->
-<a name="Credits"></a>
-<h2>0.1 Credits</h2>
+<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>This manual includes contributions from many members of the Jakarta Project
-developer community. The following authors have provided significant content:
+<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 <-- 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
+</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>Craig R. McClanahan
- (<a href="mailto:cmcclanahan@mytownnet.com">cmcclanahan@mytownnet.com</a>)
+<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!
+
-<!-- 0.2 Contents -->
-<a name="Contents"></a>
-<h2>0.2 Contents</h2>
+<!-- 5.6 Deploy -->
+<a name="Deploy"></a>
+<h2>5.6 Deploy Your Web Application</h2>
-<p>The information presented is divided into the following sections:
+<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><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</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</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="build.html"><b>BUILD.XML</b></a> -
- Outlines the structure and contents of a recommended
- <code>build.xml</code> file in detail, based on the
- deployment and source directory organizations described
- in earlier sections.
-<li><a href="processes.html"><b>Processes</b></a> -
- Provides brief descriptions of typical development processes
- utilizing the recommended deployment and source organizations.
+<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>
1.2 +132 -11 jakarta-tomcat/src/doc/appdev/source.html
Index: source.html
===================================================================
RCS file: /home/cvs/jakarta-tomcat/src/doc/appdev/source.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- source.html 2000/03/05 05:35:18 1.1
+++ source.html 2000/03/28 00:44:11 1.2
@@ -16,7 +16,7 @@
<a href="contents.html">Top</a>
</td>
<td align="right" width="25%">
- <a href="build.html">Next</a>
+ <a href="processes.html">Next</a>
</td>
</tr>
<tr>
@@ -62,7 +62,7 @@
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
-"project directory" for your application:
+<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.
@@ -103,8 +103,8 @@
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 the top level directory of your source
- hierarchy and execute <code>cvs update -d</code>.
+ 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>.
@@ -117,15 +117,21 @@
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, these changes
+<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 top level directory of your source hierarchy
+ 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>
@@ -142,18 +148,133 @@
<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 top-level directory of your source
-code hierarchy. This file includes comments that describe the various
-components. In the following section, scripts will be described that use
-Ant to build your project based on the contents of the <code>build.xml</code>
-file found there.
+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>init</b> - The initialization target is not executed directly.
+ Instead, it is invoked indirectly (by virtue of a <code>depends</code>
+ attribute) by all other build targets. This is a convenient place
+ to create defaults for property values, which can be overridden by
+ system properties on the command line that starts Ant.
+ <br><br>
+<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. A cool feature
+ of the Ant <code>javac</code> task is that it also copies any non-Java
+ source files to corresponding places in the deployment directory, while
+ maintaining the appropriate package hierarchy. This is perfect for
+ properties files that you reference as resource bundles. The "compile"
+ target is generally defined as the default target for your project,
+ so it will be executed when you simply type <code>build</code>.
+<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</code> in the project source directory, with file permissions
+that make it executable, and customized as required:
+
+<pre>
+#!/bin/sh
+# build -- Build Script for "My Application"
+# $Id: source.html,v 1.2 2000/03/28 00:44:11 craigmcc Exp $
+
+# Identify the custom class path components we need
+CP=$TOMCAT_HOME/classes:$TOMCAT_HOME/lib/ant.jar:$TOMCAT_HOME/lib/xml.jar
+CP=$CP:$TOMCAT_HOME/lib/jasper.jar:$TOMCAT_HOME/lib/servlet.jar
+CP=$CP:$TOMCAT_HOME/lib/webserver.jar
+
+# Execute ANT to perform the requested build target
+java -Dtomcat.home=$TOMCAT_HOME -classpath $CP:$CLASSPATH \
+ org.apache.tools.ant.Main "$@"
+
+</pre>
+
+<p>On Windows-based systems, the following script should be saved as file
+<code>build.bat</code> in the project source directory, and customzed
+as required:
+
+<pre>
+
+echo off
+rem Build Script for "My Application"
+rem $Id: source.html,v 1.2 2000/03/28 00:44:11 craigmcc Exp $
+
+rem Identify the custom class path we need
+if "%CLASSPATH%" == "" goto noclasspath
+set _CLASSPATH=%CLASSPATH%
+set CLASSPATH=%CLASSPATH%;%TOMCAT_HOME%/classes
+goto restclasspath
+:noclasspath
+set _CLASSPATH=
+set CLASSPATH=%TOMCAT_HOME%/classes
+:restclasspath
+set CLASSPATH=%CLASSPATH%;%TOMCAT_HOME%/lib/ant.jar;%TOMCAT_HOME%/lib/xml.jar
+set CLASSPATH=%CLASSPATH%;%TOMCAT_HOME%/lib/jasper.jar
+set CLASSPATH=%CLASSPATH%;%TOMCAT_HOME%/lib/servlet.jar
+set CLASSPATH=%CLASSPATH%;%TOMCAT_HOME%/lib/webserver.jar
+
+rem Execute ANT to perform the requested build target
+java -Dtomcat.home=%TOMCAT_HOME% org.apache.tools.ant.Main %1 %2 %3 %4 %5 %6 %7 %8 %9
+
+rem Clean up CLASSPATH
+set CLASSPATH=%_CLASSPATH%
+set _CLASSPATH=
+</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>