Ant Task

This task runs the iValidator testing framework. The latest version of the framework can be found at http://www.ivalidator.org. This task has been tested with iValidator 2.1; it won't work with versions prior to iValidator 2.0.

Note: This task has not been included in the Ant distribution yet. The ivalidator-ant.jar contains it. This task depends on external libraries also not included in the Ant distribution. You have to install the iValidator distribution too.

Note: After installing the iValidator distribution you have a couple of choices to integrate the <ivalidator> task into Ant:

  1. You include the locations of the ivalidator-ant.jar and the ivalidator.jar in your CLASSPATH environment variable placing them before any Ant jar-files.
  2. If you don't want to pollute your CLASSPATH, create an .ant/lib subdirectory in your home directory. Put both jars (ivalidator-ant.jar and ivalidator.jar) into this directory and set the home-attribute of the ivalidator target to point to your iValidator distribution directory.
  3. Since the <ivalidator> task is not part of the Ant distribution, you can create your own taskdef within the Ant build file: 
    <taskdef  name="ivalidator"
         classname="org.ivalidator.shell.ant.IValidatorTask"
         classpath="${IVALIDATOR_HOME}/ivalidator-ant.jar:${IVALIDATOR_HOME}/ivalidator.jar"/>
    where ${IVALIDATOR_HOME} points to your iValidator distribution directory. You don't have to set the home-attribute in this case. This is the preferred way at the moment.

Parameters

Attribute Description Required
home Defines the base directory of the ivalidator distribution. No; default is the parent directory of the ivalidator.jar found in the classpath.
configuration The name of the iValidator framework configuration file. If this configuration file is set and no configuration has been specified, this configuration file is used for executing iValidator. If a configuration, which is not empty and valid, is defined, it will be copied to this framework configuration file if the newly created one is different from the existing one. No; default is a temporary file.
haltonerror Stop the build process if an error occurs during the iValidator run. The build process will be stopped, if iValidator detected an error or if the iValidator test took too long. No; default is off.
errorproperty The name of a property to set in the event of a failure, an error or a timeout. No
haltonfailure Stop the build process if a failure occurs during the iValidator run. The build process will be stopped, if iValidator detected an error, a failure or if the iValidator test took too long. haltonfailure differs from haltonerror only if a failure has been detected. No; default is off.
failureproperty The name of a property to set in the event of a failure or a timeout. No
timeout Cancel the iValidator run if it doesn't finish in the given time (measured in milliseconds). No
jvm The command used to invoke the Java Virtual Machine, default is 'java'. The command is resolved by java.lang.Runtime.exec(). No; default is java.
maxmemory Maximum amount of memory to be allocated by the executed VM. No
classpathref The reference to a classpath, which will be used by the executed VM. You can also use a classpath element. Please see the note there. No; default is the ivalidator.jar found in the home directory - if the attribute is present - or found within the classpath of this task.
dir The directory in which to invoke the VM. No
newenvironment Do not propagate the old environment when new environment variables are specified. No; default is false.

By using the errorproperty and failureproperty attributes, it is possible to perform other tasks - like sending mails - and still fail the build in the event of a failure.

Nested Elements

Configuration

The iValidator framework uses an XML configuration file to define the environment within iValidator is executing and which defines front- and backends to get test descriptions and write reports. The <ivalidator> task allows the definition of this configuration file within the context of an ant build file. Corresponding to the elements of a configuration file - global properties and descriptor and report repositories with local properties - there are nested elements within the <ivalidator> task. These elements are testproperty, descriptor, report and attribute.

A configuration is empty if there is no descriptor present. In this case the configuration-file defined as an attribute will be used. If there is none, the <ivalidator> task is invalid.
If the configuration is not empty, first a temporary configuration file will be created. If the configuration-attribute is defined, the temporary file will be copied to the named file, if they are not equal. Whether copied or not, the iValidator execution will use the defined configuration-file or - if there is none - it will use the temporary file.

testproperty

Use nested <testproperty> elements to specify properties required by the test you want to run. These properties will be placed as global Propertys in the configuration file. The attributes for this element are the same as for environment variables. 

<ivalidator>
    <testproperty key="ivalidator.validate" value="false"/>
    ...
