4 Using the Signature Test Tool

This chapter provides a synopsis of each of the Signature Test tool commands along with their available options and arguments. It contains these sections:

Signature Test Tool Basics
Setup Command
SignatureTest Command
SetupAndTest Command
Merge Command
Report Formats

Note:

Appendix A includes examples of each command.

4.1 Signature Test Tool Basics

The Signature Test tool operates from the command line to generate or manipulate signature files. A signature file is a text representation of the set of public and protected features provided by an API. Test suite developers include it in a finished test suite as a signature reference for comparison to the technology implementation under test. The following list shows the commands that are available.

Setup - Creates a signature file from either an API defined by a specification or a reference API implementation.
SignatureTest - Compares the reference API represented in the signature file to the API under test and produces a report. This is the test that becomes part of a finished test suite.
SetupAndTest - Executes the Setup and SignatureTest commands in one operation.
Merge - Creates a combined signature file from several signature files representing different Java APIs in one Java runtime environment according to the JSR 68 rules.

The Signature Test tool distribution includes a Java Archive (JAR) file used for developing a signature test and one for distribution within a finished test suite to run its signature test. The description of each follows:

sigtestdev.jar - Contains classes for running the commands used during signature test development.
sigtest.jar - Contains only the classes for running the SignatureTest command. This file is distributed in a finished test suite.

Test suite developers perform these operations while using sigtestdev.jar to develop a signature test.

Run the Setup command to create a signature file from either an API defined by a specification or a reference API implementation.
Include the files required to run the signature test in the finished test suite distribution.

4.1.1 Reflection and Static Run Modes

Two run modes are available during command execution. These modes determine how the class descriptions are examined and retrieved, as follows:

Reflection Mode - Uses reflection to examine API classes and retrieve information about them. The reflection mode is of greatest advantage when the API to be analyzed has no external class files.

Static Mode - Specified with the -static flag, the tool parses only the class files listed in the -classpath command-line option.

Note:

In static mode you can test specified classes in another runtime environment. For example, this can be useful to analyze APIs that are part of a Java SE platform 1.4.2 environment when the SignatureTest command is run on a Java SE platform version 5.0.

4.1.2 Constant Checking in Differing Run Modes

The requirements related to constant checking differ in binary and source compatibility testing. Although constant checking can be applied to binary compatibility, it is a necessary prerequisite for source code compatibility. Use the -static mode to enforce strict constant checking in source code compatibility testing.

When running a signature test in source compatibility mode and using the static mode, constant checking is strict and two way. This means that all the constant fields specified in the reference API must exist and have the same values in the API under test. Likewise, all the constant fields and their related values specified in the API under test must exist and have the same values in the reference API.

In binary compatibility mode, the requirements related to constant checking are less strict. The signature test verifies that all the constant fields and associated values contained in the reference API are also available in the API under test. If any field values are missing or different, it reports an error. However, the signature test does not report an error if constant values are found in the API under test that are not available in the reference API.

4.1.3 Generics Checking in Binary Mode

The information related to generics is not used by the Java Virtual Machine^Foot 1 at runtime. This information is used only by the compiler at compile time. Because the information does not effect the runtime linkage process, it cannot cause binary incompatibility.

In binary mode the SignatureTest command compares the signatures of parameterized types after omitting the type parameters and arguments from both the signature file and the analyzed API (termed ”type erasure”). This is to ensure that they are compatible at runtime. See The Java Language Specification at http://docs.oracle.com/javase/specs/ for a detailed description of type erasure.

The bridge methods that are generated by the compiler during type erasure are not a part of the API and so they are ignored by the Signature Test tool.

4.1.4 `CLASSPATH` and `-classpath` Settings

Table 4-1 lists the requirements for setting the CLASSPATH environment variable and the -classpath option when running either the Setup or SignatureTest commands. The table uses the following terms to describe the classes that must be included:

Required classes - All superclasses and superinterfaces of the classes under test
Classes under test - The set of classes specified by a combination of the following options:
- -package
- -PackageWithoutSubpackages
- -exclude
  
  Note:
  
  The Setup command can only be run in static mode.

