JAPICOMPAT(1)						      General Commands Manual						     JAPICOMPAT(1)

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  imple-
	      mentations  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. Mak-
	      ing 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)