</ivalidator>
descriptor

A <descriptor> element defines one iValidator test run. The definition of the testrun is handled by the classes of the repository. The reference to the repository is a requiered attribute. The nested element attribute define further properties needed by the repository.

Attribute Description Required
repository Defines the descriptor repository to use. It references either a repository.xml-file or a subdirectory within the repository substructure of the iValidator distribution. For more information look at the iValidator manual. Yes
classpathref The reference to a classpath, which will be used by this repository to create test units and adapters. This explizit attribute will be saved as a local descriptor repository Property with name "classpath". No
descriptor attribute

Use nested <attribute> elements to specify properties required by the descriptor repository - for example - to define in input file with a test-description. These properties will be placed as local Propertys in the configuration file under this <descriptor> element. The attributes for this element are the same as for environment variables. 

<ivalidator>
    <descriptor repository="xml" classpathref="/xml.classpath">
        <attribute key="input" file="${XMLINPUT}"/> 
    </descriptor>
    ...
</ivalidator>
report

A <report> element defines one iValidator backend. This backend is responsible to capture the reports generated by a iValidator test run. The reference to the repository is a requiered attribute. The nested element attribute define further properties needed by the repository.

Attribute Description Required
repository Defines the report repository to use. It references either a repository.xml-file or a subdirectory within the repository substructure of the iValidator distribution. For more information look at the iValidator manual. Yes
report attribute

Use nested <attribute> elements to specify properties required by the report repository - for example - to define in input file with a test-description. These properties will be placed as local Propertys in the configuration file under this <descriptor> element. The attributes for this element are the same as for environment variables. 

<ivalidator>
    <report repository="xml">
        <attribute key="output" file="${XMLOUTPUT}"/> 
    </report>
    ...
</ivalidator>

jvmarg

Additional parameters may be passed to the executing VM via nested <jvmarg> elements. For example: 

<ivalidator>
  <jvmarg value="-Djava.compiler=NONE"/>
  ...
</ivalidator>

would run the iValidator test in a VM without JIT.

<jvmarg> allows all attributes described in Command-line Arguments.

assertions

You can control enablement of Java 1.4 assertions with an <assertions> subelement.

sysproperty

Use nested <sysproperty> elements to specify system properties required by the iValidator execution. These properties will be made available to the executing VM. The attributes for this element are the same as for environment variables. 

<ivalidator>
    <sysproperty key="user.name" value="Wilfried Schwartz"/>
    ...
</ivalidator>

would run the iValidator test under another user.name property.

syspropertyset

You can specify a set of properties to be used as system properties with syspropertysets.

bootclasspath

The location of bootstrap class files can be specified using this PATH like structure.

classpath

In addition to the <classpathref> attribute the <ivalidator> task supports a nested <classpath> element that represents a PATH like structure.
Note: Usually the classpath should only contain the ivalidator.jar, if it is not found in the home directory. So it should be used with great care.

env

It is possible to specify environment variables to pass to the executing VM via nested <env> elements. For a description of the <env> element's attributes, see the description in the exec task.

Example

<project name="IValidatorAdapterTest">
    <property name="IVALIDATOR_HOME" value="/var/ivalidator"/>

    <taskdef name="ivalidator"
         classname="org.ivalidator.shell.ant.IValidatorTask"
         classpath="${IVALIDATOR_HOME}/ivalidator-ant.jar:${IVALIDATOR_HOME}/ivalidator.jar"/>
    
    <property name="TRIALDIR" location="${IVALIDATOR_HOME}/org.ivalidator.sample.adapter"/>
    <path id="trial.classpath">
        <pathelement location="${TRIALDIR}/classes"/>
    </path>
    
    <ivalidator>
        <descriptor repository="xml" classpathref="/trial.classpath">
            <attribute key="input" file="${TRIALDIR}/test.xml"/> 
        </descriptor>
        
        <report repository="xml">
            <attribute key="outputdir" file="${TRIALDIR}/result"/>
            <attribute key="bom" value="true"/>
        </report>
    </ivalidator>
</project>

Runs iValidator on the test defined in the XML file /var/ivalidator/org.ivalidator.sample.adapter/test.xml. The output will be generated in a subdirectory called result.