This post covers the absolute basics for a beginner of setting up a minimal build script for building and deploying code as a jar/war/ear file. The aim is to show a simple build structure and script rather than building a proper application. The scripts are mostly self-explanatory. The end result can be used as a starting point for later posts covering more difficult topics including building sample applications, testing and automating your build with CruiseControl.
Prerequisite:
You need java and ant installed on your machine and running from a command prompt.
The first thing you need when setting up a new project is to decide on the structure. By using standard conventions about how you structure your code it makes it easier for others to work on it. You’ll see a similar type of build structure used in tools like Seam’s seamgen except more complicated than this one.
The root folder of your project will be referred to as PROJECT_HOME in these notes. The first thing to do is create the following folders in PROJECT_HOME:
config – holds configuration files
lib – holds any jar files
resources – resource and config files to be copied into a jar, war or ear file during the build
src – for source java files
web – for web applications pages, css, images etc
Now add an ant build script file PROJECT_HOME/build.xml which is used to build the project. Also add PROJECT_HOME/config/build.properties.sample. This file is added to source control. Each user that checks out the project will copy this file and rename it to build.properties which will be used by the build script. Any subsequent changes to the property file in source control will not overwrite a local user’s settings and this also forces a user to set the properties correctly when checking out a new project.
PROJECT_HOME/config/build.properties.sample:
project.name=example
web.pages.dir=web
javac.debug=true
javac.deprecation=false
jboss.home = C:/Applications/jboss-4.2.2.GA/
We start with a basic build script that reads the build.properties file, adds some other properties, a class path and the targets init, compile and clean. We’ll add to this as we go along.
The build process generates the folder structure for a jar file, war file and ear file in exploded-archives. It will then package those into actual archive files in the dist directory. This allows you to check what’s being added without having to examine the final archive files. You also configure a directory to deploy in this case an ear file to a web application server.
PROJECT_HOME/build.xml
<project name="example" default="compile" basedir=".">
<!-- set properties for this build -->
<property name="config.dir" value="config" />
<property file="${config.dir}/build.properties" />
<property name="src.dir" value="src" />
<property name="lib.dir" value="lib" />
<property name="resources.dir" value="resources" />
<property name="dist.dir" value="dist" />
<property name="archive.dir" value="exploded-archives" />
<property name="ear.dir" value="${archive.dir}/${project.name}.ear" />
<property name="jar.dir" value="${archive.dir}/${project.name}.jar" />
<property name="war.dir" value="${archive.dir}/${project.name}.war" />
<property name="deploy.dir" value="${jboss.home}/server/default/deploy" />
<!-- Class path settings -->
<fileset id="lib" dir="${lib.dir}">
<include name="*.jar" />
</fileset>
<path id="build.classpath">
<fileset refid="lib" />
</path>
<target name="init" description="Initialize the build">
<echo>Initialising build...</echo>
<mkdir dir="${jar.dir}" />
<mkdir dir="${ear.dir}" />
<mkdir dir="${war.dir}" />
<mkdir dir="${archive.dir}" />
<mkdir dir="${dist.dir}" />
</target>
<target name="compile" depends="init" description="Compile the Java source code">
<echo>Compiling java source code...</echo>
<javac classpathref="build.classpath" destdir="${jar.dir}" debug="${javac.debug}" deprecation="${javac.deprecation}" nowarn="on">
<src path="${src.dir}" />
</javac>
</target>
<target name="clean" description="Cleans up the build directorys">
<echo>Cleaning build directories...</echo>
<delete dir="${ear.dir}" />
<delete dir="${war.dir}" />
<delete dir="${jar.dir}" />
<delete dir="${archive.dir}" />
<delete dir="${dist.dir}" />
</target>
</project>
The build.classpath is set to simply include any jar files in the lib folder.
The init target creates any directories that are needed by the build.
The clean target deletes any directories that were created by the build.
The compile target looks in the src folder for any .java files and compiles them into the exploded-archives/example.jar folder.
To test the build script add the file
PROJECT_HOME/src/com/example/Parent.java
package com.example;
public class Parent {
private Long parentId;
public Long getParentId() {
return this.parentId;
}
public void setParentId(Long parentId) {
this.parentId = parentId;
}
}
Open a command prompt in the PROJECT_HOME folder and run the command ‘ant’. By default (default=”compile”) it will run the compile target. The compile target states that it depends on the init target, so the init target will be run first to create the folders that are needed. When the script finishes running you will find that exploded-archives/example.jar/com/example contains the compiled Parent.class.
We want to build and deploy a web application so we add the target gen-war-files which will be used to copy anything that’s needed into the exploded war file before it gets packaged. We’ll start with a target like this:
<?xml version="1.0"?>
<target name="gen-war-files" depends="compile" description="Generates the war files">
<echo>Copying war files...</echo>
<copy todir="${war.dir}">
<fileset dir="${basedir}/${web.pages.dir}/pages" />
</copy>
<copy todir="${war.dir}">
<fileset dir="${basedir}/${web.pages.dir}">
<include name="images/**/*" />
<include name="css/**/*" />
</fileset>
</copy>
<copy todir="${war.dir}/WEB-INF/lib">
<fileset dir="${lib.dir}">
<includesfile name="${config.dir}/war-jars.list" />
</fileset>
</copy>
<copy todir="${war.dir}/WEB-INF">
<fileset dir="${resources.dir}/WEB-INF">
<include name="*.*"/>
</fileset>
</copy>
</target>
A war file contains a WEB-INF folder where compiled classes and required jar files are put. Also files such as web.xml which gives configuration and deployment for the web components. So create resources/WEB-INF.
PROJECT_HOME/resources/WEB-INF/web.xml
<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.5"
xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">
</web-app>
The build script copies any files in resources/WEB-INF to the war folder and also copies any jar files that are needed to the WEB-INF/lib folder. You can configure which of the jar files in PROJECT_HOME/lib get copied over in PROJECT_HOME/config/war-jars.list. For now just create an empty file of that name in the config folder.
This target copies any files in web/pages to exploded-archives/example.war and will also copy over the images and css folders. We don’t have any files to copy at the moment, but will add an index page to see that it does get added.
web/pages/index.jsp
<?xml version="1.0" encoding="ISO-8859-1" ?>
<html>
<head>
<title>The Index Page</title>
</head>
<body>
Index page
</body>
</html>
Try the command ‘ant gen-war-files’ and you will see that exploded-archives/example.war now contains the index page.
We now add the gen-ear-files and archive targets. Similarly to the war file, the ear file requires a META-INF folder containing information about the ear file. So you can add resources/META-INF for holding these files and an empty config/ear-jars.list to configure which jar files are needed in the ear file. We will add an application.xml which is the deployment descriptor for ear files.
resources/META-INF/application.xml
<?xml version="1.0" encoding="UTF-8"?>
<application xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/application_5.xsd"
version="5">
<display-name>example</display-name>
<module>
<ejb>example.jar</ejb>
</module>
<module>
<web>
<web-uri>example.war</web-uri>
<context-root>/example</context-root>
</web>
</module>
</application>
The gen-ear-files target will take care of copying this to the correct location in the ear file then the archive target will take all the output in exploded-archives and package up all the files into the dist directory. Test this using ‘ant archive’
<target name="gen-ear-files" depends="gen-war-files" description="Generates the ear files">
<echo>Copying the ear files...</echo>
<mkdir dir="${ear.dir}/lib" />
<copy todir="${ear.dir}/lib">
<fileset dir="${lib.dir}">
<includesfile name="${config.dir}/ear-jars.list" />
</fileset>
</copy>
<copy todir="${ear.dir}/META-INF">
<fileset dir="${resources.dir}/META-INF">
<include name="*.*"/>
</fileset>
</copy>
</target>
<target name="archive" depends="gen-war-files,gen-ear-files" description="Packages all the archives">
<echo>Packaging all archives...</echo>
<jar jarfile="${dist.dir}/${project.name}.jar" basedir="${jar.dir}" />
<jar jarfile="${dist.dir}/${project.name}.war" basedir="${war.dir}" />
<jar jarfile="${dist.dir}/${project.name}.ear">
<fileset dir="${ear.dir}"/>
<fileset dir="${dist.dir}">
<include name="${project.name}.jar"/>
<include name="${project.name}.war"/>
</fileset>
</jar>
</target>
We now want to deploy the ear file that has been created to a web application server. In our example we’re using JBoss. You set the jboss.home directory in build.properties already. Now add some more build targets
<target name="clean-deploy" depends="clean, deploy" description="A full clean deploy"/>
<target name="deploy" depends="archive" description="Deploy to a JBoss web server">
<echo>Deploying to JBOSS web server...</echo>
<fail unless="jboss.home">jboss.home not set</fail>
<copy todir="${deploy.dir}" file="${dist.dir}/${project.name}.ear" />
</target>
<target name="undeploy" description="Undeploy from a JBoss web server">
<echo>Undeploying from JBOSS web server...</echo>
<delete file="${deploy.dir}/${project.name}.ear" />
</target>
Now run the clean-deploy target (set this to default) and try accessing http://localhost:8080/example/
You should see the index page display if everything is working correctly. You now have an extremely basic build script running. You should go through each line and check that you understand what it does – you can get more detailed information in the Ant User Manual.
Tags: ant · build
