Sun Microsystems 2 - Manuals

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 (#...

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

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: -...

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

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

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

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

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

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

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

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 # ....

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

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