com.sun.tdk.signaturetest
Class SignatureTest

java.lang.Object
  extended by com.sun.tdk.signaturetest.Result
      extended by com.sun.tdk.signaturetest.SigTest
          extended by com.sun.tdk.signaturetest.SignatureTest
All Implemented Interfaces:
Log, PluginAPI

public class SignatureTest
extends SigTest

SignatureTest is the main class of signature test.

The main purpose of signature test is to ensure that programs written in Java using the class libraries of one Java implementation of a specific API version (ie. 1.1, 1.2, etc.) can rely on having the same and only the same Java APIs available in other implementations of the same API version. This is a more stringent requirement than simple binary compatibility as defined in the Java Language Specification, chapter 13. It is in essence a two-way binary compatibility requirement. Therefore, third party implementations of the Java API library must retain binary compatibility with the JavaSoft API. Also, the JavaSoft API implementation must retain binary compatibility with the Java API library under test.

SignatureTest implements the standard JavaTest 3.0 com.sun.javatest.Test interface and uses the standard main() method implementation. SignatureTest allows to check only specified by command line the package or packages.

SignatureTest tracks the following aspects of binary compatibility:

SignatureTest tracks all of the super classes and all of the super interfaces of each public class and public interface within required packages.

SignatureTest tracks all of the public and protected class members for each public class and interface.

For each constructor or method tracked, SignatureTest tracks all modifiers except native and synchronized. It also tracks other attributes for constructors and methods: method name, argument types and order, return type, and the declared throwables.

For each field tracked, SignatureTest tracks all modifiers except transient. It also tracks these other attributes for fields: data type, and field name.

Usage: java com.sun.tdk.signaturetest.SignatureTest <options>

where <options> includes:

-TestURL <URL>
URL of signature file.

-FileName <n>
Path name of signature file name.

-Package <package>
Name of the package to be tested. It is implied, that all subpackages the specified package should also be tested. Such option should be included for each package (but subpackages), which is required to be tested.

-PackageWithoutSubpackages <package>
Name of the package, which is to be traced itself excluding its subpackages. Such option should be included for each package required to be traced excluding subpackages.

-Exclude <package_or_class_name>
Name of the package or class, which is not required to be traced, despite of it is implied by -Package or by -PackageWithoutSubpackages options. If the specified parameter names a package, all its subpackages are implied to be also excluded. Such option should be included for each package (but subpackages) or class, which is not required to be traced.

-FormatPlain
Do not reorder errors report.

-AllPublic
Trace public nested classes, which are member of classes having default scope.

-Classpath <path>
Path to packages being tested. If there are several directories and/or zip-files containing the required packages, all of them should be specified here. Use java.io.File.pathSeparator to separate directory and/or zip-file names in the specified path. Only classes from <path> will be used for tracking adding classes.

-static
Run signature test in static mode.

-Version <version>
Specify API version. If this parameter is not specified, API version is assumed to be that reported by getProperty("java.version").

-CheckValue
Check values of primitive constant. This option can be used in static mode only.

-Verbose
Enable error diagnostic for inherited class members.


Nested Class Summary
 
Nested classes/interfaces inherited from interface com.sun.tdk.signaturetest.plugin.PluginAPI
PluginAPI.InjectionPoint
 
Field Summary
static java.lang.String BINARY_MODE
           
static java.lang.String CHECKVALUE_OPTION
           
static java.lang.String ENABLESUPERSET_OPTION
           
protected  Exclude exclude
           
static java.lang.String FILES_OPTION
           
static java.lang.String MODE_OPTION
           
static java.lang.String NOCHECKVALUE_OPTION
           
static java.lang.String NOMERGE_OPTION
           
static java.lang.String UPDATE_FILE_OPTION
           
static java.lang.String WRITE_OPTION
           
 
Fields inherited from class com.sun.tdk.signaturetest.SigTest
ALLPUBLIC_OPTION, apiVersion, APIVERSION_OPTION, BACKWARD_ALT_OPTION, BACKWARD_OPTION, cacheSize, CLASSCACHESIZE_OPTION, classpath, CLASSPATH_OPTION, classpathStr, debug, DEBUG_OPTION, DefaultCacheSize, ERRORALL_OPTION, errorManager, errorMessages, errors, EXCLUDE_OPTION, excludedPackages, EXTENSIBLE_INTERFACES_OPTION, FILENAME_OPTION, FORMATHUMAN_ALT_OPTION, FORMATHUMAN_OPTION, FORMATPLAIN_OPTION, HELP_OPTION, isConstantValuesTracked, isStatic, isTigerFeaturesTracked, normalizer, OUT_OPTION, PACKAGE_OPTION, packages, PLUGIN_OPTION, pluginClass, purePackages, QUESTIONMARK, reportWarningAsError, sigFileName, sigFileNameList, STATIC_OPTION, testableHierarchy, testableMCBuilder, testURL, TESTURL_OPTION, trackMode, VERBOSE_OPTION, VERSION_OPTION, WITHOUTSUBPACKAGES_OPTION, XNOTIGER_OPTION, XVERBOSE_OPTION
 
