JAPIZE(1)						      General Commands Manual							 JAPIZE(1)

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)