4. SOURCE ORGANIZATION

4.1 Directory Structure

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:

• 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.
  
  
• Source code control is easier to manage on directories that contain only source files.
  
  
• The files that make up an installable distribution of your application are much easier to select when the deployment hierarchy is separate.

As we will see, the ant development tool makes the creation and processing of such directory hierarchies nearly painless.

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 build.xml configuration file that is discussed below. All of these components exist under a top level project source directory for your application:

• etc/ - Directory containing special files related to your application that will be copied to the WEB-INF directory. In all cases, this will include the application deployment descriptor file (web.xml), but may include others as well.
  
  
• lib/ - Directory containing JAR files that will be copied to the WEB-INF/lib deployment directory.
  
  
• src/ - 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.
  
  
• web/ - 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.

4.2 Source Code Control

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.

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:

• To refresh the state of your source code to that stored in the the source repository, go to your project source directory, and execute cvs update -d.
  
  
• When you create a new subdirectory in the source code hierarchy, register it in CVS with a command like cvs add {subdirname}.
  
  
• 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 cvs add {filename}.
  
  
• 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 cvs remove {filename}.
  
  
• 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 cvs commit. 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.

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 Introduction for more information.

4.3 BUILD.XML Configuration File

We will be using the ant 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 build.xml, that defines the processing steps required. Like a Makefile, the build.xml 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.

To give you a head start, a basic build.xml file 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:

• prepare - 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 depends attribute on some other task.
• compile - 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. NOTE - Previous versions of Ant copied properties files and other resource files for you as part of the execution of the <javac> task. You must now do this explicitly.
• javadoc - This target creates Javadoc API documentation for the Java classes in this web application. The example build.xml file assumes you want to include the API documentation with your app, so it generates the docs in a subdirectory of the deployment directory.
• all - 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 build all before you use the "dist" target to create a distribution of your application, to ensure that the distribution contains no unwanted files.
• dist - 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 build.xml file, the contents of the WAR file are based on the most recent build in the deployment directory.

In the following section, scripts will be described that use Ant to compile your project, based on the contents of the build.xml file defined here.

4.4 Shell and Batch Scripts

#!/bin/sh
# build -- Build Script for the "Hello, World" Application
# $Id$

# Identify the custom class path components we need
CP=$CATALINA_HOME/lib/ant.jar:$CATALINA_HOME/lib/servlet.jar
CP=$CP:$CATALINA_HOME/lib/jaxp.jar:$CATALINA_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=$CATALINA_HOME "$@"

@echo off
rem build.bat -- Build Script for the "Hello, World" Application
rem $Id$

set _CP=%CP%

rem Identify the custom class path components we need
set CP=%CATALINA_HOME%\lib\ant.jar;%CATALINA_HOME%\lib\servlet.jar
set CP=%CATALINA_HOME%\lib\jaxp.jar;%CATALINA_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=%CATALINA_HOME% %1 %2 %3 %4 %5 %6 %7 %8 %9

set CP=%_CP%
set _CP=