J2EE Automation Toolkit
Introduction

The J2EE Automation Toolkit contains the necessary files required to build and deploy a J2EE project. It is based on the popular Ant build system and can be easily extended. It is distributed as a zip archive which is composed of a windows-executable (antwrapper.bat), ant-scripts, documentation and a README.txt file.

It was created to provide an efficient way to release J2EE applications. It can be used by web developers, EJB developers or deployment engineers and focuses on the automation of repetitive tasks that are either slow, error-prone or bringing no added value.

The J2EE Automation Toolkit was designed to :

  • build web-applications (in the .war or directory format)
  • build enterprise-applications (.ear)
  • deploy web- or enterprise applications
  • support multiple environment builds (development, integration, production, ...)
  • support multiple host deployments (multiple app-servers on the same machine, ftp to integration host, ...)

Future features will include tasks that are more project-lifecycle focused such as documentation generation, unit testing and reporting following Extreme Programming's ContinuousIntegration principle.

Installing the Automation Toolkit

The Automation Toolkit can be utilized by following these steps. All of these steps are required.

  • Download and install a Java2 (version 1.2 or later) Java Development Kit implementation for your operating system platform. Define an environment variable JAVA_HOME that points to the base directory of your JDK installation, and add the directory "$JAVA_HOME/bin" to your PATH variable.
  • Download and install Ant (version 1.4 or later). Ant is available at jakarta.apache.org/ant. Define an environment variable ANT_HOME that points to the base directory of your ant installation.
  • Unzip individa-j2ee-Automation Toolkit.zip into a directory. We will refer to this directory as $Automation Toolkit_HOME in this document but you do not need to setup such an environment variable.
Setup

A J2EE project is composed of a number of files :

  • Source files (java code, web code (html, gif, jpg, jsp), documentation)
  • Libraries required for your application to compile (jar files such as j2ee.jar)
  • Configuration files (WEB-INF for the web-app, META-INF for the ejb-app and another META-INF for the .ear)

During the build process, these files will be compiled, copied into a number of directories following the J2EE specification in order to create a web-application, a web archive or an enterprise archive.

The Automation Toolkit can be used for many J2EE projects and can therefore be located outside of a particular project. For example, the Automation Toolkit could be located at /projects/Automation Toolkit while you have two J2EE projects you want to build located at /projects/project1 and /projects/project2 respectively. You will provide the executable with the path of the project you want to build or deploy. We will refer to this location as $PROJECT_HOME (which could have the value of /projects/project1 for example).

The Automation Toolkit provides default values for the locations for your source files, libraries and configuration files, as well as the project name, the deployment directory and the temporary build dir. They are all relative to your project home directory ($PROJECT_HOME).

If you want to build the default empty directory structure for your project, run the following command from the $Automation Toolkit_HOME directory : antwrapper $PROJECT_HOME build.xml init-setup

For example, the command 'antwrapper d:\project1 build.xml init' will create the following directories :

  • d:\project1\src
  • d:\project1\src\java
  • d:\project1\src\web
  • d:\project1\src\doc
  • d:\project1\lib
  • d:\project1\conf
  • d:\project1\conf\base
  • d:\project1\conf\base\WEB-INF
  • d:\project1\conf\base\EJB-INF
  • d:\project1\conf\base\META-INF

Here are the details of the different properties used by the Automation Toolkit, their default values and how they can be redefined to meet your project custom file structure.

Project part
project.name the name of your J2EE project (defaults to j2ee-project)

You can override this default value by providing a valid property files named project.properties in the $PROJECT_HOME directory containing an entry in the form of : project.name=individa

Build part
java.dir .java files (defaults to $PROJECT_HOME/src/java)
web.dir .html,gif, jpg, jsp files (defaults to $PROJECT_HOME/src/web)
doc.dir the project documentation (defaults to $PROJECT_HOME/src/doc)
lib.dir the external .jar files required to compile (defaults to $PROJECT_HOME/lib)
conf.base.webinf.dir config files for the web-app (defaults to $PROJECT_HOME/conf/base/WEB-INF)
conf.base.ejb.dir config files for the ejb-app (defaults to $PROJECT_HOME/conf/base/EJB-INF)
conf.base.metainf.dir config files for the ear (defaults to $PROJECT_HOME/conf/base/META-INF)
build.dir temporary build directory (defaults to $PROJECT_HOME/build)

