SigTest FAQ

Common questions about the SigTest project are answered here.

1. What are the licensing terms for SigTest?

   A: The SigTest project is licensed under the GNU Public License, version 2, with the Classpath Exception. See the licensing section of the download page for more information.

2. What is the classpath exception?

   A: The classpath exception was developed by the Free Software Foundation's GNU/Classpath Project (see http://www.gnu.org/software/classpath/license.html). It allows you to link an application available under any license to a library that is part of software licensed under GPL v2, without that application being subject to the GPL's requirement to be itself offered to the public under the GPL.

3. Why do you need the classpath exception?

   A: If SigTest was distributed under GPL v2, that application could be subject to the requirements of the GPL that all code that is shipped as part of a "work based on the [GPL] program" also be GPL licensed. Accordingly, a GPL license exception is needed that specifically excludes from this licensing requirement any application that links to the GPL implementation. The classpath exception accomplishes this.

4. What is the relationship between the SigTest project and the Mobile & Embedded community?

   A: The cqME project is the open source home for technologies used to test the Java Platform, Micro Edition (Java ME platform). The Mobile and Embedded community includes the cqME project. These ME-specific test technologies are built around the JT harness test harness, and the relationship between the JT Harness project and the cqME project is a close one. In fact, both projects share the same governance model and licensing requirements.

   Similar to the JT harness project, the SigTest project started out as a commercially released test technology, and is being released to the Java Tools open source community. The SigTest project also shares the same governance model and licensing requirements as the cqME project. The cqME project does not depend on the SigTest project as it does with the JT harness pr.

5. How can I submit or suggest changes to the SigTest project?

   A: We encourage you to contribute source code to the SigTest project. In accordance with the SigTest project governance process, you can submit code to the project leader either as a user, a developer, or as a committer. If your code is accepted to be integrated into the source tree, you will be asked to sign a Contributor's Agreement similar to what Apache Software Foundation requires. For more information about the governance process and the various roles for members in the community, please review Mobile & Embedded Community Governance.

6. What documentation is available for developers?

   A: The layout of the SigTest repository is described in SigTest Repository Structure.

   • The SigTest Developer's Guide describes how the source code is organized and provides important information for developers who want to modify the code.
   • The SigTest Source Code Description describes how the SigTest source code is organized.
   • The SigTest Build Instructions describes how to build the SigTest tool.
7. Can I change the project documentation?

   A: The SigTest Tool User's Guide hosted on java.sun.com is provided solely for your convenience and is not being release under the GPL version 2 as part of this project. These documents are part of the SigTest commercial product and cannot be modified.

1. What is the SignatureTest tool?

   A: The SignatureTest tool takes a given API and a corresponding reference API, and checks for mutual binary and source code compatibility. The SignatureTest tool can also check migration compatibility to determine application compatibility across different versions of the same API.

   For mutual compatibility checks, the SignatureTest tool operates on the following principles:

   • A signature test for a Java technology implementation checks that all the necessary API members are present and that no extra members illegally extend the API.
   • The reference of comparison in a signature test is a signature file, which is a text representation of the API signatures required by the related technology specification.
   • A user runs the signature test, either manually or under the control of a test harness, to compare the reference signature file to the API implementation under test.
   • The signature test algorithm compares the API implementation under test with a reference signature file to check for either mutual binary compatibility or source compatibility by verifying the equality of API member sets.

2. What is the APICoverage tool?

   A: APICoverage Tool is a utility that calculates the estimated percentage of code accessed by tests. It can be used to identify which parts of your Java language program or API are lacking test coverage by determining which portions of the API that cannot be executed. APICoverage tool is a static analyzer, so unlike dynamic coverage tools (like EMMA or Cobertura) APICoverage tool:

   • Does not require test execution
   • Generates result reports quicky
   • Does not affect test execution time
   • Is simple to configure
   • Is not subject to benchmark execution paths

3. What kind of Java platform programs can the SigTest tools be used with?

   A: Any Java platform API set, including native code. The interfaces to native code can be analyzed.

4. What is "mutual binary" compatibility mode?

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

