Provided by: japitools_0.9.7+git20150619-1_all bug

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