Summary of the content on the page No. 1
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.html
Summary of the content on the page No. 2
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. standard license agreement and applicable provisions of the FAR an
Summary of the content on the page No. 3
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 Tool 7 Signature Test Tool Basics 7 Reflection and Static Run Modes 8 Constant Checking in Differing Run Modes 9 Generics Checking in Binary Mode 9 CLASSPATH and-classpath Settings 10 Bootstrap and Extens
Summary of the content on the page No. 4
Merge Command Operative Principles 11 Element Handling byMerge 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 18 SignatureTest Command 20 Command Description 20 ▼ Running a Signature Test With the JavaTest Harness 23 Report Formats 24 Sorted Report 24 Unsorted Report 25 SetupAndTest Command 26 Command Description 26 Merge Command 27 Command Description 28 A. Quic
Summary of the content on the page No. 5
Example Result Files 39 Index 43 Contents v
Summary of the content on the page No. 6
vi Signature Test Tool 2.0 User’s Guide • April 2008
Summary of the content on the page No. 7
Tables TABLE 2-1 Settings for theSetup andSignatureTest 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-7 Merge Command Arguments 28 TABLE A-1 Environment Variable Settings for Merge Examples 36 vii
Summary of the content on the page No. 8
viii Signature Test Tool 2.0 User’s Guide • April 2008
Summary of the content on the page No. 9
Code Examples CODE EXAMPLE 2-1 Unsorted Report Example 25 CODE EXAMPLE A-1 TheV1.0/test.java File 31 CODE EXAMPLE A-2 Thetest.sig File 31 CODE EXAMPLE A-3 TheV2.0/test.java File 32 CODE EXAMPLE A-4 Thereport.txt File 33 CODE EXAMPLE A-5 SetupAndTest Command Output Example 35 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 ofx1+x2.sig 41 ix
Summary of the content on the page No. 10
x Signature Test Tool 2.0 User’s Guide • April 2008
Summary of the content on the page No. 11
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.net/ Who Should Use This Guide
Summary of the content on the page No. 12
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. Related Documentation For details on the Java programming language, see the following documents: ■ The Java Programming Language, Third Edition ■ The Java Language Specifica
Summary of the content on the page No. 13
Typographic Conventions Typeface Meaning Examples AaBbCc123 The names of commands, files, Edit your .login file. and directories, or on-screen Use ls -a to list all files. computer output % You have mail. AaBbCc123 Book titles, new words or terms, Read Chapter 6 in the User’s Guide. words to be emphasized These are called class options. You must be superuser to do this. Command-line variable or To delete a file, type rm filename. placeholder. Replace with a real name or value * SigTest-Directory
Summary of the content on the page No. 14
xiv Signature Test Tool 2.0 User’s Guide • April 2008
Summary of the content on the page No. 15
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. SigTest tool compares the signatures of two implementations of the same API and and can do the following: ■ Creat
Summary of the content on the page No. 16
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. By checking for equality of API
Summary of the content on the page No. 17
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 de
Summary of the content on the page No. 18
■ 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. For all top-level public and protected classes and interfaces, it compares the attributes of an
Summary of the content on the page No. 19
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. The SignatureTest command recognizes the -mode option that takes the values “src” or “bin” as arguments for choosing so
Summary of the content on the page No. 20
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 SigTest- Directory/redistributables/
