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.