Java Enterprise in a Nutshell 3rd Edition
Ant Template

Table of Contents

- Quick Start
- Template Overview
- Build Script Details
  - Template Targets
  - Template Properties and Entities
- Application Server Configurations
  - Application Server Properties
  - Application Server Targets
- Web Service Engine Configurations
  - Web Service Engine Properties
  - Web Service Engine Targets

Quick Start

The details of the Ant template are provided below. If you'd like to just dive in and give it a whirl without reading the details below, here's a quick-start guide:

1. Copy the Ant template files to a new directory, or into the top of an existing project directory.
2. Check the `build.properties`, and make any changes to the defaults in the `local-build.properties`. Typically, you'll only need to set the `lib.dir`, and possibly the `java.src.dir`, `config.dir` and `web.dir` properties.
3. Check the `build.xml` file and make any needed adjustments to the entities at the beginning of the file. These are set to reasonable defaults, but you may need to add some project-specific libraries to the `java.compile.classpath` path, add source files to the `project.client.src.files` patternset, etc.
4. Check the target definitions and adjust if needed. You may need to adjust the `create-wars` target to point to include the necessary libraries and web files in the archive, and to pull the correct web deployment descriptor. You may also need to adjust the `create-ejbjars` target for similar reasons. These two targets may also need to be adjusted if your project needs more than one web or EJB archive.
5. Configure your application server and web service engine (if needed). If you're using one of the application servers with configurations provided in `as-configs`, you just set `as.type` to the appropriate value. Look through the application server configuration file and add any necessary property settings to your `local-build.properties`. Do the same for your web service engine, if your project involves web services.
6. Try running the `deploy-app` target and see what breaks.

Template Overview

The Ant template applies the general principles laid out in Ch. 17, with some additional extensions added for the purposes of the book examples. This template is the basis of the build scripts for the book examples, but it is designed to be a generic template that can be used to create your own build scripts for development projects.

The Java Enterprise in a Nutshell (JENT) Ant Template provides the following features:

- Provides a starter build script structure (`build.xml`), with a collection of targets that you can customize to suit your project. These targets cover:
  - Compilation of code (both application code and unit tests)
  - Assembly of J2EE components (web, web service, EJB) and application archives
  - Execution of tests against your code (both simple local JUnit tests and in-container Cactus tests)
  - Deployment of applications to your application server
