JAX Frequently
Asked Questions
-
What is JAX? Why should
I use it?
-
How do I download JAX?
How do I install it?
-
Where is the documentation?
-
How do I use it? What command
line options are support?
-
How do I report bugs?
-
What do I do when my JAXed
program does not work?
-
What do I do when the VM
runs out of memory?
-
What happens with resource
files in the original zip or jar file?
-
How do I preserve the names
of certain classes?
-
How can I apply JAX to
a class library?
-
How do I find out where
reflection is used?
-
When to use the -nocompatibleserialization
option?
-
How do I specify the classes
that are to be included in, or excluded from,the classes that are to be
JAXed?
-
How do I preserve
the package names of the classes?
What is JAX? Why should
I use it?
JAX is an application extraction tool for Java that reduces the program's
size. JAX extracts the necessary classes, methods, and fields from a Java
application (or applet), applies some optimizations and compression techniques.
We measured size reductions ranging from 30% to 80% on real-life Java applications,
where the larger size reductions generally occur for large, library-based
applications. We have succesfully used JAX on applications of up to 2300
classes.
You should use JAX if you want to reduce the size, or obfuscate your
Java program.
How do I download Jikes?
How do I install it?
JAX is available on alphaWorks.
Follow the instructions to download it.
JAX is written in 100% pure Java, and runs on any platform that uses
Sun's JDK or other compatible VMs.
Where is the documentation?
Documentation is provided in HTML files in the download package.
Details:
-
The installation provides HTML documentation in the directory jax\docs.
-
The documentation provides an executive summary, installation details,
a tutorial, a reference manual, FAQs, news, and feedback.
How do I use it? What command
line options are support?
JAX takes as input a the name of a Java class that represents the Java
program whose size you want to reduce. Since JAX is written in Java, you
run JAX the same way you would run any other Java program.
java jax [command_line_options] <class_name>
Where:
-
<class_name>
-
starting class name
-
command_line_options (optional) are:
-
-version
-
show version number
-
-help
-
show help information
-
-notransform
-
do not merge classes
-
-noinline
-
do not inline methods
-
-nodevirtualize
-
do not devirtualize method calls
-
-noobfuscate
-
do not shorten names of internal classes, methods, and fields
-
-noverify
-
do not verify the compressed application
-
-nocompatibleserialization
-
don't preserve (de)serialization compatibility between original/JAXed versions
of the application.
-
-keeppackagenames
-
preserve package name of the classes.
JAX generates a zip file and a log file.
-
<class_name>_jax.zip is the compressed
program
-
<class_name>_jax.log is the log
file
JAX looks for 4 optional input files in the current directory:
-
<class_name>_jax.inc contains
the specifications for the classes that are to be included in, or excluded
from, the classes that are to be JAXed.
-
Below is an example of the contents of such a file:
-
|
include *
exclude java.*
exclude com.ms.*
exclude sun.* |
-
<class_name>_jax.dlc contains
the names of all classes that are loaded dynamically.
-
Example:
com.acme.ClassOne
com.acme.ClassTwo
com.acme.ClassThree
|
-
-
<class_name>_jax.dim contains
the names of all the methods that are called using reflection and the methods
which should not be obfuscated and transformed.
-
Example:
com.acme.ClassFour specialMethod1 (I)V
com.acme.ClassFour specialMethod2 (III)I
com.acme.ClassFour (Ljava/lang/Object;)V
|
-
<class_name>_jax.daf contains
the names of all the fields that are accessed using reflection.
-
Example:
com.acme.ClassFive specialField1 (I)V
com.acme.ClassSix specialField2 (III)I
com.acme.ClassSeven specialField3 java/lang/Object;
|
-
Use the "methods" and "fields"
programs that are included with the JAX distribution to get a listing of
available methods and fields in the appropriate format. Example:
java methodsjava.lang.String
java fields java.lang.String
|
How do I report bugs?
Please report all bugs by sending mail to jax@watson.ibm.com.
What do I do when my JAXed
program does not work?
Try JAXing your program with different combinations of the -noobfuscate,
-noline, -nodevirtualize, or -notransform command line options. Each
option turns off some extraction, optimization or compression functionality.
Please tell us if this problem occurs by sending mail to jax@watson.ibm.com.
What do I do when the Java
VM runs out of memory?
JAX requires approximately 40 Kbytes of memory per class processed. To
ensure that the Java VM allocates enough memory while running JAX, tell
it to allocate a larger than usual heap with the -mx
option. For example:
java -mx128M jax <class_name>
will allocate a heap size of 128 Mbytes.
What happens with resource
files in the original zip or jar file?
JAX is only concerned with the compression of class files and ignores non-class
files (e.g., .gif files and .properties files) in the class path. If your
application depends on such resource files, please save them in a separate
.zip or .jar file. In order to run your compressed application you should
include this separate resource archive to your classpath,
How do I preserve the name
of certain classes?
In some application, reflection is used to retrieve the name of a class,
and to read a resource (i.e., .gif) file with the same name. In such cases,
the name of the class must be preserved in order to run the JAXed application
correctly. You can achieve this by including the class in the .dlc
file (see above).
How can I apply JAX to
a class library?
In its current form, JAX is an application extractor. It assumes
that the JAXed application will not be extended (subclassed) and it will
remove methods and fields that are not accessed or invoked. Currently the
only mechanism to force the preservation of a class, method, or field is
to include it in the .dlc, .dim, or .daf
file, respectively. We are working on a better mechanism to support libraries.
How do I find out where
reflection is used?
It can be difficult to find out where reflection is used in your application,
especially if you use third-party libraries for which you don't have access
to the source code. To address this problem, we have included a tool called
reflect
with the JAX 5.0 distribution. This tool analyzes a ZIP file, instruments
calls to the reflection API (e.g., calls to Class.forName(),Class.newInstance(),
Method.invoke(),
etc.), and produces an instrumented ZIP file. You can then run the instrumented
application by putting the instrumented ZIP file in your classpath. Running
the instrumented application will produce a log file jax-reflect.log
in
which the intercepted calls to the reflection API are recorded. This will
tell you which classes to list in the .dlc file, which methods to list
in the .dim file, and which fields to include
in the .daf file.
To instrument your application with reflect:
-
put jax50.zip in your classpath.
-
collect all the class files of your application in a zip file MyZipFile.zip
-
java reflect MyZipFile.zip
This will produce a zip file MyZipFileR.zip
containing the instrumented application. reflect will also produce
a log file reflect.log telling you
which calls it instrumented. Now put MyZipFileR.zip
in your classpath, and run the instrumented application. This will produce
a log file jax-reflect.log with information
about the calls to the reflection API.
When to use the -nocompatibleserialization
option?
Many Java applications use serialization, which is a mechanism for
writing out objects to a file, deserialization for reading serialized
objects from a file. You can make your class serializable by having it
implement the interface java.io.Serializable. As soon you do this,
objects of that type can be serialized, and this is done by writing out
the non-static and non-transient fields of the class (and its base classes)
in a specific order. Serialization poses some interesting issues for an
extraction tool like JAX. What if you would write out an object with the
original, uncompressed version of your application, and then try to read
them back in with the compressed (JAXed) version of your application? If
JAX happens to remove unnecessary fields from a previously serialized class,
the serialized objects are no longer compatible, and similar problems occur
if JAX would merge serializable classes. To avoid such problems, JAX only
applies a limited number of transformations to serializable classes. However,
if you don't mind breaking the compatibility between JAXed and unJAXed
versions of your applications, you can tell JAX to be more aggressive by
specifying the -nocompatibleserialization option. Note: your applications
may implement java.io.Serializable indirectly. For example, all
applets are serializable.
How do I specify the classes
that are to be included in, or excluded from,the classes that are to be
JAXed?
You can provide these informations to JAX in an .inc
file.
Before loading the java classes, JAX optionally tries to look into
this .inc file to find out the classes
that are to be included in, or excluded from, the classes that are to be
JAXed. Below is an example of the contents of such a file:
include *
exclude java.*
exclude sun.*
exclude sunw.*
exclude com.ms.* |
Look at the The
JAX tutorial for a brief description of this new option.
How
do I preserve the package names of the classes?
JAX provides a option, "-keeppackagenames"
which if selected, will preserve the package
namesof the classes during name compression. Instead of renaming the
class "foo.bar.SomeName" to
"a", it will be renamed to "foo.bar.a".
Below is the usage of the option for the sample program Hanoi.
java jax -keeppackagenames
Hanoi
Copyright IBM 1997-1999. All Rights Reserved
More info inside IBM
More info outside
IBM