F Using the SigTest Tools With Apache Maven

The Apache Maven SigTest plug-in (sigtest-plugin) makes the functionality of the Sigtest, Setup and Merge commands available from Maven 2 build scripts. The Maven APICover plug-in (apicover-plugin) makes the functionality of the APICover tool available to Maven 2 build scripts. All goals are bound by default to the ”test” life cycle phase.

F.1 Goal Overview

The the four sigtest-plugin goals are described in Table F-1:

Table F-1 The sigtest-plugin Goals

Goal	Description
`sigtest-plugin:setup`	Provides `Setup` command functionality to Maven 2 build scripts. Creates a signature file from an API defined by a specification or a reference implementation.
`sigtest-plugin:test`	Provides static mode SignatureTest functionality to Maven 2 build scripts. Compares the reference API represented in the signature file to the API under test and produces a report.
`sigtest-plugin:merge`	Provides Merge functionality to Maven 2 build scripts. Creates a combined signature file from several signature files representing different Java platform APIs in one Java runtime environment according to the JSR 68 rules.
`apicover-plugin:apicover`	Provides API Coverage tool functionality to Maven 2 build scripts, This goal is used to estimate the test coverage that a test suite under development affords to implementations of its related API specification.

F.2 Goal Descriptions

The following sections describe the requirements and parameters for each of the goals listed in Table F-1. An example follows each section.

F.2.1 sigtest-plugin:setup

The setup goal accepts a reference implementation of an API as input. The command processes API input in order to generate a signature file that represents the API to be used as a reference for comparison during signature testing.

Full name: com.sun.tdk:sigtest-plugin:2.2:setup
Requires a Maven 2.0 project to be executed.
Binds by default to the life cycle phase: test

Table F-2 Required Parameters (sigtest-plugin:setup)

Name	Type	Corresponding Setup Command Option	Description
fileName	String	-filename	Specifies the name of the signature file to be created.
pathElements	List	-classpath	Specifies the path to one or more APIs that generate the signature file. Can contain multiple directories, Zip files or JAR files.
packages	List	-package	Specifies classes or packages to be included in the signature file including its subpackages if a package is specified.

Table F-3 Optional Parameters (sigtest-plugin:setup)

Name	Type	Corresponding Setup Command Option	Default Value	Description
excludes	List	-exclude		Specifies a package or class to be excluded from the signature file, including its subpackages.
nonClosedFile	boolean	-NonClosedFile	FALSE	Causes direct and indirect superclasses and superinterfaces of tested classes not to be included in the signature file. This eliminates cases where they do not belong to the scope defined by ”packages” parameters.
apiVersion	String	-apiVersion		Specifies the API version string to be recorded in the second line of the signature file.
failOnError	boolean		TRUE	Stops the build process if the command exits with an error.
negative	boolean		FALSE	Treats tests that do not succeed as having passed, and tests that do succeed as having failed. Used for negative tests.

Example F-1 Sample Plugin Configuration (pom.xml)

<project>
  . . .
  <build> 
      . . .
      <plugins> 
        <plugin> 
          . . .
          <groupId>com.sun.tdk</groupId> 
          <artifactId>sigtest-plugin</artifactId> 
          <configuration> 
            <fileName>java-awt-lang-math.sig</fileName> 
            <packages> 
              <package>java.awt</package> 
              <package>java.lang</package> 
              <package>java.math</package> 
            </packages> 
            <excludes> 
              <exclude>java.lang.Math</exclude> 
              <exclude>java.lang.ref</exclude> 
            </excludes> 
            <pathElements> 
              <pathElement>${ref.jhome}/jre/lib/rt.jar</pathElement> 
            </pathElements> 
            <apiVersion>Java Six</apiVersion> 
          </configuration> 
        </plugin> 
        . . .
      </plugins> 
      . . .
  </build> 
 . . 
</project>

F.2.2 sigtest-plugin:test

The test goal compares the reference API (represented in a signature file) to the API under test and produces a report. Unlike the SignatureTest command it only supports static mode—reflection is not supported