- Simplified configuration on a per-project or per-developer basis. All project defaults are in a single properties file (`build.properties`), all "local" properties for a given environment (developer's workstation, etc.) are kept in a properties override file (`local-build.properties`).
- Pluggable application server and web service engine configurations, allowing you to use the same build script in multiple environments, if needed. Configurations are included for the JBoss 4, Geronimo 1.0 and WebLogic 9.0 application servers, and for the Axis and JWSDP web service engines.

The template consists of the following files:

- A build script (`build.xml`)
- A default properties file (`build.properties`)
- A local properties file (`local-build.properties`)
- A set of application server "config" files that define key tasks and properties for a given application server (located in the `as-configs` directory)
- A set of web service engine "config" files that serve the same purpose for a given web service engine (located in the `wse-configs` directory)

These files work together in the build template as shown in Figure 1.

Figure 1: Ant Template Structure

The `build.xml` file loads your `local-build.properties` file first, then loads the global `build.properties` file. This allows you to override any properties found in the `build.properties` file, the application server configuration file, and/or the web service engine configuration file, as needed, to suit your environment.

Once the properties for the build script have been set up, the configuration and target definitions suitable for the application server and web service engine are loaded. The target definitions from these configuration files are invoked in the build script to accomplish key tasks, such as deploying applications or creating a component archive.

Build Script Details

Template Targets

The build script template, `build.xml`, includes default definitions for the following targets. All of these targets can be invoked directly by the developer.

During typical development, you'll just need to invoke the `deploy-app` target. Through its dependencies on other targets, invoking this target will compile the application code, assemble your component archives, assemble an application archive and attempt to deploy it. If you're using local and/or server-side unit tests in your development (as you should!), you can use the `run-tests` target. This will compile all your application code and tests, run the local tests, deploy the test-enabled version of the application, and run any server-side tests.

Each of these targets may also use one or more internal support targets, as described below. These support targets my reside in the template `build.xml` directly, or may be imported from either the application server configuration or the web service engine configuration. The default implementations of these targets are designed to be as generic as possible, so that in most cases you can configure the script for a particular project by simply setting the values of the various properties defined immediately after these target descriptions. But in some cases, depending on the needs of the project, these default target definitions may need to be adjusted as well.

`clean`
This target cleans up any artifacts generated by the other targets in the build script. It's meant to remove any binary files, generated files, or anything else that wouldn't be checked into a source code repository or bundled with a source-code distribution for the project. The default implementation deletes the `java.classes.dir` and `java.test.classes.dir` directories, deletes any jar, war or ear files found in the project base directory, deletes any `TEST-*.xml` files generated by the test targets, deletes the `generated.dir` directory, and finally invokes the `as-clean` target from the application server configuration, to clean up any application server-specific artifacts generated by its targets.
`compile`
Compiles all of the project's application code. This target compiles all of the source files in the directory specified by the `java.src.dir` property, using the value of the `project.src.files` patternset as the filter to select the files in this directory to be compiled. The compiled classes are written to the `java.classes.dir` directory.
`compile-clients`
This target compiles any client code in the project. This target is provided separately from the general compile target, to allow for cases where the project's application must be deployed before client code can be compiled, and/or where you want to compile just the client code with doing a full compile of the project. This target compiles all of the source files in the directory specified by the `java.src.dir` property, using the value of the `project.client.src.files` patternset as the filter to select the files in this directory to be compiled. The compiled classes are written to the `java.classes.dir` directory.
`compile-tests`
Compiles all of the project's unit tests. This target compiles all of the source files in the directory specified by the `java.test.src.dir` property, using the `project.test.src.files` patternset as the filter to select the files in this directory to be compiled. The compiled classes are written to the `java.test.classes.dir` directory.
This target depends on the `compile` target, since it's assumed that the unit tests invoke the application code, and therefore need to be compiled against the project classes.
`create-app`
This target compiles all of the project source code, assembles any web or EJB component archives, and assembles these into an application archive. The `create-wars` and `create-ejbjars` support targets are used to assemble any component archives that are part of the application.
The `create-wars` support target, in turn, uses the `as-create-war` target imported from the application server configuration to assemble war files. It may also use the `wse-prepare-service` and `wse-process-war` targets imported from the web service engine configuration, if the web archive includes web service implementations.
Similarly, the `create-ejbjars` support target uses the `as-create-ejb-jar`, `wse-prepare-service` and `wse-process-ejb-jar` targets.
Once the component archive(s) are created, the `create-app` target uses the `as-create-ear` target from the application server configuration to assemble the application archive for the project.
This target depends on the `create-wars` and `create-ejbjars` targets.
`create-test-app`
This target mirrors the `create-app` target, but it generates a test-enabled version of the application. It invokes the `create-test-wars` support target to generate test-enabled web archive(s) (useful if Cactus is being used to run server-side unit tests), and the `create-ejbjars` support target to generate any EJB archives. It then uses the `as-create-ear` support target from the application server configuration to assemble the test-enabled application archive.
This target depends on the `create-test-wars` and `create-ejbjars` targets.
`deploy-app`
This target attempts to deploy the assembled application archive to the application server. It simply invokes the `as-deploy` support target imported from the application server configuration.
This target depends on the `create-app` target.
`deploy-test-app`
This target attempts to deploy the test-enabled application archive to the application server. It simply invokes the `as-deploy` support target imported from the application server configuration.
This target depends on the `create-test-app` and `run-local-tests` targets.
`env`
This target simply prints out the values of some key properties, as a diagnostic tool.
`generate-artifacts`
If the project needs to auto-generate any code or configuration files (e.g., run XDoclet to generate deployment descriptors, or generate JAX-RPC interfaces for a web service from its WSDL descriptor), then this target can be used for these tasks. Once this target is complete, one of the compile targets can be used to build the generated code, and/or the application assembly/deployment targets can be used to include configuration files in the deployed components. You can define this target to perform whatever tasks are necessary for your project (the default implementation does nothing). There are some template support targets (`gen-web-artifacts`, `gen-ejb-artifacts`, `gen-ws-client-stubs`) that you may find useful for generating XDoclet and/or web service artifacts.
`run-tests`
This target runs any tests defined for your project. It does this by invoking the `run-local-tests` and `run-server-tests` targets described below.
This target depends on the `compile-tests` target.
`run-local-tests`
This target runs any local unit tests defined for your project. It uses the Ant `junit` task to run the tests from the `java.test.classes.dir` directory, using the `project.local.test.classes` patternset as the filter to select the test classes to be executed. The `local-tests-failed` property is set if any of the tests fail.
This target depends on the `compile-tests` target.
`run-server-tests`
This target runs any server-side tests defined for your project. It uses the cactus task imported from the Cactus distribution you are using, which is defined by the values of the `cactus.*` properties in the `build.properties`/`local-build.properties`. Any tests found in the `java.test.classes.dir` directory that match the `project.server.test.classes` patternset are run by this target. If any of the tests fail, the `server-tests-failed` property is set.
This target depends on the `deploy-test-app` target, to ensure that the test-enabled application is deployed first.
`verify-app`
This target attempts to verify the project's assembled application, to ensure that it will deploy cleanly to the application server. The target simply invokes the `as-verify-module` support target from the application server configuration, passing it the application archive generated from `create-app` as the module to be verified.
This target depends on the `create-app` target.

Properties and Entities

The following properties and Ant entities are used by the targets above (and their support targets). The text properties can be overridden from their defaults in your `local-build.properties`. The Ant entities (patternsets, classpaths, etc.) can be altered directly in the `build.xml` file.

`as.type`
Default: "jboss"
This property is used to select one of the application server configurations from the as-configs directory. Setting this property to "xxx" causes "as-configs/as-xxx-config.xml" to be imported into the build script.
`as.config.file`
Default: "as-configs/as-${as.type}-config.xml"
This property specifies the actual application server configuration file to import into the build script.
`config.dir`
Default: "config"
The directory where various configuration files are located. These configuration files include web, EJB and application deployment descriptors.
`generated.dir`
Default: "generated"
The directory where all generated artifacts are placed.
`java.classes.dir`
Default: "classes"
The directory where Java classes should be compiled.
`java.debug`
Default: "true"
Whether to generate debuggable class files when compiling Java code.
`java.src.dir`
Default: "src/java"
The directory containing the Java source files for this project.
`java.test.src.dir`
Default: "src/test/java"
The directory containing the Java source files for the tests in this project.
`java.test.classes.dir`
The directory where Java classes for tests should be compiled.
`java.compile.classpath`
This is a path defined in the build.xml that defines the classpath used to compile source code.
`java.test.compile.classpath`
A path defined in the `build.xml` that defines the classpath used to compile test source code.
`lib.dir`
Default: "/usr/local/software"
This property specifies root directory where various support libraries can be found. The template `build.properties` demonstrates the intended use of this property. Various support libraries are referenced starting from the `lib.dir` directory. This allows a developer to place all their third-party libraries into one central place on their workstation, and simply override the `lib.dir` property in their `local-build.properties` to point the build script to their libraries. If necessary, the individual library properties (e.g., `log4j.jar`, `jstl.jar`) can be overridden individually, if the build environment has particular libraries stored in separate libraries for some reason.
`project.src.files`
A patternset defined in the `build.xml` that specifies what source files in the `java.src.dir` are part of the deployed application, rather than client files.
`project.test.src.files`
A patternset defined in the `build.xml` that specifies what source files in the `java.test.src.dir` directory are to be considered test classes.
`project.local.test.classes`
A patternset defined in `build.xml` that specifies the classes in the `java.test.classes.dir` that are local unit test classes, rather than server-side unit tests.
`project.server.test.classes`
A patternset defined in `build.xml` that specifies the classes in the `java.test.classes.dir` that are server-side unit test classes.
`web.dir`
Default: "web"
The directory where web-related files, like HTML, JSP, CSS, images, etc.
`wse.config.file`
Default: "wse-configs/wse-${wse.type}-config.xml"
This property specifies the actual web service engine configuration file to import into the build script.
`wse.type`
Default: "axis"
This property selects one of the web service engine configuration files from the `wse-configs` directory. Setting this property to "xxx" causes "wse-configs/wse-xxx-configs.xml" to be imported into the build script. If you want to load a web service configuration file from a different location, or using a different file naming convention, then set the value of the `wse.config.file` property directly.

Application Server Configurations

Once you've installed an application server, you then need to configure the build script to use it. First, you need to ensure that the appropriate application server configuration file is imported into the main build script. If your application server config file sits in the as-configs directory and is named using the "as-XXX-config.xml" convention, then you can simply override the value of the `as.type` property in your `local-build.properties` file. For example, if you place this in your `local-build.properties`:

`as.type = jboss`

Then the `as-configs/as-jboss-config.xml` configuration file will be imported into the build script. If your application server config file doesn't sit in the `as-configs` directory, and/or doesn't follow the file naming convention, then you can also directly override the value of the `server.config.file` property in your `local-build.properties` file. This property is set to `as-configs/as-${as.type}-config.xml` in the `build.properties`, but you can override it to point directly to any file you choose, e.g.:

`server.config.file = stage-configs/stage-jboss-config.xml`

Application Server Properties

All application server configurations use the following standard properties, which usually have reasonable defaults set for them, but may need to be overridden in your `local-build.properties` file, depending on how your server is set up. You can safely use these properties in your build script as needed.

`as.http.hostname`
The name of the host where the application server is running. If the server is running on the same server as the build script, then you can set this to "localhost". Most of the application server configurations require that the Ant script is run on the same host as the application server. The JBoss configuration, for example, assumes that it can directly copy application archives to the JBoss deployment directory. But some configurations may be able to interface with remote servers for deployment, etc., and the hostname is also used to compose full URLs in some targets.
`as.http.port`
The port used by the application server for web requests. Different application servers use different default web ports (e.g., Tomcat uses 8080, while WebLogic uses 7001), and your application server install may be configured to listen to a custom port.
`as.j2ee.core.classpath`
This is a path variable that specifies the J2EE libraries provided in the application server installation. An application server configuration file typically has this configured based on some base install directory that you provide. This path variable is used in the template `build.xml` as an element of the compilation process.

Each application server configuration file may also have its own set of properties that you need to override in your `local-build.properties` file. The JBoss config file, for example, uses a property named `jboss.home` to indicate the root directory of the JBoss installation. You would need to set this property in your `local-build.properties` to point to your local JBoss directory:

`jboss.home = /opt/jboss-4.0.3`

Review the application server configuration file to see what server-specific properties it requires you to set.

Application Server Targets

Every application server configuration file must provide definitions for the following targets. The build script uses these targets to accomplish key tasks, such as deploying an application. These targets are implemented to suit the application server, and insulate the build script from server-specific details. Note that these targets are NOT meant to be invoked directly, they are only used by the build script within its targets. The only exceptions are the `as-server-start` and `as-server-stop` targets, which are can be used directly by the developer to start/stop the configured application server.

Each target has a set of required and optional properties that it expects the caller to provide. Consult the application server configuration file for details on these properties. You can see the properties in use in the template `build.xml` file where it invokes these application server targets.

`as-clean`
This target cleans up any artifacts generated by the other targets.
`as-create-ear`
This target assembles an application archive from a set of specified component modules. The caller is reponsible for specifying the modules to be included and the deployment descriptor for the archive. The target definition is responsible for including whatever server-specific configuration files the application server requires, and for performing any other server-specific assembly tasks.
`as-create-ejb-jar`
This target assembles an EJB archive from a specified set of files, and stores the ejb-jar file using a specified name in a specified location. The caller is responsible for specifying the classes, libraries, and location of deployment descriptors to be used to compose the EJB archive. The target definition is responsible for including whatever server-specific configuration files the application server requires, and for performing any other server-specific assembly tasks.
`as-create-war`
This target assembles a web archive from a specified set of files, and stores the war file using a specified name in a specified location. The caller is responsible for specifying the classes, libraries, web files, and web deployment descriptor to be used to compose the web archive. The target definition is responsible for including whatever server-specific configuration files the application server requires, and for performing any other server-specific assembly tasks.
`as-deploy`
This target deploys a given module to the application server, using the application server's deployment methods and/or tools. The caller is responsible for specifying the module to be deployed.
`as-server-start`
This target starts the application server if it is not already running.
`as-server-stop`
This target stops the application server if it is running.
`as-verify`
This target attempts to verify a given module, to ensure that it is able to be deployed to the application server. The target definition is responsible for invoking whatever verification tool is provided by the application server in use.

Web Service Engine Configurations

If your project includes web services, you must also configure the web service engine you plan to use. This process mirrors the process for setting up the application server - you need to either override the `wse.type` property, which will load a configuration from `wse-configs/wse-<wse.type>-config.xml`, or you can set the `wse.config.file` property to directly choose the configuration file from any arbitrary location. For example, if you wanted to use the Apache Axis configuration included with the template, then you could just set the `wse.type` property in your `local-build.properties` like so:

`wse.type = axis`

This will cause the file `wse-configs/wse-axis-config.xml` to be imported into the build script. If you

Web Service Engine Properties

All web service engine configurations use the following standard properties, which usually have reasonable defaults set for them, but may need to be overridden in your `local-build.properties` file, depending on how your engine is set up. You can safely use these properties in your build script as needed.

`wse.client.compile.libraries`
A path variable specifying the libraries needed to compile web service clients that use the web service engine. This path can be used in the build script as part of compilation targets.
`wse.client.run.libraries`
A path variable specifying the libraries needed to run web service clients that use the web service engine. This path can be used in the build script as part of client execution targets.
`wse.service.compile.libraries`
A path variable specifying the libraries needed to compile service implementations for the web service engine. This path can be used in the build script as part of compilation targets.
`wse.service.run.libraries`
A path variable specifying the libraries needed at runtime in order to run a service using the web service engine. This path can be used in the build script when assembling component modules and applications to be deployed.

Each web service engine configuration file may also have its own set of properties that you need to override in your `local-build.properties` file. The Apache Axis config file, for example, uses a property named `axis.home` to indicate the root directory of the Axis installation. You would need to set this property in your `local-build.properties` to point to your Axis installation directory:

`axis.home = ${lib.dir}/axis-1.3`

Review the web service engine configuration file to see what engine-specific properties it requires you to set.

Web Service Engine Targets

Every web service engine configuration file must provide definitions for the following targets. The build script uses these targets to accomplish key tasks, such as preparing component archives prior to deplyoment. These targets are implemented to suit the web service engine, and insulate the build script from engine-specific details. Note that these targets are NOT meant to be called directly, they are only used by the build script within its targets.

Each target has a set of required and optional properties that it expects the caller to provide. Consult the web service engine configuration file for details on these properties. You can see the properties in use in the template `build.xml` file where it invokes these web service engine targets.

`wse-generate-client-stubs`
This target generates client stub code for a specified web service using the web service engine tools. The web service is specified using either a WSDL file URL, and/or service configuration files. The caller is expected to specify these parameters, as well as the destination for the generated source code and classes.
`wse-post-deploy`
This target is invoked for each web service deployed by a given project, to give the web service engine the opportunity to do any necessary post-deployment processing. The caller specifies a configuration directory and a web service name, and the target expects to find specific configuration files in that configuration directory, and uses them to perform whatever post-deployment tasks are necessary. Note that some engines will not need to perform anything in this target, but it is required in all web service engine configurations to ensure portability of the build script.
`wse-prepare-service`
This target is responsible for preparing any pre-requisites for a given web service prior to it being included in a component archive for deployment. This may include generating support classes and/or configuration files for the service as required by the web service engine. The caller is expected to specify the web service using a name and a configuration directory where the details of the web service can be located. Consult the web service engine configuration file for details on the configuration files it expects.
`wse-process-ear`
This target processes an application archive prior to deployment, to ensure that it contains all necessary files needed to run web services based on the web service engine. The caller specifies an application archive file to be processed, and the target is expected to enhance the archive in place with whatever libraries and/or configuration files are needed by the engine.
`wse-process-ejb-jar`
This target processes an EJB archive prior to deployment, to ensure that it contains all necessary files needed to run web services based on the web service engine. The caller specifies an EJB archive file to be processed, and the target is expected to enhance the archive in place with whatever libraries and/or configuration files are needed by the engine.
`wse-process-war`
This target processes a web archive prior to deployment, to ensure that it contains all necessary files needed to run web services based on the web service engine. The caller specifies a web archive file to be processed, and the target is expected to enhance the archive in place with whatever libraries and/or configuration files are needed by the engine.