Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.sun.tdk.signaturetest
Class SignatureTest

    java.lang.Object
      com.sun.tdk.signaturetest.Result
          com.sun.tdk.signaturetest.SigTest
              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:

- Fully qualified name of class or interface
- Class modifiers abstract and final
- Superclasses and superinterfaces
- Public and protected class members

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`
`protected PackageGroup` | `secure`
`static java.lang.String` | `SECURE_PACKAGES_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, errorMessages, errors, EXCLUDE_OPTION, excludedPackages, EXTENSIBLE_INTERFACES_OPTION, FILENAME_OPTION, FORMATHUMAN_ALT_OPTION, FORMATHUMAN_OPTION, FORMATPLAIN_OPTION, HELP_OPTION, isStatic, isTigerFeaturesTracked, isVerbose, normalizer, NOWARN, nowarnings, 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_MESSAGE_SORT, BEFORE_TEST, BEFORE_WRITE, 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()`
`protected boolean` | `prepareCheck(MultipleFileReader in, java.io.PrintWriter log)`
`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()`
`protected boolean` | `verifyClass(ClassDescription required, boolean supportNSC)` Check if the `required` class described in signature file also presents (and is public or protected) in the API being tested.
`protected void` | `verifyClass(ClassDescription required, ClassDescription found)` Compare descriptions of the `required` and `found` classes.

Methods inherited from class com.sun.tdk.signaturetest.SigTest
`addFormat, addInherited, decodeCommonOptions, getClassDescrLoader, getContext, getErrorManager, getFileManager, getFilter, getLog, getNumErrors, getNumWarnings, getTransformer, initErrors, isConstantValuesTracked, isPackageMember, load, loadPlugin, normalizeArrayParaemeters, printErrors, removeUndocumentedAnnotations, setClassDescrLoader, setConstantValuesTracked, setErrorManager, setFilter, setFormat, setLog, setMessageTransformer, setTransformer, setupProblem, storeError, storeWarning, unpackContainerAnnotations`

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

### SECURE_PACKAGES_OPTION

    public static final java.lang.String SECURE_PACKAGES_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

### secure

    protected PackageGroup secure

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)

### verifyClass

    protected boolean verifyClass(ClassDescription required,
                                  boolean supportNSC)

  Check if the `required` class described in signature file also presents (and is public or protected) in the API being tested. If this method fails to findByName that class in the API being tested, it appends corresponding message to the errors `log`.

  Returns:
    `Status.failed("...")` if security exception occurred; or `Status.passed("")` otherwise.
  See Also:
    `SigTest.log`

### verifyClass

    protected void verifyClass(ClassDescription required,
                               ClassDescription found)

  Compare descriptions of the `required` and `found` classes. It is assumed, that description for the `required` class is read from signature file, and the `found` description belongs to that API being tested. If the descriptions compared are not equal to each other (class names differ, or there are different sets of public members in them), this method appends corresponding error messages to the `log`-file. Note, that equality of class or member names may do not imply that they have the same `static` and `protected` attributes, and `throws` clause, if the chosen `converter` enables weaker equivalence.

  See Also:
    `SigTest.log`

### prepareCheck

    protected boolean prepareCheck(MultipleFileReader in,
                                   java.io.PrintWriter log)

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD