Java Enterprise in a Nutshell 3rd Edition
Ant Template

Table of Contents

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.