Developing Applications with Tomcat

Source Organisation

Directory Structure

A key recommendation is to separate the directory hierarchy containing your source code 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.

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 (in the doc/appdev folder) 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. The following targets are generally provided:

• init - The initialization target is not executed directly. Instead, it is invoked indirectly (by virtue of a depends 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.

• 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. A cool feature of the Ant javac 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 build.

• 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.

Batch Scripts

The primary script we will utilize is generically called the build script. It executes Ant, which reads and processes the build.xml 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.

On Windows-based systems, the following script should be saved as file build.bat in the project source directory, and customzed as required:

• Setting the JAVA_HOME and TOMCAT_HOME environment variables (probably near the top of the script) if they are not defined already.

• Overriding properties defined in the build.xml file with default values. For example, to change the distribution home directory (property dist.home), you would include the following command line option after the word "java": -Ddist.home=xxxxx.