NAME

       japicompat - Test Java APIs for binary backwards compatibility.

SYNOPSIS

       japicompat [-svqhtjw4] [-o outfile] [-i ignorefiles] <original_api> <api_to_check>

DESCRIPTION

       japicompat is part of japitools, designed to test for compatibility between Java APIs.

       They  were  originally  designed  for  testing  free  implementations  of  Java itself for
       compatibility with Sun's JDK, but they can also be used for testing backward compatibility
       between versions of any API.

       The  tools are japize and japicompat. Japize is a Java program which emits a listing of an
       API in a machine-readable format. Japicompat then takes two  such  listings  and  compares
       them for binary compatibility, as defined by Sun in the Java Language Specification.

OPTIONS

       -s     disable additional binary compatibility checks (only do checks defined by the JLS).

       -v     enable checks for minor compatibility problems.

              SerialVersionUID checking: japicompat reports a minor error if a Serializable class
              has a different SerialVersionUID between the two releases.

              Deprecation checking: japicompat reports a minor error if a  class  or  member  was
              deprecated in the original API but is not deprecated in the API being checked.

       -q     disables progress reports.

       -h     generates  output  in  HTML  format. The HTML files produced depend on the japi.css
              file to get attractive presentation.

       -t     generates output in text format. This is the default.

       -j     generates output in raw machine  readable  form.  The  format  produced  is  called
              "japio"  format,  and by convention should be saved with a ".japio" file extension.
              The standalone japiotext and japiohtml utilities can be used to convert this format
              into  html or text (actually, japicompat calls japiotext or japiohtml internally if
              the -h or -t flags are used). Japio files can also be used  with  the  -i  flag  to
              support ignoring errors caused by incompatibilities between JDK versions.

       -w     disable  warnings  for  running against old buggy japi files. By default japicompat
              will produce warnings if run against  japi  files  originally  generated  by  older
              versions of japitools that had known bugs that japifix cannot eliminate.

       -4     use 1.4-compatible mode. This works as long as the APIs to compare does not contain
              1.5-only items.

       -o <outfile>
              Send the output to <outfile> instead of stdout. The format of this file depends  on
              the -h, -t and -j flags.

       -i <ignorefiles>
              Suppose  you  are  attempting  to  implement  the  Java API. You have (pretty much)
              completed coverage of the early JDK versions (1.0 and  1.1)  but  still  have  some
              distance  to  achieve  full coverage of 1.4 (this is an accurate description of all
              Free Software Java implementations at the time of  writing).  Using  japicompat  to
              compare your implementation with JDK 1.4 gives accurate results, but you might also
              want to show your coverage of the earlier versions.

              Unfortunately Sun has not followed their own binary compatibility rules between JDK
              releases, let alone the expanded rules that japicompat tests for. So when you run a
              comparison between JDK 1.1 and your implementation, you  will  get  spurious  error
              reports when you're compatible with 1.4 but not 1.1.

              Obviously  what  you  really  want  is  to  ignore errors like this, and japicompat
              provides a way to do so. First, run a comparison between 1.1 and 1.4 using  the  -j
              switch.  Then  run  the comparison between 1.1 and your implementation, passing the
              "-i" option with the output of the previous run. For example:

              $ japicompat -jo ignore-11-14.japio jdk11.japi.gz jdk14.japi.gz
              $   japicompat   -ho   jdk11-myimpl.html   -i   ignore-11-14.japio    jdk11.japi.gz
              myimpl.japi.gz

              You can also get the same effect by running:

              $ japicompat -ho jdk11-myimpl.html -i jdk14.japi.gz jdk11.japi.gz myimpl.japi.gz

              This  is obviously simpler and quicker to type, but requires the comparison between
              jdk11 and jdk14 to be run every single time. Making the japio file manually  allows
              for  it  to  be saved and used again the next time, which lets japicompat run about
              twice as fast.

        <original_api> <api_to_check>
              The japi files corresponding to the APIs to be compared.

              japicompat specifically tests that the  second  argument  is  backwardly-compatible
              with  the  first.  Therefore,  a perfect implementation of JDK 1.1 would produce no
              errors regardless of the order of the arguments, but a  perfect  implementation  of
              JDK1.1 plus parts of JDK1.2 should be tested as follows:

              $ japicompat jdk11.japi.gz myimpl.japi.gz
              $ japicompat myimpl.japi.gz jdk12.japi.gz

              It  is  probably impossible to make an implementation that passes both these tests,
              since Sun's own JDK1.2 produces numerous errors when tested against JDK1.1. See the
              discussion of the -i option above for a way to cope with this situation.

              Either  compressed  (.japi.gz)  or  uncompressed  (.japi)  files  can  be passed to
              japicompat: The file extension is used to determine whether or not  to  pipe  input
              through gzip or not.

SEE ALSO

       japize(1) Produce a listing of an API in a machine-readable format.
       japilist(1) List the contents of japi files.
       japiohtml(1) Convert japicompat output to pretty html format.
       japiotext(1) Convert japicompat output to readable plain text format.

                                         October 6, 2005                            JAPICOMPAT(1)