Last Update: 3-May-2002

Jera Ant Tasks

The Jera Ant Tasks are additional tasks for the Jakart Ant build tool.They were originally written by Jera Design for internal use, and are now made available to the public under the terms of the Common Public License.

Summary
Query Task
MainClass Task
IncVersion Task
JnlpVersion Task
Using Jera Ant Tasks
Building Jera Ant Tasks
Feedback

Summary

License:	Common Public License Version 0.5
Binary:	JeraAntTasks.jar
Source (Windows)	JeraAntTasks_src.zip
Source (UNIX)	JeraAntTasks_src.tar.gz

Query Task

Description

The Query Ant task was written so that sensitive information like logins and passwords doesn't need to be included in a build.xml file. Instead, you put a line like:

<query name="login"/>

into your build.xml file. The Query Ant task responds by putting up the following dialog:

Query Dialog

You enter you login into the dialog and press "Enter", or click "Ok", and the property "login" becomes bound to whatever you typed. That means that after executing the above Query Ant task, you can type use the expression ${login} to get whatever was placed in the login.

Parameters

Attribute	Description	Required
name	Name of property to store result in.	Yes
message	The message to display in the dialog. If omitted, defaults to the value of the "name" attribute.	No
password	If "yes" or "true", treat the input field as a password field with "*"s displayed instead of the actual characters typed. Defaults to "false".	No

Examples

One typical use of Query is in uploading files to an FTP server:

<target name="deploy" depends="compile">
    <query name="login"/>
    <query name="password" password="true"/>
    <ftp server="ftp.yoursite.com"
            userid="${login}"
            password="${password}"
            remotedir="public_html/package" >
        <fileset dir=".">
            <include name="MirrorSpot.html"/>
            <include name="MirrorSpot.class"/>
            <include name="MirrorSpot.java"/>
            <include name="pops.jpg"/>
        </fileset>
    </ftp>
</target>

Note the use of the "password" attribute to tell Query to use a non-echoing password field.

MainClass Task

Description

MainClass makes a JAR file executable by adding a "Main-Class:" header to the JAR file's manifest. In Java 1.2 and later you can launch a JAR file that contains a "Main-Class:" header by using the command line:

java -jar JarFile.jar

Some platforms (such as Windows), Java installs itself as the handler for files with the JAR suffix, so you can launch a JAR file that contains a "Main-Class:" header by just double-clicking on it.

MainClass works by copying the JAR file entry-by-entry, until it gets to the "META-INF/MANIFEST.MF" entry. For that file, it copies all the main attributes, adds a "Main-Class:" header at the end of the main attributes section, and then copies all the per-entry attributes. The unmodified JAR file is saved with ".bak" suffix.

Parameters

Attribute	Description	Required
jarfile	Path to JAR file.	Yes
mainclass	The fully-qualified class name of the class that contains the `public static void main(String[] args)` method that you wish to run on when the JAR file is launched.	Yes

Examples

Typically, you simply add a <mainclass> task to your existing "JAR" target, like so:

<target name="jar" depends="compile">
    <jar jarfile="JeraWorks.jar">
        <fileset dir="classes" />
        <fileset dir="rsrc"/>
    </jar>
    <mainclass jarfile="JeraWorks.jar" mainclass="com.jera.works.Main" />
</target>

I haven't fully worked out how MainClass interacts with JAR signing, so when I sign a JAR file, I do it in a target that runs after the <mainclass> task.

IncVersion Task

Description

IncVersion increments a version number stored in a text file. You can add an <incversion> task to your "compile" target, so that the version number gets incremented every time you compile your code.

IncVersion is especially useful for deploying applications with JNLP (Java Web Start), where each deployed version should have its own different version number. You can use IncVersion to increment a version number, and the JnlpVersion task (described below) to copy the version number into the appropriate place in the ".jnlp" file.

IncVersion expects the version file to contain a single line (with trailing line ending character(s)). IncVersion expects the line to match the regular expression:

[0-9]+([\.\-_][0-9]+)*

That is, one or more sequences of digits separated by either a period, hyphen or underscore. IncVersion treats the last sequence of digits as a number, increments it, and rewrites the file.

Examples
Before	After
1	2
1.0.1	1.0.2
1.0-1	1.0-2
1.0-1_1	1.0-1_2

Parameters

Attribute	Description	Required
file	Path to version file.	Yes

As a side effect of running, IncVersion sets two properties: ${version} is set to the incremented version, and ${cvsversion} is set to the incremented version with all periods changed to underscores, making the version number suitable for a CVS tag operation.

Examples

IncVersion is typically used in your "compile" target, like so:

