A Signature Test Tool Quick Start Examples

This appendix contains the following two step-by-step examples that show you how to use the Signature Test tool:

Example 1: Compare Two Different Implementations of the Same API
Example 2: Merge Two Signature Files

A.1 Example Programs

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.

Example A-1 Version 1.0 of test.java

package example;
public class test {
    public <T> T get (T x) {
        return x;
    }
}

Example A-2 Version 2.0 of test.java

package example;

public class test {

    public String get (int x) {
        return "";
    }
  
    public void put () {
    }
}

A.2 Example 1: Compare Two Different Implementations of the Same API

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) .

A.2.1 Using the `Setup` and `SignatureTest` Commands

This 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

A.2.2 Using the `SetupAndTest` Command

The 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

A.3 Example 2: Merge Two Signature Files

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.

A.3.1 Running Merge Example

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:
1. ./1/x/A.class
2. ./2/x/A.class
3. ./3/x/A.class

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()
```

A.3.2 Example Result Files

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