User's Guide

 

Introduction:

This document describes the following:

Related documents:

To completely understand the CS510JIP class compression utility read ' report.html'.
 

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:

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:

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