Release Notes

[Skip TOC]

Table of Contents

Introduction

New in This Release

System Requirements

Documentation

Release Contents

Installation

Using the Signature Test Tool

Using the API Coverage Tool

Known Bugs and Issues

Introduction

These release notes contain information about version 2.1 of the SigTest tools. See the SigTest 1.2 User's Guide for more information about the tools.

The SigTest project is a collection of tools that can be used to compare APIs and to measure the test coverage of an API. The tools were originally created to assist in the creation of Java technology compatibility test suites (TCKs), but are also useful in the creation of other types of test suites and in the software development process. The SigTest product consists of the following two tools.

• The Signature Test tool makes it easy to compare the signatures of two different implementations or different versions of the same API. When it compares different implementations of the same API, the tool verifies that all of the members are present, reports when new members are added, and checks the specified behavior of each API member. When it compares different versions of the same API, the tool checks that the old version can be replaced by the new one without adversely affecting existing clients of the API.
• The API Coverage tool can be used to estimate the test coverage a test suite provides for an implementation of a specified API. It does this by determining how many public class members the test suite references within the API specification. The tool uses a signature file representation of the API specification as the source of specification analysis. It does not process a formal specification in any form.

[Top]

New in This Release

The following new features have been added and the following bugs have been fixed.

New Features

• Added API coverage functionality
• Added migration compatibility checking.
• Added Ant wrappers for Signature Test tool.

This release of SigTest also includes the following improvements:

• Issue 16 - Default entry point added
• Issue 13 - Multiply sigtest/sigsetup runs in the same JVM are supported
• Issue 23 - Support for "extensible interfaces" mode
• Issue 11 - com.sun.tdk.signaturetest.Setup.run()/main() methods return status
• Issue 12, Issue 5 - Help messages improved

[Top]

Fixed Bugs

The following bugs have been fixed.

[Top]

System Requirements

Using the SigTest tools requires a properly configured certified Java Platform, Standard Edition (Java SE™ platform) runtime environment version 1.4 or later, or a Java SE platform 5.0 runtime environment if using reflection to test version 5.0 and later class files. A properly configured JDK™ installation is required to compile the examples.

[Top]

Documentation

Documentation about this project can be found on the SigTest Project web site.

In addition, you can download the SigTest 2.1 User's Guide from the java.sun.com web site. This manual was created to describe the commercial SigTest product upon which the open source SigTest tool is based. It describes the SigTest tool and how to create signature tests for your API or application. This documentation is provided solely for your convenience and is not being released under GPL version 2 as part of this project. This document cannot be modified.

[Top]

Installation

To install SigTest, unzip the distribution into a directory of your choice. For example, at a UNIX® system prompt type the following command:

% unzip sigtest-2.1.zip

Unpacking the Zip bundle installs subdirectories under the base installation directory. For more information, see the Release Contents section below and the documents listed under "For SigTest contributors" in the Quick Links box on the front page of the SigTest Project website.

[Top]

Release Contents

This section lists the components under the base subdirectory structure (SigTest-2.1/) that is created when you unzip the SigTest distribution archive during installation.

[Top]

Component Descriptions and Locations

[Top]

Using the Signature Test Tool

The Signature Test Tool operates from the command line with the following commands.

• The Setup command creates a signature file from either an API defined by a specification or a reference API implementation. A signature file is a text representation of the set of public and protected features provided by an API. Test suite developers include it in a finished test suite as a signature reference for comparison to the technology implementation under test.
• The SignatureTest command compares the reference API represented in the signature file to the API under test and produces a report. This is the test that becomes part of a finished test suite.
• The SetupAndTest command runs only in static mode, described later, to execute the Setup and SignatureTest commands in one operation.
• The Merge command creates a combined signature file from several signature files representing different Java APIs in one Java runtime environment according to the JSR 68 rules.

[Top]

Usage Examples

This section contains simple examples that show how to start the Signature Test tool from the command line using the Setup and SignatureTest command line options. See System Requirements for initial setup.

Example 1: The following command line runs the Setup command to create a signature file named result.sig:

java -jar sigtestdev.jar Setup -classpath $JAVA_HOME/jre/lib/rt.jar -filename result.sig -package java.text

Example 2: The following command line runs the SignatureTest command to manually run a signature test:

java -jar sigtest.jar Test -static -filename result.sig -classpath $JAVA_HOME/jre/lib/rt.jar -package java.text

[Top]

Operating Modes

This section describes the Signature Test tool operating modes and report messages.

[Top]

Signature Test Compatibility Check Modes

• Binary compatibility check mode - Assures that any application runs with any compatible API without any linkage error.
• Source compatibility check mode - Verifies that any application that compiles without error with a source compatible API, also compiles without error with all other source compatible APIs.

• Mutual compatibility check mode - By checking for mutual compatibility of API member sets, the test verifies that classes and their members chosen for comparison are identical in both implementations of the API.
• Migration compatibility check mode - Verifies that any application that compiles without error with a source compatible API, also compiles without error with all other source compatible APIs.

[Top]

Command Run Modes

Two run modes are available during command execution, each associated with how the class descriptions are examined and retrieved, as follows:

• Reflection Mode. The default mode for the SignatureTest commands, it uses reflection to examine API classes and retrieve information about them. The reflection mode is of greatest advantage when the API to be analyzed has no external class files.
• Static Mode. Specified with the -static option, the tool parses only the class files listed in the -classpath command-line argument. You normally use static mode when a reflection mechanism is not supported, or in a security-constrained environment that disallows checking required attributes. Static mode is use full for testing specified classes in another runtime environment.. The Setup and SetupAndTest command run only in static mode.

[Top]

Signature Test Report Messages

Report messages can be either sorted by default, or unsorted. They contain the following types of information:

• Version of both the reference API and the API under test
• Total number of errors found
• Differences such as added or missing classes, superclasses, fields, or methods
• Fully qualified name of the enclosing class related to any missing or added description
• Two errors for any modified item, one for a missing item, and another for an added item
• Description of any incompatibility in the API implementation under test

See the SigTest Version 2.1 User's Guide for hands-on procedural examples of running the tool.

[Top]

Using the API Coverage Tool

API Coverage Tool is a command-line utility that executes in a Java platform application environment. It generates static API test coverage reports in either plain text or XML format based on the following items specified by input arguments:

• The test suite being tested for its coverage, represented by a set of test class files.
• A signature file that forms a text representation of the public members of an API that must be tested by the test suite. You can use the Signature Test tool Setup command to create the appropriate signature file for use by the API Coverage tool. See the SigTest 1.2 User's Guide for details.
• One or more exclude lists to make the coverage calculation more accurate by excluding the elements listed in the specified exclude list files.

[Top]

Known Bugs and Issues

The SignatureTest and Merge commands might incorrectly process throw lists related to generics.

[Top]

Copyright © 2009 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.The majority of the SigTest project is released under the GNU General Public License Version 2 (GPLv2)