Simple Example

Simple Example

A JAM build file imports its settings and services from reusable Ant modules. A typical build file will import:

• two or more property files
• the classpath module
• one core module
• zero or more optional support modules

Here is a simple build file for compiling and packaging a jar library:

<?xml version="1.0"?>
  <project name="mylib" basedir="." default="default">      - standard Ant project tag
    <property name="jam.home" location="/dev-tools/jam"/>   - set jam.home location
    <import file="${basedir}/src/jam/props-maven.xml"/>     - generated project properties
    <import file="${jam.home}/props-global.xml"/>           - JAM's default properties
    <import file="${basedir}/src/jam/classpath.xml"/>       - generated classpath tasks
    <import file="${jam.home}/lib.xml"/>                    - core jar module
  </project>	

Two of the imported modules, props-maven.xml and classpath.xml, are generated from your POM (project.xml) file using the JAM plugin. The props-global.xml module defines JAM's naming conventions, directory layout and default property settings. The last import, lib.xml, is JAM's core module for compiling and packaging jar files. Core modules define standard commands or targets in Ant-speak, which you can list by typing:

ant -p 

The lib.xml module defines the following standard targets:

As an example of what this file can do, issuing the command

ant clean dist 

will delete any previous build artifacts, compile java source files, copy resource files and package the resulting artifacts into a jar file.

To demonstrate how easy it is to include additional functionality, the next example adds transparent unit testing with the addition of two statements. The first statement imports the optional utest.xml module and the second overrides the dist target (triggering unit testing after compilation, but before jar packaging). Here is the resulting build file:

<?xml version="1.0"?>
  <project name="mylib" basedir=".">
    <property name="jam.home" location="/dev-tools/jam"/>
    <import file="${basedir}/src/jam/props-maven.xml"/>
    <import file="${jam.home}/props-global.xml"/>
    <import file="${basedir}/src/jam/classpath.xml"/>
    <import file="${jam.home}/lib.xml"/>
    <import file="${jam.home}/utest.xml"/>                  - import unit test module
    <target name="dist" depends="compile, test, jar"/>      - add 'test' dependency to 'dist' target
  </project>	

Now if you type, ant clean dist any unit tests found in the src/test sub-directory will have to complete successfully before the distribution file is created.

Getting Started...

One way to get started is to copy a working example from the download page and modify it for your needs. The all-javagen-examples-src-jam-2.1.zip file contains everything from simple EJB and Webapp examples to a full version of the Java Petstore. Studying the examples is one of the fastest ways to learn JAM. See EJB JAMing for a step-by-step tutorial that uses one of the example projects.

Another way to get started is to copy one of the JAM templates and modify it for your own use. For each build.xml file you should define a corresponding POM (project.xml) file. Next you need to generate your props-maven.xml and classpath.xml files from the POM using the Maven command:

maven jam 

If this doesn't complete successfully, chances are you don't have your dependencies specified correctly in your POM or you're missing a required library in the local repository. The next step is to execute ant setup and verify that your settings make sense. Next, list the public targets (ant -p) and test each one starting with those with the least dependencies. A good testing sequence is: setup, clean, gen, compile, dist, repo.

For other examples see the tutorials page.