Full name: com.sun.tdk:sigtest-plugin:2.2:test
Requires a Maven 2.0 project to be executed.
Binds by default to the life cycle phase: test

Table F-4 Required Parameters (sigtest-plugin:test)

Name	Type	Corresponding Setup Option	Description
fileName	String	-filename	Specifies the name of the signature file to be created.
pathElements	List	-classpath	Specifies the path to one or more APIs that generate the signature file. Can specify multiple directories, Zip files or JAR files.
packages	List	-package	Specifies classes or packages to be included in the signature file, including its subpackages if a package is specified.

Table F-5 Optional Parameters (sigtest-plugin:test)

Name	Type	Corresponding SignatureTest Option	Default Value	Description
excludes	List	-exclude		Specifies a package or class to be excluded from the signature file, including its subpackages.
apiVersion	String	-apiVersion		Specifies the API version string to be recorded in the second line of the signature file.
binary	boolean	-mode bin	FALSE	Specifies that binary mode be used during the signature test instead of the source code compatibility mode.
backward	boolean	-Backward	FALSE	Specifies migration instead of mutual compatibility check mode.
human	boolean	-FormatHuman	FALSE	Specifies the human-readable report output format.
errorAll	boolean	-ErrorAll	FALSE	Specifies that the signature test be made stricter by upgrading certain warnings to errors.
debug	boolean	-debug	FALSE	Enables printing of the stack trace for debugging purposes if SignatureTest fails.
failOnError	boolean		TRUE	Stops the build process if the command exits with an error.
negative	boolean		FALSE	Treats tests that do not succeed as having passed, and tests that do succeed as having failed. Used for negative tests.

Example F-2 Sample Plugin Configuration (pom.xml)

<project>
  . . .
  <build> 
      . . .
      <plugins> 
        <plugin> 
          . . .
          <groupId>com.sun.tdk</groupId> 
          <artifactId>sigtest-plugin</artifactId> 
          <configuration> 
            <fileName>java-awt-lang-math.sig</fileName> 
            <packages> 
              <package>java.awt</package> 
              <package>java.lang</package> 
              <package>java.math</package> 
            </packages> 
            <excludes> 
              <exclude>java.lang.Math</exclude> 
              <exclude>java.lang.ref</exclude> 
            </excludes> 
            <pathElements> 
              <pathElement>${ref.jhome}/jre/lib/rt.jar</pathElement> 
            </pathElements> 
            <apiVersion>Java Six</apiVersion> 
            <failOnError>false</failOnError> 
            <human>true</human> 
            <backward>true</backward> 
            <out>report.txt</out> 
            <debug>true</debug> 
          </configuration> 
        </plugin> 
        . . .
      </plugins> 
      . . .
  </build> 
 . . 
</project>

F.2.3 sigtest-plugin:merge

The merge goal command combines (merges) a number of input signature files into a single signature file.

Full name: com.sun.tdk:sigtest-plugin:2.2:merge
Requires a Maven 2.0 project to be executed.
Binds by default to the life cycle phase: test

Table F-6 Required Parameters (sigtest-plugin:merge)

Name	Type	Corresponding Merge option	Description
write	String	-Write	Specifies the resulting output signature file.
files	List	-Files	Specifies the names of the signature files to be merged.

Table F-7 Optional Parameters (sigtest-plugin:merge)

Name	Type	Corresponding Merge Option	Default Value	Description
binary	boolean	-Binary	FALSE	Specifies that binary mode be used during the signature test instead of the source code compatibility mode.
failOnError	boolean		TRUE	Stops the build process if the command exits with an error.
negative	boolean		FALSE	Treats tests that do not succeed as having passed, and tests that do succeed as having failed. Used for negative tests.

Example F-3 Sample Plugin Configuration (pom.xm)

<project>
  . . .
  <build> 
      . . .
      <plugins> 
        . . .
        <plugin> 
          . . .
          <groupId>com.sun.tdk</groupId> 
          <artifactId>sigtest-plugin</artifactId> 
          <configuration> 
            <files>
              <file>baseAPI.sig</file>
              <file>optionalAPI1.sig</file>
              <file>optionalAPI2.sig</file>
            </files> 
            <write>result.sig</write> 
            <failOnError>false</failOnError> 
          </configuration> 
        </plugin> 
        . . .
      </plugins> 
      . . .
  </build> 
  . . . 
