Related projects

There are other tools that do something like this:

• SignatureTool from Motorola Gatling project
• Test compatibility between Java APIs Japitools
• Jardiff takes two jar files and outputs all the public API changes as xml, html or plain text
• SUN TCK Tools Signature Test tool

Creation of API descriptor XML from command line

java -cp jour-instrument-2.0.3.jar;javassist.jar net.sf.jour.SignatureGenerator \
   --src myclasses.jar --packages com.api;com.ext --dst api-signature.xml

All command line options:

• --src implementation : The source JAR or Directory for which the Signature File should be generated. (required)
• --dst api-signature.xml : Generated Signature XML report.
• --jars jar-one;jar-two;...;jar-n : The supporting Jars for the Source Jar.
• --systempath : Appends the system search path to the end of the search path.
• --packages org.api2;org.api2 : List package names to be included in signature
• --level public|protected|package|private: Specifies the access level for classes and members to export. Default value is protected.

N.B javassist.jar should be in classpath when running jour.

Example of generated signature XML.

See Schema for signature.xml http://jour.sourceforge.net/2.0/api-signature.xsd and XML Schema Documentation.

<?xml version="1.0" encoding="UTF-8"?>
<signature>

  <interface name="uut.signature.AnInerface" modifiers="public">
    <method name="getVoid" return="void" modifiers="public abstract"/>
    <method name="getInt" return="int" modifiers="public abstract"/>
  </interface>

  <class name="uut.signature.AClass" modifiers="public">
    <implements>
      <interface name="uut.signature.AnInerface"/>
    </implements>
    <constructor modifiers="public"/>
    <constructor>
      <parameter type="int[]"/>
      <exception name="java.lang.Error"/>
    </constructor>
    <method name="getInt" return="int" modifiers="public"/>
    <method name="getProt" return="void" modifiers="protected"/>
    <method name="getVoid" return="void" modifiers="public"/>
    <field name="constData" type="int" modifiers="public static final" constant-value="10"/>
    <field name="data" type="short" modifiers="static"/>
  </class>

  <class name="uut.signature.AChildClass" modifiers="public" extends="uut.signature.AClass">
    <constructor modifiers="protected"/>
    <method name="run" return="void" modifiers="public"/>
    <method name="run" return="java.lang.Long" modifiers="public">
      <exception name="java.lang.Error"/>
      <parameter type="byte"/>
    </method>
    <field name="constData" type="int" modifiers="public static final" constant-value="10"/>
    <field name="data" type="short" modifiers="static"/>
  </class>

</signature>

Verification of API descriptor XML from command line

java -cp jour-instrument-2.0.3.jar net.sf.jour.SignatureVerify --src myclasses-v2.jar --signature api-signature.xml

All command line options:

• --src implementation : The source JAR or Directory for which the Signature File should be generated. (required)
• --signature api-signature.xml : Base Signature XML. (required)
• --packages org.api2;org.api2 : List package names to compare. Default to all classes in Signature File.
• --jars jar-one;jar-two;...;jar-n : The supporting Jars for the Source Jar.
• --systempath : Appends the system search path to the end of the search path. Defaults to false
• --allowAPIextension [false]|true
• --allowThrowsLess [false]|true
• --level public|protected|package|private: Specifies the access level for classes and members to compare. Default value is protected.

N.B javassist.jar should be in classpath when running jour.

Verification of API descriptor XML from JUnit tests

Extend your JUnit test from net.sf.jour.signature.SignatureTestCase and implement abstract methods

package javax.obex;

import net.sf.jour.signature.SignatureTestCase;

public class JSR82APIObexDeclarationsTest extends SignatureTestCase {

    public String getAPIPath() {
        return getClassPath(SessionNotifier.class);
    }

    public String getSignatureXMLPath() {
        return "jsr82-obex-signature.xml";
    }

}

Alternatively you can use class net.sf.jour.signature.APICompare

Creation of classes base on API descriptor XML from command line

java -cp jour-instrument-2.0.3.jar net.sf.jour.SignatureExport --signature api-signature.xml --dst ./api-classes

All command line options:

• --signature api-signature.xml : Base Signature XML. (required)
• --dst outputClassesDir: Directory to write created classes to. (required)
• --packages org.api2;org.api2 : List package names to export. Default to all classes in Signature File.
• --jars jar-one;jar-two;...;jar-n : The supporting Jars for the Source Jar.
• --systempath : Appends the system search path to the end of the search path.
• --stubException ExceptionClassName: Use throw new Exception() for method implementations
• --stubExceptionMessage ExceptionMessage: Use throw new Exception("ExceptionMessage") for method implementations
• --classVersion 1.1|1.3|1.5|1.4|1.6 : Java classes version. Defaults to 1.5 on when running by java 5 and 1.3 on java 1.4
• --level public|protected|package|private: Specifies the access level for classes and members to export. Default value is protected.