Table 4-1 Settings for the Setup and SignatureTest Commands

Variable or Option In Reflection Mode In Static Mode

Variable or Option	In Reflection Mode	In Static Mode
`CLASSPATH` environment variable	Required. Must contain the following: `sigtestdev.jar` or `sigtest.jar` Classes under test Other required classes, except for bootstrap and extension classes described in "Bootstrap and Extension Classes"	Required. Must contain either `sigtestdev.jar` or `sigtest.jar`.
`-classpath` argument	N/A	Required. Must contain the following: Classes under test All required classes

CLASSPATH environment variable

Required. Must contain the following:

sigtestdev.jar or sigtest.jar
Classes under test
Other required classes, except for bootstrap and extension classes described in "Bootstrap and Extension Classes"

Required. Must contain either sigtestdev.jar or sigtest.jar.

-classpath argument

N/A

Required. Must contain the following:

Classes under test
All required classes

4.1.4.1 Bootstrap and Extension Classes

Bootstrap and extension classes are those located in rt.jar and several other JAR files under the Java-Home/jre/lib/ directory, where Java-Home is the base directory of the Java platform runtime installation. For example, classes from the java package such as java.lang.Object are bootstrap classes. Their location is already available to the Java Virtual Machine environment. Because of this, they do not need to be specified in the CLASSPATH environment variable when reflection mode is used. Furthermore, bootstrap and extension classes are always loaded from JAR files located in the Java-Home/jre/lib/ directory, regardless of whether they were specified in the class path or not. This is an important feature of the reflection mode.

4.2 Signature File `Merge` Rules

The -Files option of the SignatureTest command accepts values to specify one or more signature files that are combined to represent an API configuration that is used as input for testing. This resulting API-set can also be combined into a single signature file for testing purposes.

By default the API combination is assumed to be constructed according to the JSR 68 rules. This can be overridden during a Signature Test tool test run by specifying the -NoMerge option to run the signature test. The -NoMerge option forces the Signature Test tool to use the first class description it encounters if more than one class with the same name is found in the set of signature files specified by the -Files option. In this case it uses the class from the left-most signature file that is specified with -Files.

Note:

The operative merging principles used by the Signature Test tool are described in Appendix D.

4.2.1 Java ME Platform-based Merge

The Java ME platform architecture specified by JSR 68^Foot 2 allows for the inclusion of several Java platform APIs in one conforming Java platform runtime environment. The condition for combining these APIs is that any application written for the resulting runtime environment must execute successfully on the combination. See the JSR 68 specification for details.

If such a combination exists, it is defined on the basis of the combined sets of APIs with semantics, and the semantics must be compatible with those of all the included components.

The only means of verifying the semantics of the combination is to run the applicable test suite for each API. However, it is possible to automate the creation of a combined set of API signatures, and it is also possible to detect when a combined set cannot be built.

The Merge command functionality combines (merges) several input signature files into one resulting signature file, as follows: If A, B, and C are signature files, then A + B yields signature file C, and each of the three signature files represent the corresponding classes of their respective APIs. The Merge process constructs the resulting API C out of the two input APIs A and B.

4.3 `Setup` Command

The Setup command has the following synopsis:

java -jar sigtestdev.jar Setup [options]

java com.sun.tdk.signaturetest.Setup [options]

Table 4-2 describes the available command options and the values that they accept. Before running the command, also see these sections: "Case Sensitivity of Option Arguments" and "CLASSPATH and -classpath Settings".

4.3.1 Command Description

The Setup command accepts a reference implementation of an API as input. The command processes the API input to generate a signature file that represents the API to be used as a reference of comparison for the purpose of signature testing.

Setup processes the API input in the static mode by parsing the set of classes specified with the -classpath options.

Also see Appendix A for an example of the command that you can run.

Note:

Arguments to options marked with an asterisk (*) in Table 4-2 can be specified multiple times. For example, if you want to specify filtering for the java.awt, java.lang, and java.math packages, you can specify the three arguments separated by a file separator character as shown in the following example:. -Package java.awt:java.lang:java.math On Unix operating systems the separator character is ”:” and on Microsoft Windows it is ”;”.

