Sun Microsystems Java User Manual

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

THIS PRODUCTCONTAINSCONFIDENTIAL INFORMATION AND TRADE SECRETS OF SUN MICROSYSTEMS, INC. USE, DISCLOSURE ORREPRODUCTION ISPROHIBITED WITHOUTTHE PRIOREXPRESS WRITTENPERMISSION OFSUN MICROSYSTEMS, INC.

U.S. GovernmentRights -Commercial software. Government usersare subjectto theSun Microsystems, Inc. standardlicense agreement and applicable provisionsof theFAR and its supplements.

Sun, SunMicrosystems, theSun logo,Java, Solaris,SigTest, JVM andJAR are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S.and othercountries.

UNIX isa registered trademark inthe U.S.and othercountries, exclusivelylicensed throughX/Open Company, Ltd.

Products covered by andinformation containedin thisservice manualare controlled by U.S.Export Controllaws andmay besubject tothe export orimport lawsin othercountries. Nuclear, missile, chemical biological weapons or nuclear maritime end uses or end users, whether direct orindirect, are strictly prohibited. Exportor reexport to countries subject to U.S. embargoor toentities identiﬁedon U.S.export exclusion lists, including,but notlimited to,the deniedpersons andspecially designatednationals listsis strictlyprohibited.

DOCUMENTATION IS PROVIDED "AS IS" AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID.

CE PRODUITCONTIENT DESINFORMATIONSCONFIDENTIELLES ETDES SECRETSCOMMERCIAUX DESUN MICROSYSTEMS,INC. SON UTILISATION, SA DIVULGATION ET SA REPRODUCTION SONT INTERDITES SANS L AUTORISATION EXPRESSE, ECRITE ET PREALABLE DESUN MICROSYSTEMS,INC.

Sun, SunMicrosystems, lelogo Sun,Java, Solaris,SigTest, JVM etJAR sontdes marques de fabrique ou des marques déposéesde Sun Microsystems, Inc.aux Etats-Uniset dansd’autres pays.

UNIX estune marquedéposée auxEtats-Unis etdans d’autres pays etlicenciée exlusivementpar X/OpenCompany, Ltd.

Les produitsqui fontl’objet dece manueld’entretien et les informations qu’il contient sont regis par la legislation americaine en matiere de controle desexportations etpeuvent etre soumis audroit d’autres pays dansle domainedes exportationset importations.Les utilisations ﬁnales, ouutilisateurs ﬁnaux,pour desarmes nucleaires,des missiles,des armesbiologiques etchimiques oudu nucleaire maritime, directement ouindirectement, sont strictement interdites. Les exportations ou reexportations versdes payssous embargo des Etats-Unis, ou vers desentites ﬁgurantsur leslistes d’exclusiond’exportation americaines,y compris,mais demaniere nonexclusive, laliste depersonnes qui font objetd’un ordre de nepas participer, d’une facon directe ou indirecte,aux exportationsdes produits ou des services qui sont regipar la legislation americaineen matierede controle des exportationset laliste deressortissants speciﬁquementdesignes, sontrigoureusement interdites.

LA DOCUMENTATION EST FOURNIE "EN L’ETAT" ET TOUTES AUTRES CONDITIONS, DECLARATIONSET GARANTIESEXPRESSES OU TACITES SONT FORMELLEMENT EXCLUES, DANS LA MESURE AUTORISEEPAR LA LOIAPPLICABLE, YCOMPRIS NOTAMMENT TOUTE GARANTIEIMPLICITE RELATIVE A LA QUALITE MARCHANDE, A L’APTITUDEA UNEUTILISATIONPARTICULIERE OU A L’ABSENCEDE CONTREFACON.

Please

Recycle

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 Extension Classes 10

Signature File Merge Rules 11

JSR 68-Based Merge 11

iii

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 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. Quick Start Examples 29

Example Setup Command 29

▼ Running the Setup Command 30

Example SignatureTest Command 32

▼ Running SignatureTest Without the JavaTest Harness 32

Example SetupAndTest Command 34

▼ Running the SetupAndTest Command 34

Merge Examples 36

▼ Running Merge Examples 36

iv Signature Test Tool 2.0 User’s Guide • April 2008

Example Result Files 39

Index 43

Contents v

vi Signature Test Tool 2.0 User’s Guide • April 2008

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-7 Merge Command Arguments 28 TABLE A-1 Environment Variable Settings for Merge Examples 36

vii

viii Signature Test Tool 2.0 User’s Guide • April 2008

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 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.sig 41

x Signature Test Tool 2.0 User’s Guide • April 2008

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

