README for CS510JIP Class compresssion utilities

User's Guide

Introduction:

This document describes the following:

How to set up the environment for the Class compressor, decompressor and the class loader.
How to execute the ByteCodeCompressor, Whole class compressor, ByteCodeDecompressor and the Whole Class decompressor .
Test the validity of the compression using a Class loader to resolve compressed as well as uncompressed classes.

Environment:

As the project has been coded entirely in Java, it should be possible to execute the applications on any platform supporting JDK 1.1 .
The entire package is available in a single 'ZIP' file. Follow the steps listed below to install the software:

Unzip the file 'CS510JIP.zip' into a separate directory (say 'HOME'). The inflation would create three sub directories, namely, 'classcompressor' containing all the '.java' and '.class' files for class compression and decompression; sub-directory 'classloader' containing all the '.java' and '.class' files for the class loader; sub-directory 'class-example' containing the class examples used to test the utilities.
The file 'classpath.bat' sets the classpath on a Windows/NT machine. Edit the file to point to the JDK home directory on your machine as well as the compressor HOME.
Execute the batch file to set CLASSPATH.

Class Compressor

Constants: Boolean flags enabling various compression methods, debugging, etc. are available in a '.java' file called 'Constants.java' (<HOME>/cs510jip/classcompressor/Constants.java). It might be required to edit this file.
The following are some of the important constants along with their initial settings:

    /**
    * Compress the byte code ??
    */
    public static final boolean COMPRESS_BYTECODE = true ;

    /**
    * Turn ON/OFF debugging.
    */
    public final static boolean DEBUG = true;

    /*
    * GZIP compression after Byte code compression.
    */
    public final static boolean GZIP_COMPRESS = true ;

    /**
    * Flag to indicate if the Code Attribute information (Debugging info.) is to be
    * included in the Class file generated.
    */
    public static final boolean WRITE_CODE_ATTRIBUTES = false ;

NOTE: All flags are 'static final' attributes. So if any change in the settings is done, it would necessitate the recompilation of all dependents, which in this case are some of the classes in 'classcompressor'.
Also note that the settings are shared by both the class compressor and decompressor. So if any change in the settings is done, it is advisable to regenerate any already generated compressed classes ( '.cls' files).

Testing the ByteCodeCompressor:

The class 'ByteCodeCompressorTest' tests the byte code compression algorithm and outputs trace information as any new instruction is generated, but does not create any compressed class file.

To run, 'cd' to <HOME>/cs510jip/codecompressor and type 'java ByteCodeCompressorTest <.class file>'.
e.g.: "java cs510jip.classcompressor.ByteCodeCompressorTest ClassFileReader.class > out'.
Edit the file 'out' to see all the new instructions that will get generated along with the original byte code size and the new byte
cod size.

Generating the Compressed class file:

The class 'ClassCompressor' compresses the whole class file according to the parameters set in the class 'Constants.class' and outputs the compressed class to a file with extension '.cls'.

To run, 'cd' to <HOME>/cs510jip/codecompressor and type 'java ClassCompressor <.class file>'.
e.g. "java cs510jip.classcompressor.ClassCompressor ClassFileReader.class > out"
In this case file 'ClassFileReader.cls' contains the compressed class.

There are several other example classes available in <HOME>/cs510jip/class_example.

Testing the ClassDecompressor:

The class 'ClassDecompressor' tests the entire class decompression generating the original class file.

To run, 'cd' to <HOME>/cs510jip/classcompressor and type 'java ClassDecompressor <.cls file>'.
e.g.: "java cs510jip.classcompressor.ClassDecompressor ClassFileReader.cls > out'.
Here a file 'ClassFileReader.classd' contains the decompressed class.
NOTE: The size of the decompressed class file may not be the same as the original class file as some debugging information may have been eliminated.

Validating the decompression:

The decompressed class file can be validated using either the 'class loader' built to load compressed classes or by renaming 'ClassFileReader.classd' to 'ClassFileReader.class' and running the decompressor again (This uses ClassFileReader.class).

Class Loader:

The class loader is available in <HOME>/cs510jip/classloader. This class loader can load compressed as well as uncompressed classes. The loader tries to retrieve a file with a '.cls' extension first, if not available tries for a file with a '.class' extension. If both tests fail an exception is thrown.

To run, 'cd' to <HOME>/cs510jip/classloader and type 'java TestLoader <classpath(optional)> <Fully qualified class name>'.

e.g: "java cs510jip.classloader.TestLoader
d:/cs510jip/project/project_main/ cs510jip.classcompressor.ClassFileReader >out ".
Note that as a Loaded class gets resolved several other classes may need to be loaded, so make sure all the dependent classes are also available accessible through the class path.

Known Problems:

- The class compressor currently fails to compress the byte codes when there are constant pool instructions using indexes greater than 255. This might be the case for very large class files. In case the algorithm comes across such an constant pool index, an exception message will be written to 'std err' device and the resulting .cls file generated will be invalid.
- Very rarely used are some variable length instructions, lookupswitch and tableswitch. The class compressor cannot handle these at this moment and the resulting .cls file generated will be invalid.
- The Class loader implement's both a Local file class loader as well as aURL(remote file) class loader. The current URL class loader still has some unresolved bugs and fails to load classes.

===================================================================================