5. What is "source compatibility" mode?

   A: 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 with any other binary compatible API.

   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.

   This is a stricter check than the mutual binary compatibility check and the tool performs it by default.

6. What is migration compatibility? How is it different from 2-way source/binary compatibility?

   A: Migration compatibility (or 1-way backwards compatibility) determines whether an application that uses an API can safely migrate to a newer version of that API (typically, a superset of the same functionality). This is different than mutual (2-way) compatibility which requires complete equality between the two API sets. Mutual compatibility checking is typically useful for compatibility testing or certification purposes, migration compatibility is useful for application testing.

7. Should I use reflection or static mode?

   A: The Java programming language reflection API has many limitations, thus SignatureTest tool cannot detect extra classes using reflection. Constant checking and annotation analysis are also limited in reflection mode. Consequently, static mode checks are much stronger and are generally preferable to reflection mode checks.

   In some cases only reflection mode can be used -- for example, in an ME device with a ROMized Java runtime system where you do not have access to the class file.

8. How do I use the SigTest tools in a test suite?

   A: Test suites for any Java platform/API/application (such as TCKs for Oracle's own Java Development Kit (JDK)) typically provide a set of behavioral tests, as a component. Similarly, API tests can be considered as a testing component required to ensure backwards source level (for compilation) and binary level (for runtime linking) compatibility testing. SignatureTest tool can be thought of as a single, complex predicate, determining the backwards compatibility.

9. How do I use SignatureTest tool in an application?

   A: Products and applications (as well as platforms) may have an architecture with some API or other arbitrary programming interface layers within a program that needs to maintain backwards compatibility for the product to function (whether that API is exposed or not). SignatureTest tool can be used for unit testing a product to determine this compatibility. This can be useful for determining product instabilities early in the software lifecycle.

   Applications can also use SignatureTest tool in "migration compatibility" mode, to determine how compatible the application is with a different/newer version of an API that the application depends on.

10. How do I use SigTest to test an ME device?

    A: The signature test has a requirement for the Java Platform, Standard Edition (Java SE platform) runtime environment version 1.4 or later (see "System Requirements"). This requirement might prevent using the tool on limited or nonstandard environments such as some Java Platform, MicroEdition (Java ME platform) or Java Platform, Enterprise Edition (Java EE platform) configurations.

    To overcome this, the tool provides support of custom signature loaders that can be implemented as a plug-in to gather signatures from a runtime environment where the signature test command cannot be run directly. An example of this is a light- weight remote JT harness agent with the signature loader running on a remote Connected Device Configuration (CDC) compatible device with low resources and communication capabilities.

11. Why do no inherited members show up in the signatures associated with a given class?

    A: SignatureTest tool always takes into account inherited members because there are no differences between a given class's inherited members and its own members.

    Prior to SigTest 1.5, SignatureTest tool wrote inherited members in any class (in other words any class in a signature file contained at least java.lang.Object members). Since SigTest 1.5, SignatureTest tool only writes the members of a given class, but a signature file must be "transitively closed". This means for a set of signature files, all superclasses must be included. During a SignatureTest test run, SignatureTest tool merges superclass members and checks them.

12. My API is a superset of a Java API. Is there a way to filter out warnings or errors that do not originate from my API?

    A: SignatureTest tool is built in an extensible way, and users are allowed to write plug-ins to filter or process member signatures as they pass through the difference engine. Though SignatureTest tool does not provide any native filtering options, it is relatively easy to create special-purpose filters for situations like this.

    Some caution should be applied for filtering inherited members. Java (being an object-oriented programming language) doesn't distinguish inherited superclasses class members and class members declared in the class itself. If you filter out inherited members you can't guarantee binary or source code compatibility

13. Is the ordering of items on the command-line important??

    A: No, SigTest tools command-line options are order-independent.

14. Why is the @Deprecated annotation tracked by SignatureTest tool, but its ancestor the @deprecated Javadoc tag is not?

    A: The @Deprecated annotation and @deprecated Javadoc comment are not the same. The most important difference to SignatureTest tool is that the @Deprecated annotation is specified by the Java Language Specification, but the Javadoc tag is not.

    According to the following section of Oracle'sguide How and When To Deprecate APIs the @Deprecated annotation is mandatory and @deprecated Javadoc tag is optional:

    How to Deprecate

    Starting with Java SE 5.0, you deprecate a class, method, or field by using the @Deprecated annotation. Additionally, you can use the @deprecated Javadoc tag tell developers what to use instead.

    Using the annotation causes the Java language compiler to generate warnings when the deprecated class, method, or field is used. The compiler suppresses deprecation warnings if a deprecated compilation unit uses a deprecated class, method, or field. This enables you to build legacy APIs without generating warnings.

    You are strongly encouraged to use the Javadoc @deprecated tag with appropriate comments explaining how to use the new API. This ensures developers will have a workable migration path from the old API to the new API. For more information, see Using the @deprecated Javadoc Tag.

    Note: The Java Language Specification requires compilers to issue warnings when classes, methods, or fields marked with the @Deprecated annotation are used. Compilers are not required by the Java Language Specification to issue warnings when classes, methods, or fields marked with the @deprecated Javadoc tag are accessed, although the Oracle compilers currently do so. However, there is no guarantee that the Oracle compiler will always issue such warnings.

    7.1

15. Why are some annotations (such as @Deprecated) tracked by SignatureTest tool, and others are not?

    A: SignatureTest tool (version 1.5) only tracks annotations whose types are annotated with @Documented

    The following section of the Java Language Specification describes java.lang.annotation.Documented:

    @Documented
    @Retention(value=RUNTIME)
    @Target(value=ANNOTATION_TYPE) public @interface Documented
    

    Indicates that annotations with a type are to be documented by Javadoc and similar tools by default. This type should be used to annotate the declarations of types whose annotations affect the use of annotated elements by their clients. If a type declaration is annotated with Documented, its annotations become part of the public API of the annotated elements.

    Therefore, any annotation type annotated with the @Documented annotation is a "part of the public API". Because @Deprecated is documented, SignatureTest tool tracks it like any other part of a public API.

    SignatureTest tool writes to a signature file and checks annotations that have either RUNTIME or CLASS retention. Since annotations with CLASS retention cannot be retrieved using the reflection API, SignatureTest tool ignores such annotations in reflection test mode - but does check them in static test mode.

16. In the recorded signature files, I see some fields flagged with "hfds". What does the "hfds" flag mean?

    A: "hfds" is a list of names of non-API (with private and default access) fields and static inner classes. This is an internal implementation and SignatureTest tool does not track them. This flag is required due to member hiding. Any non-API field or class can hide an API element from a superclass with the same name. The following example demonstrates this.

    // this is an API class
    public class super {  
          public final static double PI = 3.14d;  // this is an API field
    }
    
    public class sub extends super {
       private String PI="Pi... pi... pi...";   // this PI hides superclass' API PI
    } 
    

    Adding a non-API field can break compatibility -- but only obliquely. The example above demonstrates this. Assume the existing client contains the code:

    System.out.println("PI=" + sub.PI ); 
    

    adding the private sub.PI breaks binary and source code compatibility in this case. SignatureTest tool builds a class hierarchy, calculates API hiding (like the JVM does), and reports an error.

17. How do I use the -nonclosedfile option?

    A: When using the -nonclosedfile option during the recording (Setup) of a signature file, the recording process can appear to work correctly. However, upon playback you might see a failure with the following message:

    The following classes are required, but missing in the signature files:   
            java.lang.Object, java.lang.Exception 
                           STATUS: Error.   Required classes not found!
    

    SignatureTest tool must have a transitively closed set of classes. Each particular signature file cannot be closed for the case where merge is used. For example:

    test -files nonclosedfile1.sig:nonclosedfile2.sig:nonclosedfile3.sig ...
    

    This works if the "nonclosedfile1.sig + nonclosedfile2.sig + nonclosedfile3.sig" construct is a transitively closed set of checked classes. The -nonclosedfile option to the SignatureTest tool setup command allows you to generate these files.