Page 3 - Contents; Preface; CLASSPATH
iii Contents Preface xi 1. Introduction 1 Signature Test Basics 1 What is Tested 2 Mutual Binary Compatibility Check 2 Mutual Source Compatibility Check 3 Class and Class Member Attributes Checked 3 Source and Binary Compatibility Modes 4 Using Custom Signature Loaders 5 2. Using the Signature Test ...
Page 4 - Quick Start Examples
iv Signature Test Tool 2.0 User’s Guide • April 2008 Merge Command Operative Principles 11 Element Handling by Merge 12 Setup Command 14 Command Description 14 Case Sensitivity of Command Arguments 16 Signature File Formats 16 Signature File Contents 17 Signature File Header 17 Signature File Body 1...
Page 5 - Example Result Files; Index
Page 7 - Tables
vii Tables TABLE 2-1 Settings for the Setup and SignatureTest Commands 10 TABLE 2-2 Setup Command Arguments 14 TABLE 2-3 Signature File Format Compatibility 16 TABLE 2-4 Signature File Content Summary 18 TABLE 2-5 SignatureTest Command Arguments 20 TABLE 2-6 SetupAndTest Command Argument 26 TABLE 2-...
Page 9 - Code Examples
ix 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 32 CODE EXAMPLE A-4 The report.txt File 33 CODE EXAMPLE A-5 SetupAndTest Command Output Example 35 CODE EXAMPLE A-6 ...
Page 11 - Who Should Use This Guide; Note –
xi Preface This guide describes how to install and run the SigTest tool. This tool is composed ofa group of utilities used to develop signature test components that can be used tocompare API test signatures. Note – For simplicity, this user ’s guide refers to the test harness as the JavaTest harness...
Page 12 - How This Guide Is Organized; Related Documentation
xii Signature Test Tool 2.0 User’s Guide • April 2008 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 t...
Page 13 - Typographic Conventions
Preface xiii Typographic Conventions Sun Welcomes Your Comments We are interested in improving our documentation and welcome your commentsand suggestions. Send us your comments at http://java.sun.com/docs/forms/sendusmail.html . Typeface Meaning Examples AaBbCc123 The names of commands, files,and di...
Page 15 - Introduction; Signature Test Basics
1 C H A P T E R 1 Introduction The SigTest tool makes it possible to easily compare the signatures of two differentimplementations 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 eachAPI member. Signature Test ...
Page 16 - What is Tested; Mutual Binary Compatibility Check
2 Signature Test Tool 2.0 User’s Guide • April 2008 When used in a software development environment, SigTest tool can be used totrack and control changes to an API throughout the development process. What is Tested The signature test algorithm compares the API implementation under test with asignatu...
Page 17 - Mutual Source Compatibility Check; Class and Class Member Attributes Checked
Chapter 1 Introduction 3 Mutual Source Compatibility Check While binary compatibility is important, it cannot guarantee that an application inbinary form as a set of class files can be recompiled without error. The signature test source compatibility check mode verifies that any application thatcomp...
Page 18 - Source and Binary Compatibility Modes
4 Signature Test Tool 2.0 User’s Guide • April 2008 ■ In source mode only, the normalized list of thrown exceptions, describedearlier, where order is insignificant ■ Fields: ■ Set of modifiers, except transient ■ Field type ■ Documented annotations with SOURCE and RUNTIME retention of the following ...
Page 19 - Using Custom Signature Loaders
Chapter 1 Introduction 5 The use of building blocks created a need for more lenient checking of exceptionthrow lists compared to earlier SigTest tool versions. Consequently, SigTest tool 1.5provides both a source and a binary compatibility mode of operation. This retainscompatibility with earlier si...
Page 21 - Using the Signature Test Tool; Signature Test Tool Basics
7 C H A P T E R 2 Using the Signature Test Tool This chapter provides a synopsis of each of the SigTest tool commands along withtheir available options and arguments. It contains these sections: ■ Signature Test Tool Basics ■ Setup Command ■ SignatureTest Command ■ SetupAndTest Command ■ Merge Comma...
Page 22 - Reflection and Static Run Modes
8 Signature Test Tool 2.0 User’s Guide • April 2008 ■ Merge - Creates a combined signature file from several signature files representing different Java APIs in one Java runtime environment according tothe JSR 68 rules. The SigTest tool distribution includes a Java™ Archive (JAR) file used fordevelo...
Page 23 - Constant Checking in Differing Run Modes
Chapter 2 Using the Signature Test Tool 9 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 platform1.4.2 environment when the SignatureTest command is run on a Java SE platform version 5.0....
Page 24 - Bootstrap and Extension Classes
10 Signature Test Tool 2.0 User’s Guide • April 2008 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. The table uses the following terms to describe t...
Page 25 - Signature File
Chapter 2 Using the Signature Test Tool 11 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 thatis used as input for testing. This resulting API-set can also be combin...
Page 26 - Element Handling by
12 Signature Test Tool 2.0 User’s Guide • April 2008 ■ 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 aremerged then X mus...
Page 28 - Command Description
14 Signature Test Tool 2.0 User’s Guide • April 2008 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...
Page 30 - Case Sensitivity of Command Arguments
16 Signature Test Tool 2.0 User’s Guide • April 2008 Case Sensitivity of Command Arguments The specification of each argument flag at the command line is not case sensitive, butthe input value entered immediately after the argument flag is case sensitive. The following two command lines produce iden...
Page 31 - Signature File Contents; Signature File Header
Chapter 2 Using the Signature Test Tool 17 Also see “Source and Binary Compatibility Modes” on page 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 (#...
Page 32 - Signature File Body
18 Signature Test Tool 2.0 User’s Guide • April 2008 Signature File Body The remaining body of a signature file immediately follows the header. It containsthe following information, which is further clarified in TABLE 2-4 : ■ For each public or protected class, all modifiers except strictfp , and th...
Page 38 - Change the following two arguments in the; value of the test; Report Formats; Sorted Report
24 Signature Test Tool 2.0 User’s Guide • April 2008 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: -...
Page 39 - Unsorted Report
Chapter 2 Using the Signature Test Tool 25 ■ 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 ...
Page 43 - Example
29 A P P E N D I X A Quick Start Examples This appendix provides a simple example of each of the SigTest tool commands thatyou can run quickly to become familiar with them. It contains these sections: ■ Example Setup Command ■ Example SignatureTest Command ■ Example SetupAndTest Command ■ Merge Exam...
Page 44 - Running the
30 Signature Test Tool 2.0 User’s Guide • April 2008 ▼ 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 fr...
Page 45 - Confirm the correct contents of the resulting
Appendix A Quick Star t Examples 31 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...
Page 46 - Running
32 Signature Test Tool 2.0 User’s Guide • April 2008 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 autom...
Page 48 - environment variable for access to the Java runtime environment
34 Signature Test Tool 2.0 User’s Guide • April 2008 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. ▼ Running the SetupAndTest Command This procedure assume...
Page 50 - Merge Examples; Running Merge Examples
36 Signature Test Tool 2.0 User’s Guide • April 2008 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 ea...
Page 51 - Run these commands to compile each file into a separate; command lines on each
Appendix A Quick Star t Examples 37 Contents of: ./3/A.java 3. Run these commands to compile each file into a separate x subdirectory: 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 # ....
Page 52 - Run this command to merge
38 Signature Test Tool 2.0 User’s Guide • April 2008 b. Run command #2: 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 somepossible differences according to your system characteristics: c. Run command ...
Page 53 - Run this command to merge
Appendix A Quick Star t Examples 39 6. Run this command to merge x2.sig and x3.sig attempting to produce the x2+x3.sig file: The command prints a message to the console similar to the following with possibledifferences due to system characteristics indicating a conflicting static modifier, and no si...
