JAPIZE(1)

💖 JAPIZE — bestie's guide to the API lister 💖

okay so. japize is a real one. it's a whole tool from the japitools family and its entire job is: Produce a listing of an API in a machine-readable format. that's it, that's the girlbossery. ✨

🌸 SYNOPSIS 🌸

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

yes the synopsis has no commas and neither do we. it's giving chaotic but correct. 💅

🦋 DESCRIPTION 🦋

okay so japize is one half of japitools, and japitools was literally built to test for compatibility between Java APIs. that's the whole vibe.

and like, the origin story?? they were originally designed for testing free implementations of Java itself for compatibility with Sun's JDK. but plot twist bestie — they can also be used for testing backward compatibility between versions of <em>any</em> API. glow up fr. 👑

The tools are japize and japicompat. Here's the division of labor:

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

so one of them talks, the other one judges. iconic duo behavior, no notes. 😭

⚠️ At least one +<pkgpath> is required. not optional. not a suggestion. japize is not playing.

also <name> will have ".japi" and/or ".gz" appended as appropriate — so don't come for her about the extension, she handles it. 🎀

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. and if you want to be <em>unambiguous</em> about it (main character energy), you may specify this 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). basically: turn this on only if you're fighting for your life on resources. 😮‍💨
• 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. she's a little type-A about extensions and honestly? respect. 🫶

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. so like, don't be quirky about it unless you enjoy suffering. 💀

• 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. she'll check both doors. one of them is locked. she's fine with that. 🚪✨
  • explicitly — pkgpaths of the form a.b.c are illegal — you must use the explicit form. no shortcuts, no vibes, only precision. 🎯
  • 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. sorry bestie, capitalization lies sometimes. 😭
  • 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 <em>exactly</em> 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. no sneaking single files past her, she sees everything. 🙈
• +|-<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. and honestly?? good for her. she's not gonna do all that work for nothing. 💅

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 <em>unambiguously</em> which type of path is intended. the comma is the moment. the comma is the whole plot. 🌟

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. so like, you have options and she's flexible but she needs to know which lane you're in. 🛣️

🌈 EXAMPLE 🌈

Sun's JDK 1.1 includes classes in java.awt.peer and in java.text.resources that are <em>not</em> 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,

look at her. three ways to do the same thing. all valid. all ate. 🔥

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

go read them. the whole family is cute. iykyk. 🦋

and that's the page bestie!! 🫶 this is JAPIZE(1) from the General Commands Manual, dated October 6, 2005. yeah she's a 2005 baby and she's still serving. periodt. 💖✨👑