japize - Produce a listing of an API in a machine-readable format.

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

       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,

       japize - Produce a listing of an API in a machine-readable format.

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.

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                                       JAPIZE(1)

japize[unzip][as<name>]apis<zipfile>|<dir>...+|-<pkgpath>...