This guide is for developers of quality assurance test suites and developers of compatibility test suites — TCKs for a Java Community Process

™

(JCP™) program.

™

platform API as part of the Java

Before You Read This Guide

Before reading this guide, it is best to be familiar with the Java programming language. A good resource for the Java programming language is the Sun Microsystems, Inc. web site, located at http://java.sun.com.

Note – Web URLs provided are subject to change.

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.

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:

■ Create and run a test that verifies that all of the members are present

■ Report when new members are added

■ Check the specified behavior of each API member

The signature test created by SigTest tool can be run independently at the command line, or under the control of the JavaTest™ harness.

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/

The SigTest tool was originally created to assist in the creation of Java technology compatibility test suites (TCKs). It simplified the process of verifying that the API signature of a new implementation of a Java technology matched the signature of a reference implementation of that API.

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 member sets, the test verifies that the following conditions are true:

■ If an API item is defined in the reference representation of the API, then that item

is implemented in the API under test, and vice versa.

■ Attributes chosen for comparison are identical in both implementations of the

API. The tool chooses attributes for comparison according to the type of check being processed. This is described more in the next section.

Mutual Binary Compatibility Check

The signature test binary compatibility check mode verifies that a Java technology implementation undergoing compatibility testing and its referenced APIs are mutually binary compatible as defined in Chapter 13, “Binary Compatibility,” of The Java Language Specification. This assures that any application runs with any compatible API without any linkage errors.

This check is less strict than the default source compatibility check, described next. It is for use primarily in the special case of when a technology is developed for Java technology environments that are purely runtime. Such an environment does not provide a Java technology-based compiler (Java compiler), nor does it include class files that could be used to compile applications for that environment. Because of the limited use of such an environment, the API requirements are slightly relaxed compared to environments that support application development.

Java application environments can contain several Java technologies. Not all Java technologies can be combined with each other, and in particular, their sets of API signatures might be incompatible with each other. Relaxing signature checks to the level of mutual binary compatibility allows the developer to combine technologies in a purely runtime environment that cannot be combined otherwise.

2 Signature Test Tool 2.0 User’s Guide • April 2008

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.

Class and Class Member Attributes Checked

A Java platform API consists of classes, and interfaces, and their member fields, methods, and constructors, and documented annotations. In turn, all of these API items can have various attributes such as names, modifiers, a list of parameters, a list of interfaces, exceptions, nested classes, and so forth. A signature test checks that certain members and attributes belonging to the API under test are the same as those defined by the API to which it is being compared. The signature test checks public and protected API items only and ignores private and package-access items.

The tool checks the following attributes when comparing items in the API implementation under test:

■ Classes and interfaces, including nested classes and interfaces:

■ Set of modifiers except strictfp

■ Name of the superclass

■ Names of all superinterfaces, direct plus indirect, where order is insignificant

■ Constructors:

■ Set of modifiers

■ List of argument types

■ In source compatibility mode only, the normalized list of thrown exceptions

where order is insignificant

Normalizing the throw lists involves removing all superfluous exception classes. An exception class is superfluous if it is a subclass of either the java.lang.RuntimeException class, the java.lang.Error class, or another class from the same list.

■ Methods:

■ The set of modifiers, except strictfp, synchronized, and native

■ The return type

■ The list of argument types

Chapter 1 Introduction 3

■ 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 any classes and interfaces with the same fully qualified name.

2. Taking into account all declared and inherited members, it compares all public and protected members of the same kind and same simple name, treating constructors as class members for convenience sake.

Source and Binary Compatibility Modes

Earlier SigTest tool versions performed a comparison of all exceptions declared in throws clauses for methods and constructors. Certain variations in this area caused an error message during the signature test. Despite these error messages, the source files compiled successfully together. Successful compilation is the basic criteria for source compatibility with the the current SigTest tool, while successful linking as the basic criteria for binary compatibility.

Changes to the throws clause of methods or constructors do not break compatibility with existing binaries because these clauses are checked only at compile time, causing no linkage error. For the purpose of signature testing, this relates directly to binary compatibility as described earlier in “Mutual Binary Compatibility Check” on

page 2.

The adaptation of JSR 68, The Java™ ME Platform Specification, formalized the use of building blocks in API development. A building block is a subset of an existing API that is approved for reuse in the construction of profiles or optional packages. The building block concept enables a developer to duplicate the functionality provided by another API without having to redefine an entirely new API. For further details see JSR 68 at http://www.jcp.org/en/jsr/detail?id=68.

4 Signature Test Tool 2.0 User’s Guide • April 2008

+ 40 hidden pages