<target name="compile">
    <incversion file="etc/JeraWorks.jar.version" />
    <jnlpversion
        jnlpfile="etc/jeraworks.jnlp"
        jarentry="JeraWorks.jar"
        newversion="${version}"
    />
    <echo>version = ${version}</echo>
    <echo>cvsversion = ${cvsversion}</echo>
    <mkdir dir="classes" />
    <javac
        destdir="classes"
    >
        <src>
            <pathelement location="src" />
            <pathelement location="../JeraApp/src" />
        </src>
        <classpath>
            <pathelement location="lib/junit.jar" />
        </classpath>
    </javac>
</target>

Note how IncVersion works hand-in-hand with JnlpVersion.

JnlpVersion Task

Description

This task is somewhat esoteric. It's only useful if you're deploying a Java application via JNLP (Java Web Start). If you aren't, feel free to scroll straight to Using Jera Ant Tasks.

JnlpVersion modifies the version attribute of a specified <jar> tag in a ".jnlp" file. You can use this, along with a web server that generates the "x-java-jnlp-version-id" header to greatly improve the efficiency of Java Web Start's caching. See the Java Web Start homepage and the JNLP Spec for more information.

Dependencies

MainClass requires a JAXP-compliant XML parser and XSLT processor to be present on the classpath.

Parameters

Attribute	Description	Required
jnlpfile	Path to version file.	Yes
jarentry	Replace (or create) the "version" attribute of the <jar> tag where the "href" attribute matches this.	Yes
newversion	The new value for the "version" attribute of the <jar> tag.	Yes

Examples

JnlpVersion is typically used alongside IncVersion in your "compile" target, like so:

<target name="compile">
    <incversion file="etc/JeraWorks.jar.version" />
    <jnlpversion
        jnlpfile="etc/jeraworks.jnlp"
        jarentry="JeraWorks.jar"
        newversion="${version}"
    />
    <echo>version = ${version}</echo>
    <echo>cvsversion = ${cvsversion}</echo>
    <mkdir dir="classes" />
    <javac
        destdir="classes"
    >
        <src>
            <pathelement location="src" />
            <pathelement location="../JeraApp/src" />
        </src>
        <classpath>
            <pathelement location="lib/junit.jar" />
        </classpath>
    </javac>
</target>

When used on the following "JeraWorks.jar.version" file:

0.1-1

And the following "jeraworks.jnlp" file:

<?xml version="1.0" encoding="UTF-8"?>
<jnlp spec="1.0+" codebase="http://www.jera.com/jeraworks/download" href="jeraworks.jnlp">
    <information>
        <title>JeraWorks</title>
        <vendor>Jera Design</vendor>
        <homepage href="http://www.jera.com/jeraworks/"/>
        <description>A Cross-Platform Outliner written in Java. Launches with Java Web Start.</description>
        <description kind="short">The Cross-Platform Outliner</description>
        <icon href="JWIcon.gif" version="0.1"/>
        <offline-allowed/>
    </information>
    <security>
        <all-permissions/>
    </security>
    <resources>
        <j2se version="1.3+"/>
        <jar href="JeraWorks.jar" version="0.1-1"/>
    </resources>
    <application-desc main-class="com.jera.works.Main"/>
</jnlp>

First the IncVersion task loads the version file, increments it to 0.1-2 and saves it. Then the JnlpVersion task replaces the existing <jar> "version" attribute shown in bold above with the new version, in this case 0.1-2.

Using Jera Ant Tasks

Download the following file and place it in the $ANT_HOME/lib directory:
- JeraAntTasks.jar
Add the following lines to your build.xml so Ant can find the tasks:
<taskdef name="query" classname="com.jera.anttasks.Query"/> <taskdef name="mainclass" classname="com.jera.anttasks.MainClass"/> <taskdef name="incversion" classname="com.jera.anttasks.IncVersion" /> <taskdef name="jnlpversion" classname="com.jera.anttasks.JnlpVersion" />
That's it!

Building Jera Ant Tasks

Download a source bundle:
- JeraAntTasks_src.zip (Windows line endings)
- JeraAntTasks_src.tar.gz (UNIX line endings)
Uncompress
Run "ant install" in the project directory.
Add the following lines to your build.xml so Ant can find the tasks:
<taskdef name="query" classname="com.jera.anttasks.Query"/> <taskdef name="mainclass" classname="com.jera.anttasks.MainClass"/> <taskdef name="incversion" classname="com.jera.anttasks.IncVersion" /> <taskdef name="jnlpversion" classname="com.jera.anttasks.JnlpVersion" />
That's it!

Feedback

I'd love to hear how you're using the Jera Ant Tasks, or if you're having any problems. Send email to John Brewer <jbrewer@jera.com>. Thanks!