Fields inherited from class com.sun.tdk.signaturetest.Result
NO_EXIT
 
Fields inherited from interface com.sun.tdk.signaturetest.plugin.PluginAPI
AFTER_BUILD_MEMBERS, AFTER_CLASS_CORRECTOR, BEFORE_TEST, CLASS_CORRECTOR, IS_CLASS_ACCESSIBLE, ON_CLASS_LOAD
 
Constructor Summary
SignatureTest()
           
 
Method Summary
protected  boolean allowMissingSuperclasses()
           
 void decodeOptions(java.lang.String optionName, java.lang.String[] args)
           
protected  java.lang.String getComponentName()
           
protected static SignatureTest getInstance()
           
protected  boolean isAPICheckMode()
           
static void main(java.lang.String[] args)
          Run the test using command-line; return status via numeric exit code.
protected  boolean normalizeReq()
           
 void run(java.lang.String[] args, java.io.PrintWriter log, java.io.PrintWriter ref)
          This is the gate to run the test with the JavaTest application.
protected  void setupLoaders(ClassDescriptionLoader loader, ClassDescriptionLoader second)
           
protected  void usage()
          Prints help text.
 boolean useErasurator()
           
 
Methods inherited from class com.sun.tdk.signaturetest.SigTest
addFormat, addInherited, decodeCommonOptions, getClassDescrLoader, getContext, getFileManager, getFilter, getLog, getNumErrors, getNumWarnings, getTransformer, initErrors, isPackageMember, load, loadPlugin, normalizeArrayParaemeters, printErrors, removeUndocumentedAnnotations, setClassDescrLoader, setFilter, setFormat, setLog, setTransformer, setupProblem, storeError, storeWarning
 
Methods inherited from class com.sun.tdk.signaturetest.Result
error, exit, failed, getReason, isPassed, notrun, passed, passed, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

CHECKVALUE_OPTION

public static final java.lang.String CHECKVALUE_OPTION
See Also:
Constant Field Values

NOCHECKVALUE_OPTION

public static final java.lang.String NOCHECKVALUE_OPTION
See Also:
Constant Field Values

MODE_OPTION

public static final java.lang.String MODE_OPTION
See Also:
Constant Field Values

ENABLESUPERSET_OPTION

public static final java.lang.String ENABLESUPERSET_OPTION
See Also:
Constant Field Values

FILES_OPTION

public static final java.lang.String FILES_OPTION
See Also:
Constant Field Values

NOMERGE_OPTION

public static final java.lang.String NOMERGE_OPTION
See Also:
Constant Field Values

WRITE_OPTION

public static final java.lang.String WRITE_OPTION
See Also:
Constant Field Values

UPDATE_FILE_OPTION

public static final java.lang.String UPDATE_FILE_OPTION
See Also:
Constant Field Values

BINARY_MODE

public static final java.lang.String BINARY_MODE
See Also:
Constant Field Values

exclude

protected Exclude exclude
Constructor Detail

SignatureTest

public SignatureTest()
Method Detail

main

public static void main(java.lang.String[] args)
Run the test using command-line; return status via numeric exit code.

See Also:
run(String[],PrintWriter,PrintWriter)

getInstance

protected static SignatureTest getInstance()

run

public void run(java.lang.String[] args,
                java.io.PrintWriter log,
                java.io.PrintWriter ref)
This is the gate to run the test with the JavaTest application.

Parameters:
log - This log-file is used for error messages.
ref - This reference-file is ignored here.
See Also:
main(String[])

decodeOptions

public void decodeOptions(java.lang.String optionName,
                          java.lang.String[] args)
                   throws CommandLineParserException
Throws:
CommandLineParserException

usage

protected void usage()
Prints help text.

Specified by:
usage in class SigTest

getComponentName

protected java.lang.String getComponentName()
Specified by:
getComponentName in class SigTest

useErasurator

public boolean useErasurator()
Overrides:
useErasurator in class SigTest

allowMissingSuperclasses

protected boolean allowMissingSuperclasses()

normalizeReq

protected boolean normalizeReq()

isAPICheckMode

protected boolean isAPICheckMode()

setupLoaders

protected void setupLoaders(ClassDescriptionLoader loader,
                            ClassDescriptionLoader second)