Table 4-2 Setup Command Options

Option	Description
`-help`	Optional. Displays usage information for available command options and exits.
`-debug`	Optional. Enables printing of the stack trace for debugging purposes if `Setup` fails.
`-classpath` path	Required. Specifies the path to one or more APIs that generate the signature file. Can contain multiple directories or ZIP or JAR files. The `-package` option further refines the set of classes specified in `-classpath` (see "`CLASSPATH` and `-classpath` Settings"). There is no default `-classpath`. Use the path separator appropriate for the platform (identified by `java.io.File.pathSeparator`).
`-TestURL` path	Optional. Specifies the directory location in which to create the signature file as a `file` protocol URL: `file://`path Must end in a trailing slash on a UNIX system or a backslash on a Microsoft Windows or DOS system. `Setup` does not support the HTTP protocol.
`-FileName` file_name	Required. Specifies the name of the signature file to be created.
`-ClosedFile`	Optional. The default if not specified. Specifies to include in the signature file all direct and indirect superclasses for all required classes (tested classes), even if these superclasses are non-public or from untested packages.
`-NonClosedFile`	Optional. Declines the default `-ClosedFile` mode previously described. Does not include all direct and indirect superclasses and superinterfaces of tested classes in the signature file
`-package` package_or_class_name*	Optional. Specifies a class or package to be included in the signature file, including its subpackages if a package is specified. The `-package` value acts as a filter on the set of classes specified in `-classpath`. The default is all classes. Repeat the option to specify multiple entries.
`-PackageWithoutSubpackages` package*	Optional. Similar to the `-package` option, this specifies a package to be included but without its subpackages. Repeat the option to specify multiple entries.
`-exclude` package_or_class_name*	Optional. Specifies a package or class to be excluded from the signature file, including its subpackages. Repeat the option for multiple entries. Excludes duplicate entries specified by the `-package` or the `-PackageWithoutSubpackages` option.
`-verbose [nowarn \| noerr]`	Optional. Enables error diagnostics for inherited class members. By default, such error messages are suppressed. `nowarn`: Suppress warnings. `noerr`: Suppress errors.
`-version`	Optional. Displays version information.
`-apiVersion` version_string	Optional. Specifies the API version string to be recorded in the second line of the signature file, as described in "Signature File Contents".
`-CopyRight` copyright_string	Optional. Writes the specified copyright string to the signature file.
`-static`	Deprecated. The `Setup` command now runs only in static mode.
`-keepfile`	Optional. By default, if the `Setup` command encounters an error, it does not keep the generated signature file. This option directs the `Setup` command to keep the generated signature file if an error is encountered. Use this option with caution because the signature file might be inconsistent.

4.3.2 Case Sensitivity of Option Arguments

The specification of each argument option at the command line is not case sensitive, but the input value entered immediately after the option is case sensitive.

The following two command lines produce identical results for the -FileName flag:

% java -jar sigtestdev.jar Setup -FileName name.sig
% java -jar sigtestdev.jar Setup -filename name.sig

However, these two might not produce identical results if the host operating system is case sensitive to the file name values entered:

% java -jar sigtestdev.jar Setup -FileName name.sig
% java -jar sigtestdev.jar Setup -FileName NAME.sig

4.3.3 Signature File Formats

The Signature Test tool has changed signature file formats through progressive versions. Table 4-3 lists the existing signature file formats and describes how each relates to a specific Signature Test tool version. In Signature Test tool 2.2, the SignatureTest and Merge commands read v2.1 and later signature files, and output only v4.1.

Table 4-3 Signature File Format Compatibility

