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.
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.
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.
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.
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.
A: The layout of the SigTest repository is described in SigTest Repository Structure.
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.
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: 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:
A: Any Java platform API set, including native code. The interfaces to native code can be analyzed.
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.
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.
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.
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.
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.
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.
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.
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.
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
A: No, SigTest tools command-line options are order-independent.
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 DeprecateStarting 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
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 DocumentedIndicates 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.
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.
-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.