SigTest Tool 2.0 User’s Guide For Java™ Compatibility Test Suite Developers Sun Microsystems, Inc. www.sun.com April 2008 Submit comments about this document at: http://java.sun.com/docs/forms/sendusmail.
Copyright © 2008 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, U.S.A. All rights reserved. THIS PRODUCT CONTAINS CONFIDENTIAL INFORMATION AND TRADE SECRETS OF SUN MICROSYSTEMS, INC. USE, DISCLOSURE OR REPRODUCTION IS PROHIBITED WITHOUT THE PRIOR EXPRESS WRITTEN PERMISSION OF SUN MICROSYSTEMS, INC. U.S. Government Rights - Commercial software. Government users are subject to the Sun Microsystems, Inc.
Contents Preface 1. xi Introduction 1 Signature Test Basics What is Tested 1 2 Mutual Binary Compatibility Check 2 Mutual Source Compatibility Check 3 Class and Class Member Attributes Checked Source and Binary Compatibility Modes Using Custom Signature Loaders 2.
Merge Command Operative Principles Element Handling by Merge Setup Command 11 12 14 Command Description 14 Case Sensitivity of Command Arguments Signature File Formats 16 Signature File Contents 17 Signature File Header Signature File Body Command Description 20 20 Running a Signature Test With the JavaTest Harness Report Formats 24 Unsorted Report 25 SetupAndTest Command 26 Command Description 26 Merge Command 27 Command Description Quick Start Examples 28 29 Example Setup Comman
Example Result Files Index 39 43 Contents v
vi Signature Test Tool 2.
Tables TABLE 2-1 Settings for the Setup and SignatureTest Commands TABLE 2-2 Setup Command Arguments TABLE 2-3 Signature File Format Compatibility TABLE 2-4 Signature File Content Summary TABLE 2-5 SignatureTest Command Arguments TABLE 2-6 SetupAndTest Command Argument TABLE 2-7 Merge Command Arguments TABLE A-1 Environment Variable Settings for Merge Examples 10 14 16 18 20 26 28 36 vii
viii Signature Test Tool 2.
Code Examples CODE EXAMPLE 2-1 Unsorted Report Example 25 CODE EXAMPLE A-1 The V1.0/test.java File 31 CODE EXAMPLE A-2 The test.sig File 31 CODE EXAMPLE A-3 The V2.0/test.java File CODE EXAMPLE A-4 The report.txt File 32 33 CODE EXAMPLE A-5 SetupAndTest Command Output Example CODE EXAMPLE A-6 Contents of ./x1.sig 39 CODE EXAMPLE A-7 Contents of ./x2.sig 40 CODE EXAMPLE A-8 Contents of ./x3.sig 40 CODE EXAMPLE A-9 Contents of x1+x2.
x Signature Test Tool 2.
Preface This guide describes how to install and run the SigTest tool. This tool is composed of a group of utilities used to develop signature test components that can be used to compare API test signatures. Note – For simplicity, this user’s guide refers to the test harness as the JavaTest harness. Note that the open source version of the harness, called JT harness, can be used in its place. The JT harness software can be downloaded from: http://jtharness.dev.java.
How This Guide Is Organized Chapter 1 describes SigTest tool and the purpose of signature testing. Chapter 2” provides a synopsis of each of the SigTest tool commands along with their available options and arguments. Appendix ” provides SigTest tool command examples that you can run to quickly familiarize yourself with them.
Typographic Conventions Typeface Meaning Examples AaBbCc123 The names of commands, files, and directories, or on-screen computer output Edit your .login file. Use ls -a to list all files. % You have mail. AaBbCc123 Book titles, new words or terms, words to be emphasized Read Chapter 6 in the User’s Guide. These are called class options. You must be superuser to do this. Command-line variable or placeholder. Replace with a real name or value To delete a file, type rm filename.
xiv Signature Test Tool 2.
CHAPTER 1 Introduction The SigTest tool makes it possible to easily compare the signatures of two different implementations of the same API. It verifies that all of the members are present, reports when new members are added, and checks the specified behavior of each API member. Signature Test Basics A signature test compares two implementations of an API and reports the differences.
When used in a software development environment, SigTest tool can be used to track and control changes to an API throughout the development process. What is Tested The signature test algorithm compares the API implementation under test with a signature file created from the API you are comparing it to — often referred to as a reference implementation. The signature test checks for mutual binary or source compatibility by verifying the equality of API member sets.
Mutual Source Compatibility Check While binary compatibility is important, it cannot guarantee that an application in binary form as a set of class files can be recompiled without error. The signature test source compatibility check mode verifies that any application that compiles without error with a compatible API, compiles without error with all other source compatible APIs. Mutual source compatibility is a stricter check than the mutual binary compatibility and SigTest tool performs it by default.
■ ■ ■ In source mode only, the normalized list of thrown exceptions, described earlier, where order is insignificant Fields: ■ Set of modifiers, except transient ■ Field type Documented annotations with SOURCE and RUNTIME retention of the following types: ■ Classes and interfaces ■ Fields, methods and constructors ■ Parameters and annotation types The tool performs the check in the following order: 1.
The use of building blocks created a need for more lenient checking of exception throw lists compared to earlier SigTest tool versions. Consequently, SigTest tool 1.5 provides both a source and a binary compatibility mode of operation. This retains compatibility with earlier signature files while adding support for building blocks and eliminating the unnecessary error messages.
As an aid in developing such an extension, the SigTest tool distribution includes a class library that contains a signature serializer and some related utility classes in the SigTest-Directory/lib/remote.jar file. This file contains a subset of the SigTest tool classes that are necessary to develop a custom plug-in. All of these library classes are CDC 1.0 compatible and have minimal memory requirements. The source code for these classes is distributed in the SigTestDirectory/redistributables/sigtest_src.
CHAPTER 2 Using the Signature Test Tool This chapter provides a synopsis of each of the SigTest 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 Also see Appendix A for examples of each SigTest tool command that you can run.
■ 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 SigTest 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.
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. Constant Checking in Differing Run Modes The requirements related to constant checking differ in binary and source compatibility testing.
CLASSPATH and -classpath Settings TABLE 2-1 lists the requirements for setting the CLASSPATH environment variable and the -classpath argument when running either the Setup or SignatureTest commands.
Signature File Merge Rules The -Files argument 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.
■ The Merge operation is commutative, so with API A and B, A + B = B + A. ■ It recognizes either binary or source compatibility when merging APIs. ■ For any application X that is compatible with either API A or B, when A and B are merged then X must be compatible with the resulting API C. ■ The resulting API C cannot contain a class that is not found in either of the A or B input APIs. This means that any class in C has to have corresponding classes in either A or B or both A and B.
■ When there are two different access modifiers select the more visible one. For example, if A is a public int foo, and B is protected int foo, then the merge into C results into public int foo. ■ If the elements differ in the final modifier, do not include it If a class is final, then all of its methods are implicitly final according to Section 8.4.3.3 of The Java Language Specification, 2nd Editon. ■ If corresponding elements differ in the static modifier, then declare a conflict.
Setup Command The Setup command has the following synopsis: java com.sun.tdk.signaturetest.Setup [arguments] TABLE 2-2 describes the available command arguments and the values that they accept. Before running the command, also see these sections: “CLASSPATH and -classpath Settings” on page 10 and “Case Sensitivity of Command Arguments” on page 16. Command Description The Setup command accepts a reference implementation of an API as input.
TABLE 2-2 Setup Command Arguments (Continued) Setup Option Description -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.
Case Sensitivity of Command Arguments The specification of each argument flag at the command line is not case sensitive, but the input value entered immediately after the argument flag is case sensitive. The following two command lines produce identical results for the -FileName flag: % java com.sun.tdk.signaturetest.Setup -FileName name.sig % java com.sun.tdk.signaturetest.Setup -filename name.
TABLE 2-3 Signature File Format Compatibility (Continued) Format Description 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 SigTest 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.
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 2-4: ■ For each public or protected class, all modifiers except strictfp, and the fully qualified name of any superclass or interfaces implemented, generic type parameters, and annotations.
TABLE 2-4 Signature File Content Summary (Continued) Modifier Class or Interface strictfp – Field Method – transient – volatile + synchroniz ed – native – Chapter 2 Constructor Nested Class or Interface – Using the Signature Test Tool 19
SignatureTest Command The SignatureTest command has the following synopsis: java com.sun.tdk.signaturetest.SignatureTest [arguments] It follows the rules described in “Case Sensitivity of Command Arguments” on page 16. TABLE 2-5 lists the available arguments. Note – SignatureTest command settings for the CLASSPATH environment variable and the -classpath argument are the same as those listed for the Setup command in TABLE 2-1.
TABLE 2-5 SignatureTest Command Arguments (Continued) Option Description -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.
TABLE 2-5 SignatureTest Command Arguments (Continued) Option Description -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.
▼ Running a Signature Test With the JavaTest Harness Although the SignatureTest command can be run by itself, SignatureTest can also be executed as a test by the JavaTest harness. This section describes the items that must be in place in a test suite to perform the signature test with the JavaTest harness. If you are developing an API, it is advisable to provide a signature test along with any behavioral tests you develope for that API.
5. Change the following two arguments in the executeArgs value of the test description file in use. ■ Change the argument to the -FileName option in the test description to correspond to the signature file name. It will look something like this: -FileName ./name.
■ 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 superc
SetupAndTest Command The SetupAndTest command has the following synopsis: java com.sun.tdk.signaturetest.SetupAndTest [arguments] TABLE 2-6 describes all arguments available to the SetupAndTest command. See “Case Sensitivity of Command Arguments” on page 16 and “CLASSPATH and -classpath Settings” on page 10. SetupAndTest requires sigtestdev.jar in the CLASSPATH environment variable.
TABLE 2-6 SetupAndTest Command Argument (Continued) -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.
TABLE 2-7 describes the arguments available to the Merge command. Also see “Case Sensitivity of Command Arguments” on page 16. Command Description The Merge command combines (merges) a number of input signature files into one resulting signature file. See “Signature File Merge Rules” on page 11 for details on the rules used for merging, and “Signature File Formats” on page 16 for details on supported versions of signature file formats..
APPENDIX A Quick Start Examples This appendix provides a simple example of each of the SigTest tool commands that you can run quickly to become familiar with them. It contains these sections: ■ Example Setup Command ■ Example SignatureTest Command ■ Example SetupAndTest Command ■ Merge Examples Note – These examples are meant to be run in sequential order with the commands using output created by the previous example.
▼ Running the Setup Command 1. At a command prompt, change to a current working directory of your choice and note that all subsequent steps and commands are relative to this directory. 2. Using your favorite text editor, copy and paste the code from the test.java file in CODE EXAMPLE A-1 into a file with the same name under a new V1.0 subdirectory, with this as a result: current-working-dir/V1.0/test.
5. Confirm the correct contents of the resulting test.sig file by comparing it with CODE EXAMPLE A-2. This completes the Setup command example. Note – Save the files you created in this procedure for use in the subsequent example in “Running SignatureTest Without the JavaTest Harness” on page 32.” CODE EXAMPLE A-1 The V1.0/test.java File package example; public class test { public T get (T x) { return x; } } CODE EXAMPLE A-2 The test.sig File #Signature file v4.0 #Version V1.
Example SignatureTest Command This section illustrates how to run SignatureTest from the command line without the JavaTest harness. Also see “Running a Signature Test With the JavaTest Harness” on page 23 to see how the signature test is run automatically during a test run. ▼ Running SignatureTest Without the JavaTest Harness This procedure uses the same test.sig file (contents in CODE EXAMPLE A-2) and the same environment setup created in “Running the Setup Command” on page 30. 1.
3. Compile the V2.0/test.java source file version with this command, noting that this newly compiled version serves as the implementation class under test. % javac -d V2.0 V2.0/test.java This step generates the following new class file to be tested against the test.sig file in the next step: ./V2.0/example/test.class 4. Run the SignatureTest command against the new class file using the -out option to direct the results to a report.txt file with this command: % java -cp V2.0:$CLASSPATH \ com.sun.tdk.
The report.txt File CODE EXAMPLE A-4 Added Methods ------------example.test: example.test: method public java.lang.String example.test.get(int) method public void example.test.put() STATUS:Failed.3 errors Example SetupAndTest Command The following procedure runs the SetupAndTest command to create a new test2.sig file from the input API class, and compare it with the specified example package.
% java $CLASSPATH com.sun.tdk.signaturetest.SetupAndTest \ -apiVersion 2.0 \ -reference V1.0:$JRE \ -test V2.0:$JRE \ -package example \ -FileName test2.sig The previous SetupAndTest command reports to standard output a message similar to CODE EXAMPLE A-5 with differences according to your system characteristics : CODE EXAMPLE A-5 SetupAndTest Command Output Example Invoke Setup ... Class path: "V1.0;C:\java\jdk1.5.0_06\/jre/lib/rt.
Merge Examples This section illustrates an example of running Merge which involves these three steps: 1. Compiling three .java files to produce .class files as a source for the signature files used in the example 2. Running the Setup command on each .class file to produce its signature file 3. Using Merge to combine the files and see the results.
package x; public class A { public void abc() {} public void bar() {} } Contents of: ./3/A.java package x; public class A { public static void abc() {} } 3. Run these commands to compile each file into a separate x subdirectory: % javac -d 1 1/A.java % javac -d 2 2/A.java % javac -d 3 3/A.java These are the resulting files: ■ ./1/x/A.class ■ ./2/x/A.class ■ ./3/x/A.class 4. Run these three Setup command lines on each A.class file to produce the three x#.sig files as shown. a.
b. Run command #2: % java -cp 2:$CLASSPATH com.sun.tdk.signaturetest.Setup \ -static -classpath 2:$RT_JAR -package x -FileName x2.sig The command generates the ./x2.sig file shown in CODE EXAMPLE A-7 and produces a console message similar to this indicating successful setup with some possible differences according to your system characteristics: Class path: "2:/opt/jdk1.5.0_09/jre/lib/rt.
6. Run this command to merge x2.sig and x3.sig attempting to produce the x2+x3.sig file: % java -cp $CLASSPATH com.sun.tdk.signaturetest.Merge -Files x2.sig:x3.sig -Write x2+x3.sig The command prints a message to the console similar to the following with possible differences due to system characteristics indicating a conflicting static modifier, and no signature file is created: x.A.abc : modifier conflict STATUS:Error.Error The conflict is that x2.
CODE EXAMPLE A-6 CLSS cons meth meth supr Contents of ./x1.sig (Continued) public x.A public A() public void abc() public void foo() java.lang.Object CODE EXAMPLE A-7 Contents of ./x2.sig #Signature file v4.0 #Version CLSS public java.lang.Object cons public Object() meth protected java.lang.Object clone() throws java.lang.CloneNotSupportedException meth protected void finalize() throws java.lang.Throwable meth public boolean equals(java.lang.Object) meth public final java.lang.
CODE EXAMPLE A-8 Contents of ./x3.sig (Continued) meth protected void finalize() throws java.lang.Throwable meth public boolean equals(java.lang.Object) meth public final java.lang.Class getClass() meth public final void notify() meth public final void notifyAll() meth public final void wait() throws java.lang.InterruptedException meth public final void wait(long) throws java.lang.InterruptedException meth public final void wait(long,int) throws java.lang.
CODE EXAMPLE A-9 Contents of x1+x2.sig meth public void bar() meth public void foo() supr java.lang.Object 42 Signature Test Tool 2.
Index C command arguments -apiVersion, 27 -Binary, 28 -CheckValue, 21, 27 -ClassCacheSize, 21, 27 -classpath, 14, 21 -ClosedFile, 15 -debug, 14, 20 -ErrorAll, 22 -exclude, 15, 22, 27 -FileName, 15, 21, 26 -Files, 21 -FormatPlain, 22, 27 -help, 14, 20, 26, 28 -mode, 20 -NoCheckValue, 21, 27 -NoMerge, 22 -NonClosedFile, 15 -out, 22, 27 -package, 15, 22, 26 -PackageWithoutSubpackages, 15, 22, 27 -reference, 26 -static, 14, 20 -test, 26 -TestURL, 15, 21 -verbose, 15, 22, 27 -version, 15, 22 -Write, 28 commands
U unsorted report, 25 44 Signature Test Tool 2.