Format	Description
v0	Generates a signature file with simple class member names. This was the default format in Signature Test tool 1.0, but is not supported by `SignatureTest` command in Signature Test tool 1.3 and later.
v1	Generates a signature file with fully qualified class member names. This was the default format in Signature Test tool 1.1. This format includes non-normalized exception throw lists for constructors and methods. Normalizing the throw list involves removing all superfluous exception classes. A class is superfluous if it is a subclass of either the `java.lang.RuntimeException` class, or the `java.lang.Error` class, or another class from the same list. This format is not supported by `SignatureTest` command in Signature Test tool 1.3 and later.
v2	This is the default format for Signature Test tool 1.2. Generates a signature file with fully qualified class member names and modified `supr` statements. This format includes normalized exception throw lists for constructors and methods. This format is not supported by `SignatureTest` command in Signature Test tool 1.3 and later.
v2.1	This version extends the v2 format to indicate whether an interface is inherited directly or indirectly. It is read by `SignatureTest` command in Signature Test tool 1.3 and later.
v3.1	Generates data for JDK^™ software version 5.0 such as generics, annotations, and enums.
v4.0	Inherited members are not written to the signature file. Private and default visibility fields and nested classes that can potentially hide visible API elements are tracked. In Signature Test tool 2.2, all output files are of this version.
v4.1	Non-static constants are written to the signature file. References to outer classes are stored for the inner classes. Constructor names are changed to `<init>`. This has been the case since SigTest 2.2.
v4.2	Support for Java 8 features, such as default and static methods in interfaces, and type and repeating annotations. The `Setup` command writes files in this format since Signature Test tool 3.0.

Also see "Source and Binary Compatibility Modes".

4.3.4 Signature File Contents

Setup generates each signature file with a mandatory header in the first two lines, followed by the body of the signature file.

Note:

