NAME
japize - Produce a listing of an API in a machine-readable format.
SYNOPSIS
japize [unzip] [as <name>] apis <zipfile>|<dir> ... +|-<pkgpath> ...
DESCRIPTION
japize 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.
At least one +<pkgpath> is required. <name> will have ".japi" and/or
".gz" appended as appropriate.
The word "apis" can be replaced by "explicitly", "byname", "packages"
or "classes". These options indicate whether something of the form
"a.b.C" should be treated as a class or a package. You may specify this
unambiguously by using one of the forms "a.b.cpackage," or
"a.b,CClass".
OPTIONS
unzip disable zipping of the output with gzip. Zipping the output is
highly recommended since it saves huge amounts of space. The
only situations where you might not want to use gzip compression
are when memory and CPU usage are extremely tight or if your JVM
does not implement GZIPOutputStream correctly (in which case you
might still want to gzip the resulting file manually).
as <name>
Specifying this option tells japize to write its output to a
file with the specified name. When writing to a file with the
"as" option, japize insists on writing to a file name ending in
.japi.gz for compressed files, or .japi for uncompressed files.
If the filename you specify doesn't have the right extension,
japize will add parts to it to ensure that it does.
If the "as" option is omitted, japize will write to standard
output. In this case japize has no control over the filename you
use, but it is strongly recommended to use a filename with the
correct extension (".japi.gz" unless the "unzip" option was
specified). If you use any other extension, japicompat and other
tools may be unable to recognize the format.
apis | explicitly | byname | packages | classes
This option has a dual role: it indicates the boundary between
japize options (unzip, as) and other arguments (files and
packages), but also tells japize how to deal with ambiguously
specified arguments. See "+|-<pkgpath>" below for details on the
behavior of each option. If you are unsure which to specify,
"apis" is a safe choice.
apis
a.b.c is tried both as a package and a class. This will always
do what you want (which is why apis is described as the safe
default) but at the expense of possibly doing extra unnecessary
processing trying to find the wrong thing.
explicitly
pkgpaths of the form a.b.c are illegal - you must use the
explicit form.
byname
a.b.c will be processed as a package if "c" starts with a
lowercase letter, or as a class if it starts with an uppercase
one. This usually does what you want but fails on things like
org.omg.CORBA.
packages
a.b.c will be processed as a package. If processing for a class
is needed, it must be specified explicitly.
classes
a.b.c will be processed as a class. If processing for a package
is needed, it must be specified explicitly.
<zipfile> | <dir>
Any arguments after "apis" that do not start with "+" or "-" are
taken to be zipfiles or directories. These should be specified
exactly as you would put them in your CLASSPATH (except
separated by spaces rather than colons). Anything that's a file
will be assumed to be a zip (or jar) file, so you can't specify
a .class file directly - if you need to do that you should
specify the folder containing it and then name the class for
processing.
+|-<pkgpath>
To specify which classes are included, use +pkgpath to add
pkgpaths to be scanned and -pkgpath to exclude sub-pkgpaths of
these. You MUST specify at least one +pkgpath option to specify
which pkgpath to include, otherwise Japize could happily scan
through all the zipfiles and directories but not actually
process any of the classes. Since that would be a useless thing
to do, japize gives an error instead.
A "pkgpath" refers to either a package (which includes, by
implication, all sub-packages of it) or a single class. A
pkgpath for a package looks like "com.foo.pkg.sub," and a
pkgpath for a class looks like "com.foo.pkg,Cls". The existence
and placement of the comma indicates unambiguously which type of
path is intended.
Most of the time, though, it's a pain to have to put in commas
in names that are familiar with dots instead, and get the comma
placement exactly right. For this reason, japize accepts
pkgpaths containing only dots, and lets you tell it what to make
of those names. The interpretation of "a.b.c" as a pkgpath
depends on whether you specified apis, explicitly, byname,
packages, or classes.
EXAMPLE
Sun's JDK 1.1 includes classes in java.awt.peer and in
java.text.resources that are not part of the public API, even though
they are public classes; however, every other class in the java.*
package hierarchy is part of the public API. The syntax to construct a
useful jdk11.japi.gz would therefore be:
$ japize as jdk11 apis classes.zip +java -java.awt.peer
-java.text.resources
Note that since all pkgpath arguments here are packages, you could save
a small amount of processing by doing this instead:
$ japize as jdk11 packages classes.zip +java -java.awt.peer
-java.text.resources
or even this:
$ japize as jdk11 explicitly classes.zip +java, -java.awt.peer,
-java.text.resources,
SEE ALSO
japicompat(1) Test Java APIs for binary backwards compatibility.
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