Man Linux: Main Page and Category List

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