Comment lines start with the pound (#) character and can be inserted anywhere after the first two mandatory header lines.

4.3.4.1 Signature File Header

Setup generates the first two mandatory header lines of each signature file as follows:

#Signature file format
#Version version-string

With the following variable replacement values:

format is either one of the values described in Table 4-3, or empty, that indicates v0.
version-string is a value taken directly from the argument given at the startup command line to the -apiVersion option (see Table 4-2).

Note that the header can also contain an optional copyright string.

4.3.4.2 Signature File Body

The remaining body of a signature file immediately follows the header. It contains the following information, which is further clarified in Table 4-4:

For each public or protected class:
- All modifiers except strictfp
- The fully qualified name of any superclass or interfaces implemented
- Generic type parameters, and annotations.
For each public or protected interface:
- All modifiers except strictfp
- The fully qualified name of any superinterfaces implemented,
- Generic type parameters
- Annotations
For each public or protected field:
- All modifiers except transient and volatile
- The fully qualified name of the field's type and its fully qualified name
- If the field is a primitive or string constant, the value of the field is included
- Documented annotations and type parameters
For each public or protected method:
- All modifiers (except native, synchronized, and strictfp)
- The fully qualified name of the type of returned value, the method's fully qualified name
- Types of all parameters
- The names of exceptions declared in a throws clause

For each public or protected constructor:

All modifiers
The fully qualified name of the constructor
Types of all parametera
Any exceptions declared in a throws clause

Note:

All private types that are used in the definition of a public or protected item are substituted by their public or protected equivalent if possible, otherwise an error is generated. All types included in a signature file are either public or protected and not private or package local.

Table 4-4 further summarizes the contents of a generated signature file. A plus (+) indicates a class modifier is included in a generated signature file and a minus (-) indicates it is ignored for that particular element. A blank cell indicates that the condition does not apply to a cell, for example, a class does not have a transient modifier so it is blank.

Table 4-4 Signature File Content Summary

Modifier	Class or Interface (Including Nested)	Field	Method	Constructor
`public`	+	+	+	+
`protected`	+	+	+	+
`abstract`	+		+
`static`	+	+	+
`final`	+	+	+
`strictfp`	–		–	–
`transient`		–
`volatile`		–
`synchronized`			–
`native`			–
`varargs`			+	+

4.4 `SignatureTest` Command

The SignatureTest command has the following synopsis:

java -jar sigtest.jar Test [options]

java com.sun.tdk.signaturetest.SignatureTest [options]

The second alternative assumes that sigtest.jar is on the class path. The rules described in "Case Sensitivity of Option Arguments" apply. Table 4-5 lists the available options.

Note:

SignatureTest command settings for the CLASSPATH environment variable and the -classpath option are the same as those listed for the Setup command in Table 4-1.

4.4.1 Command Description

The SignatureTest command compares the reference API represented in a signature file to the API under test and produces a report. Depending on the command-line options specified, it uses either the reflection or static mode. If the -classpath option is specified, the SignatureTest command checks if any extra classes are contained in the APIs it specifies.

See "Signature File Formats" for details about supported versions of signature file formats.

Note:

Arguments to options marked with an asterisk (*) in Table 4-5 can be specified multiple times. For example, if you want to specify filtering for the java.awt, java.lang, and java.math packages, you can specify the three arguments separated by a file separator character as shown in the following example:. --Package java.awt:java.lang:java.math On Unix operating systems the separator character is ”:” and on Microsoft Windows it is ”;”.

Table 4-5 SignatureTest Command Options

Option	Description
`-help`	Optional. Displays usage information for available command options and exits.
`-debug`	Optional. Enables printing of the stack trace for debugging purposes if `SignatureTest` fails.
`-static`	Optional. Specifies to run in static mode without using reflection and reports on only the class files specified in the `-classpath` option.
`-mode [bin \| src]`	Optional. Specifies the compatibility mode to use during the signature test, either binary or source, respectively. Defaults to `src`. "Source and Binary Compatibility Modes" describes each mode.
`-CheckValue`	Specifies to check the values of primitive and string constants. This option generates an error if a signature file does not contain the data necessary for constant checking.
`-NoCheckValue`	Specifies not to check the values of primitive and string constants.
`-ClassCacheSize` size_of_cache	Optional. Used in static mode only. Default is 1024. Specifies the size of the class cache as a number of classes to be held in memory to reduce execution time. Increasing this value dedicates more memory to this function.
`-classpath` path	Optional. Specifies the path to one or more APIs to be tested. Defaults to the classes contained in the signature file under test. Can contain multiple directories or ZIP or JAR files. The `-package` option filters the set of classes specified in `-classpath` (see "`CLASSPATH` and `-classpath` Settings"). Uses the path separator appropriate for the platform (identified by `java.io.File.pathSeparator`).
`-TestURL` URL	Optional. Specifies the directory location of the signature file as a `file` protocol URL: `file://`path Must end in a trailing forward slash on a UNIX system or a backslash on a Microsoft Windows or DOS system.
`-FileName` file_name	Required if `-Files` is not specified. Specifies the name of a signature file to be used.
`-Files` file_names	Required if -FileName is not specified. Use this option for testing a combination of APIs represented by corresponding signature files. Specifies the names of the signature files to be used delimited by a file separator. The file separator on UNIX systems is a colon (:) character, and on Microsoft Windows systems it is a semicolon (;). See "Signature File `Merge` Rules" for details about the rules used for merging.
`-NoMerge`	Optional. Forces using the first encountered class description if more than one class with the same name is found in the input set of signature files specified by `-Files` option. In this case it uses the class from the left-most signature file that is specified with `-Files`. This option prevents the test from using the default merging behavior according to the JSR 68 rules. See "Signature File `Merge` Rules" for details about the rules used for merging.
`-Package` package_or_class_name*	Optional. Specifies a class or package to be reported on, including its subpackages if a package is specified. The default is all classes and packages in the signature file. This option acts as a filter on the set of classes or packages optionally specified in `-classpath`. Repeat the option to specify multiple entries.
`-PackageWithoutSubpackages` package*	Optional. Similar to the `-package` option, specifies a package to be reported on without its subpackages. Repeat the option to specify multiple entries.
`-Exclude` package_or_class_name*	Optional. A package or class to be excluded from the report, including its subpackages. Repeat the option for multiple entries. Excludes duplicate entries specified by the `-package` or the `-PackageWithoutSubpackages` option.
`-out` file_name	Optional. Prints report messages to a specified file instead of standard output.
`-FormatPlain`	Optional. Specifies not to sort report messages, but output them immediately. Allows a decrease in memory consumption compared to the default sorted format of message reporting.
-FormatHuman -H	Optional. Specifies the human-readable report output format. Simple API changes are presented not as pair of errors (”missing element” and ”added element”), but as a single API change.
-Backward -B	Optional. Specifies migration compatibility check mode.
`-apiVersion` version_string	Optional. Specifies the API version number of the implementation under test to be recorded in the report.
`-verbose [nowarn \| noerr]`	Optional. Enables error diagnostics for inherited class members. By default, such error messages are suppressed. `nowarn`: Suppress warnings. `noerr`: Suppress errors.
`-version`	Optional. Displays version information.
`-ErrorAll`	Optional. Specifies to make the signature test more strict by upgrading certain warnings to errors.
-Update file_name	Optional. Specifies the name of an update file. See "Using Update Files".

4.4.2 Using Update Files

An update file is an XML file that contains API changes that can be applied to a signature file before tests are performed. An update can have an ID and corresponding comments. Example 4-1 shows an example of an update file that removes and adds a class before test execution.

Example 4-1 Update File Example

<updateset>
    <update type=”removeclass” id=”Change #12” comments=”Fixing bug #1234”
            classname=”com.acme.Elefant” />
    <update type=”addclass” id=”Change #13” comments=”Approved by the committee”
            classname=”com.acme.Tiger” />
    CLSS public com.acme.Tier”>    
    cons public <init>()
    cons public <init>(java.land.String)
    supr java.lang.Object
    </update>
</updateset>

The XML file is enclosed within the <updateset> element and each change is specified in an <update> element. Each <change> element consists of a type and a set of attributes. The types and their attributes are described in Table 4-6.

Table 4-6 Update Types and Attributes

Update Types	Description
removeclass	Removes a class. Required attributes: classname - the name of the class to remove Optional attributes: id - change ID comments - a comment that describes the change Example: <update type="removeclass" classname="com.acme.Zoo" id="Issue #1717" comments="Bug fixing" />
removepackage	Removes all classes belonging to a specified package. Required attributes: packagename - the name of the package to remove Optional attributes: id - change ID comments - a comment that describes the change Example: <update type="removepackage" packagename="com.acme.animals" id="CR 4657" comments="Removing incorrectly introduced package, approved" />
addclass	Adds a class. Required attributes: classname - the name of the class to remove Definition of the new class in the element body Optional attributes: id - change ID comments - a comment that describes the change Example: <update type="addclass" classname="com.acme.zoo.Rabbit"> CLSS public com.acme.zoo.Rabbit cons public <init>() cons public <init>(java.lang.String) supr com.acme.zoo.Animal </update>
removemember	Removes a class member. Required attributes: classname - the name of the class to change member - the name of the member signature to remove Optional attributes: id - change ID comments - a comment that describes the change Example: <update type="removemember" classname="com.acme.zoo.donkey" member="meth public final com.acme.Tail getTail()"/>
addmember	Adds a class member. Required attributes: classname - the name of the class to change member - the member signature add Optional attributes: id - change ID comments - a comment that describes the change Example: <update type="addmember" classname="com.acme.zoo.donkey" comments="See wiki for details" member="meth public com.acme.Ear[] getEars()"/>
changemember	Changes a class member Required attributes: classname - the name of the class to change member - the member signature to change newmember -the new member signature Optional attributes: id - change ID comments - a comment that describes the change Example: <update type="changemember" classname="com.acme.zoo.donkey" member="meth public Ear[] getEars()" newmember="meth public java.util.List<com.acme.Ear> getEars()"/>

4.4.3 Report Formats

You can cause SignatureTest command report messages to be sorted (default), or unsorted by specifying the -FormatPlain flag at the command line. See Step 8 of the procedure "Using the SetupAndTest Command" to see a sorted report that was generated into a plain text file with the -out option. Report messages contain the following types of information:

The versions of both the reference API and the API under test
The total number of errors found
The differences such as added or missing classes, superclasses, fields, or methods
The fully qualified name of the enclosing class related to any missing or added description
Two errors for any modified item, one for a missing item and another for an added item
A description of any incompatibility in the API implementation under test

4.4.3.1 Sorted Report

Report messages are sorted by default. Unlike the unsorted format, duplicate messages are removed. To accurately compare the error totals between formats, the sorted report prints two error counts: the total number of errors and the total number of duplicates.

The sorted report groups error messages by category of difference with classes within each category ordered alphabetically by name, and empty categories are ignored. This is the category ordering sequence:

Missing Classes
Missing Class Descriptions (Modified classes and nested classes)
Missing Superclasses or Superinterfaces
Missing Fields
Missing Constructors
Missing Methods
Added Classes
Added Class Descriptions (Modified classes and nested classes)
Added Superclasses or Superinterfaces
Added Fields
Added Constructors
Added Methods
Linkage Errors

Linkage errors occur during testing if the API implementation under test is corrupted, for example, if a superclass or superinterface of a class under test cannot be loaded.

See the sorted report in Example A-4.

4.4.3.2 Unsorted Report

The -FormatPlain option specifies an unsorted report. The unsorted format reports messages immediately during execution and duplicate messages are included.

Example 4-2 shows an unsorted report that corresponds to the sorted report in Example A-4.

Example 4-2 Unsorted Report Example

Definition required but not found in example.test
    method public int get(int)
Definition found but not permitted in example.test
    method public java.lang.String get(int)
Definition found but not permitted in example.test
    method public void put()
SignatureTest report
Tested version: 2.0
STATUS: Failed. 3 errors

4.4.3.3 Human-Readable Report

The human-readable report format is similar to the sorted report format. Unlike the sorted report format where some changes in the API are presented as pairs of messages (”added element” and ”missed element”), the human-readable report format presents these changes as a single message that describes the difference between the APIs. This report recognizes the following cases:

Modifiers were changed
Return type was changed
Parameter types were changed
Normalized throw list was changed
Constant value was changed
Annotation was changed

Unlike the sorted report format, all messages are grouped by class first, rather than message type. The code example below shows the output for an class:

Class tests.human.many.E1
  Changed
    method public abstract void tests.human.many.E1.foo() throws java.io.IOException
    - Throws: [java.io.IOException]
    method public abstract void tests.human.many.E1.foo() throws java.io.IOException
    - [public, abstract]
    + [protected]
    field public final static int tests.human.many.E1.i = 0
    - type: int
    + type: char
    field public final static int tests.human.many.E1.i = 0
    - value: 0

4.5 `SetupAndTest` Command

The SetupAndTest command has the following synopsis:

java -jar sigtestdev.jar SetupAndTest [options]

java com.sun.tdk.signaturetest.SetupAndTest [options]

The second alternative assumes that sigtestdev.jar is on the class path. The rules described in "Case Sensitivity of Option Arguments" apply. Table 4-7 lists the available options.

4.5.1 Command Description

SetupAndTest is a wrapper command that runs only in static mode to execute the Setup and SignatureTest commands in one operation. It performs these functions:

Calls the Setup command to create a signature file from the reference API specified as input. It creates a temporary signature file if no name is specified for it with the -FileName option.
Calls the SignatureTest command to make the comparison and produce a report.

Note:

Arguments to options marked with an asterisk in Table 4-7 can be specified multiple times. For example, if you want to specify filtering for the java.awt, java.lang, and java.math packages, you can specify the three arguments separated by a file separator character as shown in the following example:-Package java.awt:java.lang:java.math On Unix operating systems the separator character is ”:” and on Microsoft Windows it is ”;”.

Table 4-7 SetupAndTest Command Options

Option	Description
`-help`	Optional. Displays usage information for available command options and exits.
`-reference` path	Required. Specifies the path to the classes to be used for creating the signature file.
`-test` path	Required. Path to the packages being tested.
`-FileName` file	Optional. Specifies the signature file name. The command execution uses a temporary file if not specified.
`-mode [bin \| src]`	Optional. Specifies the compatibility mode to use during the signature test, either binary or source, respectively. Defaults to `src`. "Source and Binary Compatibility Modes" describes each mode.
`-package` package_or_class_name*	Optional. Specifies a class or package to be reported on, including its subpackages if a package is specified. This option acts as a filter on the set of classes or packages that are tested and reported on. The default is all classes and packages. Repeat the option to specify multiple entries.
`-PackageWithoutSubpackages` name*	Optional. Specifies package to be tested excluding subpackages.
`-exclude` name*	Optional. A package or class to be excluded from testing, including its subpackages. Repeat the option for multiple entries. Excludes duplicate entries specified by the `-package` or the `-PackageWithoutSubpackages` option.
`-ClassCacheSize` size_of_cache	Optional. Specifies the size of the class cache as a number of classes to be held in memory to reduce execution time. Increasing this value dedicates more memory to this function. Defaults to 100.
`-CheckValue`	Optional. Specifies to check the values of primitive and string constants. This option generates an error if a signature file does not contain the data necessary for constant checking.
`-NoCheckValue`	Optional. Specifies not to check the values of primitive and string constants.
-`verbose [nowarn \| noerr]`	Optional. Enables error diagnostics for inherited class members. By default, such error messages are suppressed. `nowarn`: Suppress warnings. `noerr`: Suppress errors.
`-version`	Optional. Displays version information.
`-apiVersion` version_string	Optional. Specifies the API version number of the implementation under test to be recorded in the generated report.
`-out` file_name	Optional. Prints report messages to a specified file instead of standard output.
`-FormatPlain`	Optional. Specifies not to sort report messages, but output them immediately. Allows a decrease in memory consumption compared to the default sorted format of message reporting.
-FormatHuman -H	Optional. Specifies the human-readable report output format. Simple API changes are presented not as pair of errors (”missing element” and ”added element”), but as a single API change.
-Backward -B	Optional. Specifies migration compatibility check mode.

4.6 `Merge` Command

The Merge command has the following synopsis:

java -jar sigtest.jar Merge [options]

java com.sun.tdk.signaturetest.Merge [options]

The second alternative assumes that sigtest.jar is on the class path. The rules described in "Case Sensitivity of Option Arguments" apply. Table 4-8 lists the available options.

4.6.1 Command Description

The Merge command combines (merges) a number of input signature files into one resulting signature file. See "Signature File Merge Rules" for details about the rules used for merging, and "Signature File Formats" for details about supported versions of signature file formats. Table 4-8 lists the Merge command options.

Table 4-8 Merge Command Options

Option	Description
`-help`	Optional. Displays usage information for available command options and exits.
`-Files`	Required. Specifies the names of the signature files to be merged delimited by a file separator. The file separator on UNIX systems is a colon (:) character, and on Microsoft Windows systems it is a semicolon (;). See "Signature File `Merge` Rules" for details about the rules used for merging.
`-Write`	Required. Specifies the resulting output signature file.
`-Binary`	Optional. Specifies to use the binary merge mode. See "Source and Binary Compatibility Modes".

Footnote Legend

Footnote 1: The terms ”Java Virtual Machine” and ”JVM” mean a Virtual Machine for the Java platform.
Footnote 2: http://jcp.org/en/jsr/detail?id=68

4 Using the Signature Test Tool

4.1 Signature Test Tool Basics

4.1.1 Reflection and Static Run Modes

4.1.2 Constant Checking in Differing Run Modes

4.1.3 Generics Checking in Binary Mode

4.1.4 CLASSPATH and -classpath Settings

4.1.4.1 Bootstrap and Extension Classes

4.2 Signature File Merge Rules

4.2.1 Java ME Platform-based Merge

4.3 Setup Command

4.3.1 Command Description

4.3.2 Case Sensitivity of Option Arguments

4.3.3 Signature File Formats

4.3.4 Signature File Contents

4.3.4.1 Signature File Header

4.3.4.2 Signature File Body

4.4 SignatureTest Command

4.4.1 Command Description

4.4.2 Using Update Files

4.4.3 Report Formats

4.4.3.1 Sorted Report

4.4.3.2 Unsorted Report

4.4.3.3 Human-Readable Report

4.5 SetupAndTest Command

4.5.1 Command Description

4.6 Merge Command

4.6.1 Command Description

4.1.4 `CLASSPATH` and `-classpath` Settings

4.2 Signature File `Merge` Rules

4.3 `Setup` Command

4.4 `SignatureTest` Command

4.5 `SetupAndTest` Command

4.6 `Merge` Command