This appendix contains the following two step-by-step examples that show you how to use the Signature Test tool:
Sample sources used in the examples, along with simple UNIX operating system shell and Windows batch scripts are provided in the examples/usersguide
directory. You can use these to help run the examples. The README file in that directory explains how to use them.
Note: The examples use UNIX operating system syntax. |
Caution: Code examples are an optional part of the SigTest distribution and are not required to use the SigTest tools. You can remove the example directory ($SIGTEST_HOME/examples) if you are concerned about security issues the examples might create. |
Example A-1 and Example A-2 show the two implementations of the test API used throughout these examples.
You can compare two implementations of an API in two ways:
Run the Setup
command to create a signature file for the first implementation and then run the SignatureTest
command to compare them. This is shown in the first part of this example: (UNKNOWN STEP NUMBER) .
Run the SetupAndTest
command. The command combines the Setup
and SignatureTest
commands. This is shown in the second part of this example: (UNKNOWN STEP NUMBER) .
Setup
and SignatureTest
CommandsThis example shows how to compare the following implementations of the test.java
API using the Setup
and SignatureTest
commands.
Make SigTest-directory/examples/usersguide
the current directory.
Compile the two implementation files.
SigTest tool works with class files. Use the following commands to compile the source files into class file:
% javac -d V1.0 V1.0/test.java % javac -d V2.0 V2.0/test.java
Set the CLASSPATH environment variable to include the path to sigtestdev.jar
.
% setenv CLASSPATH=../../lib/sigtestdev.jar
Set the JAVA_HOME environment variable to include the base directory of the Java platform runtime installation on your system.
% setenv JAVAHOME=java_runtime_path
Use the Setup
command to create a signature file for the V1.0 implementation.
Note that the “\” characters are used to break long lines. Type this as a single line at the command line.
% java com.sun.tdk.signaturetest.Setup \ -classpath V1.0:$JAVA_HOME/jre/lib/rt.jar \ -static \ -apiVersion V1.0 \ -package example \ -fileName test.sig
The Setup
command emits console output similar to the following:
Constant checking: on Found in total: 16260 classes Selected by -Package: 1 classes Written to sigfile: 2 classes STATUS:Passed.
Confirm that the contents of the signature file are correct by comparing it to the following file:
#Signature file v4.0 CLSS public example.test cons public test() meth public <%0 extends java.lang.Object> {%%0} get({%%0}) supr java.lang.Object CLSS public java.lang.Object cons public Object() meth protected java.lang.Object clone() throws java.lang.CloneNotSupportedException meth protected void finalize() throws java.lang.Throwable meth public boolean equals(java.lang.Object) meth public final java.lang.Class<?> getClass() meth public final void notify() meth public final void notifyAll() meth public final void wait() throws java.lang.InterruptedException meth public final void wait(long) throws java.lang.InterruptedException meth public final void wait(long,int) throws java.lang.InterruptedException meth public int hashCode() meth public java.lang.String toString()
Use the SignatureTest
command to compare the V2.0 API signature with the V1.0 signature file you created in Step 5.
% java com.sun.tdk.signaturetest.Setup \ -classpath V2.0:$JAVA_HOME/jre/lib/rt.jar \ -static \ -package example \ -fileName test.sig \ -out report.txt
The -out
option directs the command to write its results to report.txt
.
A message similar to the following is written to the console when the command terminates:
See log recorded to file report.txt for more details. STATUS:Failed.3 errors
Confirm that the contents of the report.txt
file are correct by comparing it to to the following file:
Note: There might be some minor differences because of system-specific information. |
SignatureTest report Tested version: Check mode: src [throws normalized] Constant checking: off Missing Methods --------------- example.test: method public <%0 extends java.lang.Object> {%%0} example.test.get({%%0}) Added Methods ------------- example.test: method public java.lang.String example.test.get(int) example.test: method public void example.test.put() STATUS:Failed.3 errors
SetupAndTest
CommandThe SetupAndTest
command combines the functionality of the Setup
and SignatureTest
commands into a single command.
Follow steps 1 - 4 in the previous example.
Use the following SetupAndTest
command to create a signature file.
% java $CLASSPATH com.sun.tdk.signaturetest.SetupAndTest \ -reference V1.0:$JAVA_HOME/jre/lib/rt.jar \ -test V2.0:$JAVA_HOME/jre/lib/rt.jar \ -package example
The SetupAndTest
command reports results similar to following example to standard output.
Invoke Setup ... Class path: "V1.0;C:\java\jdk1.5.0_06\/jre/lib/rt.jar" Constant checking: on Found in total: 12749 classes Selected by -Package: 1 classes Written to sigfile: 2 classes Invoke SignatureTest ... SignatureTest report Tested version: 2.0 Check mode: src [throws normalized] Constant checking: on Missing Methods --------------- example.test: method public <%0 extends java.lang.Object> {%%0} example.te st.get({%%0}) Added Methods ------------- example.test: method public java.lang.String example.test.get(int) example.test: method public void example.test.put() STATUS:Failed.3 errors
This example shows how to use the Merge
command to accomplish the following:
Compile three .java
files to produce .class
files.
Run the Setup
command on each .class
file to produce a signature file.
Use the Merge
command to combine the files.
These examples use the environment variables listed below:.
Environment Variable | Description |
---|---|
CLASSPATH | Must include the sigtestdev.jar file. For example:/sigtest-1.5/lib/sigtestdev.jar |
RT_JAR | The location of the runtime rt.jar file. For example: /opt/jdk1.5.0_09/jre/lib/rt.jar |
Set up the environment with the environment variable settings in the table above.
Create each of the files shown in the following examples. Create each in a different directory but with the same file name.
Create directories named 1
, 2
, and 3
. Add the appropriate file to each directory.
package x; public class A { public void abc() {} public void foo() {} } package x; public class A { public void abc() {} public void bar() {} } package x; public class A { public static void abc() {} }
Run these commands to compile each file into a separate x
subdirectory:
% javac -d 1 1/A.java % javac -d 2 2/A.java % javac -d 3 3/A.java
This creates the following class files:
Run the following three Setup
commands on each A.class
file to produce the three x
#.sig
files like the ones shown in following examples.
Command #1:
% java -cp 1:$CLASSPATH com.sun.tdk.signaturetest.Setup \ -static -classpath 1:$RT_JAR -package x -FileName x1.sig
The command generates the ./x1.sig
file like the one shown in the following example and produces a similar console message.
Class path: "1:/opt/jdk1.5.0_09/jre/lib/rt.jar" Constant checking: on Found in total: 13185 classes Selected by -Package: 1 classes Written to sigfile: 2 classes STATUS:Passed.
Command #2:
% java -cp 2:$CLASSPATH com.sun.tdk.signaturetest.Setup \ -static -classpath 2:$RT_JAR -package x -FileName x2.sig
The command generates the ./x2.sig
file shown in the following example and produces a console message similar to this indicating successful setup.
Class path: "2:/opt/jdk1.5.0_09/jre/lib/rt.jar" Constant checking: on Found in total: 13185 classes Selected by -Package: 1 classes Written to sigfile: 2 classes STATUS:Passed.
Command #3:
% java -cp 3:$CLASSPATH com.sun.tdk.signaturetest.Setup \ -static -classpath 3:$RT_JAR -package x -FileName x3.sig
The command generates the ./x3.sig
file shown in following example and produces a console message similar to this indicating successful setup.
Class path: "3:/opt/jdk1.5.0_09/jre/lib/rt.jar" Constant checking: on Found in total: 13185 classes Selected by -Package: 1 classes Written to sigfile: 2 classes STATUS:Passed.
Run the following command to merge x1.sig
and x2.sig
and produce the x1+x2.sig
file shown in the following example:
% java -cp $CLASSPATH com.sun.tdk.signaturetest.Merge -Files \ x1.sig:x2.sig -Write x1+x2.sig
The command generates a console message similar to the following message:
Warning: class java.lang.Throwable not found STATUS:Passed.
Run this command to merge x2.sig
and x3.sig
attempting to produce the x2+x3.sig
file:
% java -cp $CLASSPATH com.sun.tdk.signaturetest.Merge -Files x2.sig:x3.sig -Write x2+x3.sig
The command prints a message to the console similar to the following. it indicates a conflicting static
modifier, and no signature file is created:
x.A.abc : <static> modifier conflict STATUS:Error.Error
The conflict occurs because x2.sig
contains this method (see Example A-4):
meth public void x.A.abc() and x3.sig contains this method: meth public static void x.A.abc()
This section contains the files that are generated from the previous Merge
examples.
Example A-3 Contents of ./x1.sig
#Signature file v4.0 #Version CLSS public java.lang.Object cons public Object() meth protected java.lang.Object clone() throws java.lang.CloneNotSupportedException meth protected void finalize() throws java.lang.Throwable meth public boolean equals(java.lang.Object) meth public final java.lang.Class<?> getClass() meth public final void notify() meth public final void notifyAll() meth public final void wait() throws java.lang.InterruptedException meth public final void wait(long) throws java.lang.InterruptedException meth public final void wait(long,int) throws java.lang.InterruptedException meth public int hashCode() meth public java.lang.String toString() CLSS public x.A cons public A() meth public void abc() meth public void foo() supr java.lang.Object
Example A-4 Contents of ./x2.sig
#Signature file v4.0 #Version CLSS public java.lang.Object cons public Object() meth protected java.lang.Object clone() throws java.lang.CloneNotSupportedException meth protected void finalize() throws java.lang.Throwable meth public boolean equals(java.lang.Object) meth public final java.lang.Class<?> getClass() meth public final void notify() meth public final void notifyAll() meth public final void wait() throws java.lang.InterruptedException meth public final void wait(long) throws java.lang.InterruptedException meth public final void wait(long,int) throws java.lang.InterruptedException meth public int hashCode() meth public java.lang.String toString() CLSS public x.A cons public A() meth public void abc() meth public void bar() supr java.lang.Object
Example A-5 Contents of ./x3.sig
#Signature file v4.0 #Version CLSS public java.lang.Object cons public Object() meth protected java.lang.Object clone() throws java.lang.CloneNotSupportedException meth protected void finalize() throws java.lang.Throwable meth public boolean equals(java.lang.Object) meth public final java.lang.Class<?> getClass() meth public final void notify() meth public final void notifyAll() meth public final void wait() throws java.lang.InterruptedException meth public final void wait(long) throws java.lang.InterruptedException meth public final void wait(long,int) throws java.lang.InterruptedException meth public int hashCode() meth public java.lang.String toString() CLSS public x.A cons public A() meth public static void abc() supr java.lang.Object
Example A-6 Contents of ./x1+x2.sig
#Signature file v4.0 #Version CLSS public java.lang.Object cons public Object() meth protected java.lang.Object clone() throws java.lang.CloneNotSupportedException meth protected void finalize() throws java.lang.Throwable meth public boolean equals(java.lang.Object) meth public final java.lang.Class<?> getClass() meth public final void notify() meth public final void notifyAll() meth public final void wait() throws java.lang.InterruptedException meth public final void wait(long) throws java.lang.InterruptedException meth public final void wait(long,int) throws java.lang.InterruptedException meth public int hashCode() meth public java.lang.String toString() CLSS public x.A cons public A() meth public void abc() meth public void bar() meth public void foo() supr java.lang.Object