E Using the SigTest Tools With Ant

This appendix describes how to use the SigTest tools in Ant build scripts.

E.1 Using the Setup Command From an Ant Script

The Signature Test tool Setup command can be invoked from an Ant script. The sigtestdev.jar file contains the corresponding Ant task.

Use the following task definition in your Ant build script:

<taskdef name="setup"  classname="com.sun.tdk.signaturetest.ant.ASetup"  classpath="sigtestdev.jar"/>

Table E-1 lists required and optional attributes and nested elements for the “setup” task.

Table E-1 Setup Attributes Available for Ant Scripts

Attribute	Description
Required
“package” attribute or nested “package” elements	Corresponds to the `-package` option
“classpath” attribute or nested “classpath” elements	Corresponds to the `-classpath` option
“filename” attribute	Corresponds to the `-filename` option

Optional:
“failonerror” attribute	Stops the build process if the command exits with an error. Default value is `false`
“apiVersion” attribute	Corresponds to `-apiVersion`. Set API version for signature file
“exclude” attribute or nested “exclude” elements	Corresponds to -exclude option. Specifies package(s) or class(es), which is not required to be tested
“negative” attribute	Treats a failed result as successful and a successful result as failed. Used for negative tests. Default value is “false”.

The following code shows how to use the Setup command in an Ant script:

<target name="td" description="Setup task definition">
  <taskdef name="setup" classname="com.sun.tdk.signaturetest.ant.ASetup"
    classpath="${sigtest.home}/sigtestdev.jar"/>
</target>

<target name="setup" 
  description="Runs signature test setup for com.acme.openapi package with subpackages"
  depends="td">
  <setup package="com.acme.openapi" failonerror="true" apiVersion="openapi-v2"
    filename="acme-openapi-v1.sig">
    <classpath>
      <pathelement location="${java.home}/jre/lib/rt.jar"/>
      <pathelement location="${testd.home}/lib/acmeAPIv2.jar"/>
    </classpath>
    <exclude class="com.acme.openapi.NotTested"/>
  </setup>
</target>

E.2 Using the SignatureTest Command From an Ant Script

The SignatureTest command can be invoked from Ant script. Both sigtestdev.jar and sigtest.jar contain corresponding Ant tasks. Unlike the ordinary SignatureTest command, its Ant wrapper can run the test only in static mode—reflection mode is not supported. Use the following task definition in your Ant build script:

<taskdef name="test"  classname="com.sun.tdk.signaturetest.ant.ATest"  classpath="sigtest.jar"/>

Table E-2 lists required and optional attributes and nested elements for “test” Ant task.

Table E-2 SignatureTest Attributes Available for Ant Scripts

Attribute	Description
Required:
“package” attribute or nested “package” elements	Corresponds to the `-package` option
“classpath” attribute or nested “classpath” elements	Corresponds to the `-classpath` option
“filename” attribute	Corresponds to the `-filename` option
Optional:
“failonerror” attribute	Stops the build process if the command exits with an error. Default is false
“apiVersion” attribute	Corresponds to the `-apiVersion` option. Sets the API version for signature files.
“exclude” attribute or nested “exclude” elements	Corresponds to the `-exclude` option. Specifies package(s) or class(es), do not require testing.
“binary” attribute	Corresponds to the “`-mode` `bin`” option. Runs the test in binary mode. Default is “false”.
“errorAll” attribute	Corresponds to the `-errorAll` option. Handles warnings as errors. Default is “false”.
“debug” attribute	Corresponds to the `-debug` option. Prints debug information such as detailed stack traces. Default is “false”.
“backward” attribute	Corresponds to the `-Backward` option. Runs backward compatibility checking. Default is “false”.
“formatHuman” attribute	Corresponds to the `-formatHuman` option. Processes human readable error output. Default is “false”.
“output” attribute	Corresponds to the `-out` option. Specifies the report file name.
“negative” attribute	Treats a failed result as successful and a successful result as failed. Used for negative tests. Default value is “false”.

The following code sample shows how to use the SignatureTest command with an Ant script.

<target name="td" description="Signature test task definition">
  <taskdef name="test" classname="com.sun.tdk.signaturetest.ant.ATest"
    classpath="${sigtest.home}/sigtest.jar"/>
</target>

<target name="test" 
  description="Runs migration compatibility test for com.acme.openapi 
  package with subpackages, tests v2 against v1 signature file"
  depends="td">
  <test failonerror="true" apiVersion="openapi-v2"
    filename="acme-openapi-v1.sig" backward="true" output="st_report.txt">
    <package name="com.acme.openapi" />
    <exclude class="com.acme.openapi.NotTested"/>
    <classpath>
      <pathelement location="${java.home}/jre/lib/rt.jar"/>
      <pathelement location="${testd.home}/lib/acmeAPIv2.jar"/>
    </classpath>
 </test>
</target>

E.3 Using the Merge Command From an Ant Script

The Signature Test tool Merge command can be invoked from an Ant script. Both the sigtestdev.jar and sigtest.jar files contain the corresponding Ant task. Use the following task definition in your Ant build script:

<taskdef name="merge" classname="com.sun.tdk.signaturetest.ant.AMerge" classpath="sigtest.jar"/>

Table E-3 and Table E-4 list required and optional attributes and nested elements for the “merge” task.

Table E-3 Required Setup Attributes Available for Ant Scripts

Attribute	Description
“file” nested elements	Corresponds to the `-files` option
“write” attribute	Corresponds to the `-write` option

Table E-4 Optional Setup Attributes Available for Ant Scripts

Attribute	Description
“binary” attribute	Corresponds to the `-binary` option. Default value is “false”.
“failonerror” attribute	Stop the build process if the command exits with an error. Default value is “false”.
“negative” attribute	Treats a failed result as successful and a successful result as failed. Used for negative tests. Default value is “false”.

Table E-5 SAMPLE of REDOING TABLE UNITS: Setup Attributes Available for Ant Scripts

Attribute	Description	Status
“file” nested elements	Corresponds to the `-files` option	Required
“write” attribute	Corresponds to the `-write` option	Required
“binary” attribute	Corresponds to the `-binary` option. Default value is “false”.	Optional
“failonerror” attribute	Stop the build process if the command exits with an error. Default value is “false”.	Optional
“negative” attribute	Treats a failed result as successful and a successful result as failed. Used for negative tests. Default value is “false”.	Optional

The following code shows how to use the Merge command in an Ant script:

<target name="mergeFiles" description="Merges signature files">
     <taskdef name="merge" classname="com.sun.tdk.signaturetest.ant.AMerge"         
        classpath="${sigtest.jar}"/>     <merge write="${build.test.dir}/core_and_loaders.sig" failonerror="true">
     <file name="${build.test.dir}/core.sig"/>
     <file name="${build.test.dir}/loaders.sig"/>
     </merge>
</target>

E.4 Using APICheck From an Ant Script

The API Check tool command can be invoked from an Ant script. The apicheck.jar file contains the corresponding Ant task. Use the following task definition in your Ant build script:

<taskdef name="apicheck" classname="com.sun.tdk.apicheck.ant.ACheck" classpath="apicheck.jar:sigtest.jar"/>

All required and optional attributes and nested elements for the “apicheck” task are the same as used for the Signature Test Tool “test” Ant command and are listed in Table E-2.

See (UNKNOWN STEP NUMBER) for an example that shows how to set up APICheck in an Ant script.