This chapter provides a synopsis of each of the Signature Test tool commands along with their available options and arguments. It contains these sections:
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.
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 |
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.
The information related to generics is not used by the Java Virtual MachineFoot 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.
CLASSPATH
and -classpath
SettingsTable 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 |
Table 4-1 Settings for the Setup
and SignatureTest
Commands
Variable or Option | In Reflection Mode | In Static Mode |
---|---|---|
|
Required. Must contain the following:
|
Required. Must contain either |
|
N/A |
Required. Must contain the following:
|
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.
Merge
RulesThe -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
.
The Java ME platform architecture specified by JSR 68Foot 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.
Setup
CommandThe Setup
command has the following synopsis:
java -jar sigtestdev.jar Setup
[options]
or
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".
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 |
Table 4-2 Setup
Command Options
Option | Description |
---|---|
Optional. Displays usage information for available command options and exits. |
|
Optional. Enables printing of the stack trace for debugging purposes if |
|
Required. Specifies the path to one or more APIs that generate the signature file. Can contain multiple directories or ZIP or JAR files. The |
|
Optional. Specifies the directory location in which to create the signature file as a
Must end in a trailing slash on a UNIX system or a backslash on a Microsoft Windows or DOS system. |
|
Required. Specifies the name of the signature file to be created. |
|
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. |
|
Optional. Declines the default |
|
Optional. Specifies a class or package to be included in the signature file, including its subpackages if a package is specified. The |
|
Optional. Similar to the |
|
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 |
|
Optional. Enables error diagnostics for inherited class members. By default, such error messages are suppressed.
|
|
|
Optional. Displays version information. |
Optional. Specifies the API version string to be recorded in the second line of the signature file, as described in "Signature File Contents". |
|
|
Optional. Writes the specified copyright string to the signature file. |
Deprecated. The |
|
Optional. By default, if the |
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
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 |
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 |
v2 |
This is the default format for Signature Test tool 1.2. Generates a signature file with fully qualified class member names and modified |
v2.1 |
This version extends the v2 format to indicate whether an interface is inherited directly or indirectly. It is read by |
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 |
v4.2 |
Support for Java 8 features, such as default and static methods in interfaces, and type and repeating annotations. The |
Also see "Source and Binary Compatibility Modes".
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. |
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.
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 |
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.
SignatureTest
CommandThe SignatureTest
command has the following synopsis:
java -jar sigtest.jar Test
[options]
or
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:
|
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 |
Table 4-5 SignatureTest
Command Options
Option | Description |
---|---|
Optional. Displays usage information for available command options and exits. |
|
Optional. Enables printing of the stack trace for debugging purposes if |
|
Optional. Specifies to run in static mode without using reflection and reports on only the class files specified in the |
|
Optional. Specifies the compatibility mode to use during the signature test, either binary or source, respectively. Defaults to |
|
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. |
|
Specifies not to check the values of primitive and string constants. |
|
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. |
|
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 |
|
Optional. Specifies the directory location of the signature file as a
Must end in a trailing forward slash on a UNIX system or a backslash on a Microsoft Windows or DOS system. |
|
Required if |
|
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 |
|
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 |
|
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 |
|
Optional. Similar to the |
|
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 |
|
Optional. Prints report messages to a specified file instead of standard output. |
|
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. |
Optional. Specifies the API version number of the implementation under test to be recorded in the report. |
|
Optional. Enables error diagnostics for inherited class members. By default, such error messages are suppressed.
|
|
|
Optional. Displays version information. |
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". |
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:
Optional attributes:
Example: <update type="removeclass" classname="com.acme.Zoo" |
removepackage |
Removes all classes belonging to a specified package. Required attributes:
Optional attributes:
Example: <update type="removepackage" packagename="com.acme.animals" id="CR 4657" comments="Removing incorrectly introduced package, approved" /> |
addclass |
Adds a class. Required attributes:
Optional attributes:
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:
Optional attributes:
Example: <update type="removemember" classname="com.acme.zoo.donkey" member="meth public final com.acme.Tail getTail()"/> |
addmember |
Adds a class member. Required attributes:
Optional attributes:
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:
Optional attributes:
Example: <update type="changemember" classname="com.acme.zoo.donkey" member="meth public Ear[] getEars()" newmember="meth public java.util.List<com.acme.Ear> getEars()"/> |
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
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.
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
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
SetupAndTest
CommandThe SetupAndTest
command has the following synopsis:
java -jar sigtestdev.jar SetupAndTest [
options]
or
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.
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 |
Table 4-7 SetupAndTest
Command Options
Option | Description |
---|---|
Optional. Displays usage information for available command options and exits. |
|
Required. Specifies the path to the classes to be used for creating the signature file. |
|
Required. Path to the packages being tested. |
|
Optional. Specifies the signature file name. The command execution uses a temporary file if not specified. |
|
Optional. Specifies the compatibility mode to use during the signature test, either binary or source, respectively. Defaults to |
|
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. |
|
Optional. Specifies package to be tested excluding subpackages. |
|
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 |
|
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. |
|
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. |
|
Optional. Specifies not to check the values of primitive and string constants. |
|
Optional. Enables error diagnostics for inherited class members. By default, such error messages are suppressed.
|
|
|
Optional. Displays version information. |
Optional. Specifies the API version number of the implementation under test to be recorded in the generated report. |
|
Optional. Prints report messages to a specified file instead of standard output. |
|
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. |
Merge
CommandThe Merge
command has the following synopsis:
java -jar sigtest.jar Merge [
options]
or
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.
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 |
---|---|
Optional. Displays usage information for available command options and exits. |
|
|
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 |
Required. Specifies the resulting output signature file. |
|
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.http://jcp.org/en/jsr/detail?id=68