Extra Ant Tasks

The Assert Task

Antelope includes a special Ant task for adding an assertion capability to Ant projects. This task works in a manner very similar to the Java 'assert' keyword, and provides a limited "design by contract" facility to Ant. This is very useful for testing build scripts prior to putting them into production.

The Assert task verifies that a given property has a given value and throws a BuildException if the property value is not as expected or the property does not exist.

Also like Java's 'assert' keyword, the Assert task must be 'turned on' using the property "ant.enable.asserts". If not set, or is set to false, the Assert task works exactly like the Sequential task.

This task can hold other tasks including Assert.

To use this task in your build files, include a task definition like this:

    <taskdef name="assert" classname="ise.antelope.common.Assert"/>
    <property name="ant.enable.asserts" value="true"/>

Attributes:
AttributeDescriptionDefaultRequired
name The name of the property to test for. none Yes
exists Test for existence or non-existence of the property. True No
value The value to test for, implies 'exists=true'. If the value in the project is different than this value, a BuildException will be thrown and the build will stop. none No
execute Should the tasks contained in this task be executed? It may be useful to set this to false when testing build files. True No
failonerror Should the build halt if the assertion fails? Setting this to false is contrary to the intented use of assertions, but may be useful in certain situations. True No

The assert task does not support any nested elements apart from Ant tasks. Any valid Ant task may be embedded within the assert task.

In the following example, the first 'assert' task checks that the "wait" property exists and does not execute the 'echo' and 'sleep' tasks. The second 'assert' task checks that the "wait" property exists, has a value of 2, and executes the 'echo' task.

     <property name="wait" value="2"/>
     <assert name="wait" execute="false">
        <echo>
            Waiting ${wait} seconds...
            Click the red button to stop waiting.
        </echo>
        <sleep seconds="${wait}"/>
     </assert>
     <assert name="wait" value="2" execute="true">
        <echo>done waiting!</echo>
     </assert>

If the "ant.enable.asserts" property is set to false, then in the above example, the 'echo', 'sleep', and 'echo' tasks will all execute.

Top


The If Task

Antelope includes a special Ant task for adding an "if" capability to Ant projects. This task works in a manner very similar to the Java 'if' keyword. This is useful for performing certain tasks only if a property has a specific value.

This task can hold other tasks including the If task.

To use this task in your build files, include a task definition like this:

    <taskdef name="if" classname="ise.antelope.common.IfTask"/>

Attributes:
AttributeDescriptionDefaultRequired
name The name of the property to test for. none Yes
exists Test for existence or non-existence of the property. True No
value The value to test for, implies 'exists=true'. If the value for the property in the project is the same as this value, embedded tasks will be executed. none No

The If task does not support any nested elements apart from Ant tasks. Any valid Ant task may be embedded within the If task.

In the following example, the 'antcall' task will execute only if the project has a property named "test" with a value of "true".

   <if name="test" value="true">
      <antcall target="doUnitTests"/>
   </if>

In the next example, the 'antcall' task will execute only if the project has a property named "test". In this example, it does not matter what value is assigned to the "test" property.

   <if name="test">
      <antcall target="doUnitTests"/>
   </if>

Of course, the same thing could have been done by:

   <antcall target="doUnitTests"/>
   <target name="doUnitTests" if="test">
   </target>
In the next example, the 'antcall' task will execute only if the project does not have a property named test. This is the opposite situation of the previous example.

   <if name="test" exists="false">
      <antcall target="doUnitTests"/>
   </if>

The next example demonstrates nested 'if' tasks. This example will run the unit tests, and if it is Monday, will run the weekly unit tests.

   <tstamp>
      <format property="day" pattern="E" />
   </tstamp>
   <if name="test" value="true">
      <antcall target="doUnitTests"/>
      <if name="day" value="Mon">
         <antcall target="doWeeklyUnitTests"/>
      </if>
   </if>

The next example shows the "if" and "assert" tasks working together to validate a property before use, and also shows an example of where the "assert" 'failonerror' attribute might be useful. In this example, if the e-mail address is invalid, the e-mail won't be sent and the build won't fail.

   <if name="email_from" value="buildteam@mycompany.com">
      <property name="valid_email" value="true"/>
   </if>
   <if name="email_from" value="buildsite@mycompany.com">
      <property name="valid_email" value="true"/>
   </if>
   <assert name="valid_email" value="true" failonerror="false">
      <mail from="${email_from}" tolist="${email_to}" message="New release available"/>
   </assert>

Top

The Try Task

The "Try" task works similarly to the try/catch construct in Java. This task is useful when a particular task might fail, but the build should not fail if it does. An example is the "mail" task will fail if the mail server is not available, but the build should not fail if the mail message cannot be delivered.

To use this task in your build files, include a task definition like this:

    <taskdef name="try" classname="com.crossgain.antext.TryTask"/>

Attributes:
AttributeDescriptionDefaultRequired
catch The name of a target to execute if a task fails. This is optional. The target must be in the same project. None No

In the following example, the "fail" task will not cause the build to fail because it is contained by a "try". The "testfail" target will execute.

    <target name="test" description="This exercises the Try task.">
        <try catch="testfail">
            <echo>I am trying...</echo>
            <fail message=" and I failed..."/>
            <echo> but I did not die!</echo>
        </try>
    </target>
  
    <target name="testfail">
        <echo>Did testfail</echo>
    </target>

Top

The UserProperty Task

Another task provided by Antelope is the UserProperty task. This works exactly like the standard Ant Property task, except that THESE PROPERTIES ARE MUTABLE. While this goes against the standard Ant use of properties, occasionally it is useful to be able to change a property value with the build. In general, use of this task is DISCOURAGED, and the standard Ant Property should be used if possible.

To use this task in your build files, include a task definition like this:

    <taskdef name="userproperty" classname="ise.antelope.common.UserProperty"/>

For usage information, see the Ant 1.5 documentation for the Property task.

Top