</project>

F.2.4 apicover-plugin:apicover

The apicover-plugin:apicover goal is used to estimate the test coverage that a test suite under development affords to implementations of its related API specification. It does this by determining how many public class members the test suite references within the API specification that it is designed to test against. The tool uses a signature file representation of the API specification as the basis of its specification analysis.

Full name: com.sun.tdk:apicover-plugin:2.2:apicover
Requires a Maven 2.0 project to be executed.
Binds by default to the life cycle phase: test

Table F-8 Required Parameters (apicover-plugin:apicover)

Name	Type	Corresponding APICover Option	Description
tests	List	-ts	Specifies the path to the test suite classes to be analyzed. Also accepts a JAR file.
api	String	-api	Specifies the location of the signature file representing the API under examination.

Table F-9 Optional Parameters (apicover-plugin:apicover)

Name	Type	Corresponding APICover Option	Default Value	Description
tsIncludes	List	-tsInclude		Recursively includes classes from the specified test suite package.
tsIncludeWs	List	-tsIncludeW		Includes classes from the specified test suite package without subpackages.
tsExcludes	List	-tsExclude		Recursively excludes classes from the specified test suite package.
apiIncludes	List	-apiInclude		Recursively includes classes from the specified API package.
apiIncludeWs	List	-apiIncludeW		Includes classes from the specified API package without subpackages.
apiExcludes	List	-apiExclude		Recursively excludes classes from the specified API package.
excludeLists	List	-excludeList		Specifies the file name of an exclude list that contains API elements to be excluded from the coverage calculation.
excludeInterfaces	boolean	-excludeInterfaces	FALSE	Excludes all interface classes.
excludeAbstractClasses	boolean	-excludeAbstractClasses	FALSE	Excludes all abstract classes including interfaces.
excludeAbstractMethods	boolean	-excludeAbstractMethods	FALSE	Excludes all abstract methods from all classes and interfaces
excludeFields	boolean	-excludeFields	FALSE	Excludes all fields from all classes and interfaces.
includeConstantFields	boolean	-includeConstantFields	FALSE	Specifies the inclusion of all final fields of any type in the coverage calculation.
mode	String	-mode	w (worst case)	Specifies the mode of coverage calculation as ”w” which represents the worst case or ”r” which represents the real world.
detail	String	-detail	2	Specifies the level of report detail as an integer from 0-4
format	String	-format	plain	Specifies the report format as plain text or XML. The values can be ”plain” or ”xml”. Note that an example of the XML output is available in SIGTEST_HOME`/msc.`
report	String	-report	See the description.	Specifies the location of the generated report file. The path argument defaults to the working directory when only a file name is specified. If a file name is not specified, it defaults to the Maven logger
out	String	-out	See the description	Generates a specially formatted report file for use by other applications and places it at the specified location/file name. The path defaults to the working directory.

Example F-4 Sample Plugin Configuration (pom.xml)

<project>
  . . .
  <build> 
      . . .
      <plugins> 
        . . .
        <plugin> 
          . . .
          <groupId>com.sun.tdk</groupId> 
          <artifactId>apicover-plugin</artifactId> 
          <configuration> 
            <api>publicAPIv3.sig</api> 
            <tests> 
              <test>${ts.path}/testSet1.jar</test> 
              <test>${ts.path}/testSet2.jar</test> 
              <test>${ts.path}/testSet3.jar</test> 
            </tests> 
            <apiIncludes> 
              <apiInclude>com.acme.api</apiInclude> 
            </apiIncludes> 
            <mode>r</mode> 
            <detail>4</detail> 
            <format>plain</format> 
            <report>${report.path}/covrep_real.txt</report> 
          </configuration> 
          . . .
        </plugin> 
        . . .
      </plugins> 
      . . .
  </build> 
  . . . 
</project>