You can override those default values by providing a valid property files named build.properties in the $PROJECT_HOME directory.

You can provide environment specific configuration files, for example if the web.xml file used during development is different from the one that will be used in production. To do so, you need to :

  • Provide a value for the conf.base.dir property (which defaults to $PROJECT_HOME/conf/base) in build.properties
  • create a directory under $conf.base.dir with the name of the needed environment under $conf.base.dir/$yourenv
  • create the WEB-INF, EJB-INF and META-INF directories if needed
  • place the environment-specific config files into any of those directories

Upon specifying to the executable the name of the environment you want to build for, the build process will use the environment-specific configuration files in addition to (also means overriding) the config files present in the conf/base/ subdirectories.

Note that you can also provide an environment specific property file in the form of build_envName.properties where 'envName' is the name of the environment you want to build for. In this case, the regular build.properties file will be overridden by the properties/values defined in build_envName.properties.

Deployment part
deployment.antfile the path to another ant script that will be used for deployment. Note that this path will be relative to the Automation Toolkit installation dir ($Automation Toolkit_HOME) and not $PROJECT_HOME. (defaults to deploy_base.xml)

You can override those default values by providing a valid property file named deploy.properties or an environment-specific deploy_envName.properties file.

The Automation Toolkit comes with a deploy_fs.xml script which provides simple file system functionality, ideally suited for development purposes. Other deployment scripts can be created following the hardware configuration, network setups or environment needs.

Building a J2EE Application
Building a Web-Application

The build of a web-application creates a directory named after the project which contains the web files, the java classes and libraries, and the WEB-INF folder following the servlet 2.2 specification. The web-app will be put in the temporary build directory ($build.dir). Command : antwrapper $PROJECT_HOME build.xml webapp

Building a Web-Archive

The build of a web-archive creates Servlet 2.2 compliant .war file named after the project. The web-archive will be put in the temporary build directory ($build.dir). Command : antwrapper $PROJECT_HOME build.xml war

Building an Enterprise-Archive

The build of an enterprise-archive creates a J2EE compliant .ear file named after the project. The archive contains the project web-app as a .war file and the project ejb-app in a jar file. The enterprise archive will be put in the temporary build directory ($build.dir). Command : antwrapper $PROJECT_HOME build.xml ear

Building for a specific environment

Add the environment name to the command. Command : antwrapper $PROJECT_HOME build.xml webapp tomcat3dev

Cleaning a build

Cleans the temporary build directory. Command : antwrapper $PROJECT_HOME build.xml clean

Deploying a J2EE application
Deploying a Web-Application

Deploys the project if the web container supports directory-based web-applications.
This requires that the web container deployment directory is specified in the depoy.properties file located in the $PROJECT_HOME using the deployment.dir key.
For example by adding deployment.dir=c:\\path\\to\\webcontainer\\webapps
Otherwise, the project will be deployed in the default $PROJECT_HOME/deployment directory.

Command : antwrapper $PROJECT_HOME deploy.xml webapp

Deploying a Web-Archive

Command : antwrapper $PROJECT_HOME deploy.xml war

Deploying an Enterprise-Archive

Command : antwrapper $PROJECT_HOME deploy.xml ear

Deploying for a specific environment

To deploy for a specific environment, simply add the environment name to the command line and provide a deploy_envName.properties that matches the desired environment and that overrides the deployment.dir and deployment.buildfile values if necessary. Command : antwrapper $PROJECT_HOME deploy.xml war tomcat4dev And provide a deploy_tomcat4dev.properties file with the following content : deployment.dir=D:\\software\\java\\jakarta-tomcat-4.0-b7\\webapps

Cleaning a deployment

Command : antwrapper $PROJECT_HOME deploy.xml clean

Or for a specific environment : antwrapper $PROJECT_HOME deploy.xml clean tomcat4dev

TODO
  • Provide a Unix shell antwrapper script.
  • Generate the project documentation using DocBook/XSL.
  • Add unit testing to Java classes via JUnit.
  • Add unit testing to the web and ejb classes via Cactus.
copyright 2002 ultrawork.org