Man Linux: Main Page and Category List


       japicompat - Test Java APIs for binary backwards compatibility.


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


       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.


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


       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