8 Using the API Check Tool

API Check tool behaves much the same as Signature Test tool and uses the same options and signature files. See Chapter 4 for a description of the options. The input signature file is generated by the Signature Test tool Setup command using the -NonClosedFile option. Neither the CLASSPATH variable used for reflection mode, nor classes listed with -classpath option for static mode can contain base classes. See "CLASSPATH and -classpath Settings" for more information.

8.1 API Check Tool Verification Scope

API Check tool verifies classes in signature files that are also covered by packages defined using the -package option. If the specified signature file is generated using the -NonClosedFile option, all superclasses and superinterfaces outside this scope are not checked.

As an example, consider a signature file that contains java.util classes. Use the following command to create the signature file:

java -jar sigtestdev.jar setup -classpath $JAVA_HOME/jre/lib/rt.jar 
    -filename java-util.sig -nonclosedfile -package java.util

Use the following command to verify the java.util.ArrayList class using the signature file created in the previous command:

java -jar apicheck.jar -static -classpath $JAVA_HOME/jre/lib/rt.jar -filename
    java-util.sig -package java.util.ArrayList

Because java.util.ArrayList is specified as the scope for checking, it is he only class verified. ArrayList has a branching class and interface hierarchy that belongs to the java.lang, java.util and java.io packages as shown in Figure 8-1. Because the input signature file only contains classes from the java.util package, only the ArrayList class superclasses and superinterfaces from java.util are analyzed and their members are checked as ArrayList class inherited members.

Figure 8-1 java.util Classes

Description of "Figure 8-1 java.util Classes"

Consider a similar signature file that contains java.lang classes. In a similar check for the RuntimePermission class, the RuntimePermission hierarchy starts in the java.lang.Object class, departs the java.lang package to java.security and finally returns to the java.lang package:

java.lang.Object
     extended by java.security.Permission
         extended by java.security.BasicPermission
             extended by java.lang.RuntimePermission

API Check tool cannot verify any of the RuntimePermission class hierarchy because its direct superclass is outside the scope. In this case, even though java.lang.Object is in scope no inherited members are taken into account, and only members declared in RuntimePermission itself are analyzed.

8.2 Running API Check Tool

API Check tool command synopsis:

% java -jar apicheck.jar [options]
or
% java com.sun.tdk.apicheck.Main [options]

The rules described in "Case Sensitivity of Option Arguments" apply.

The command options are the same as those for Signature Test Tool and are listed in Table 4-5.

The settings for the CLASSPATH environment variable and the -classpath option are the same as those for Signature Test Tool and are listed in Table 4-1.