• Using JABA
• Introduction
• Setting up environment
• Unpacking the distribution
• Setting environment variables
• Preparing the subject
• Compiling the subject
• Building and preparing the resource file
• Running JABA through the provided drivers
• Textual driver
• GUI driver
• Building your custom analysis application
• Copying and modifying the driver
• Visualizing the analysis graphs in JABA
• Compiling the driver
• Running your custom analyzer
• Reporting a bug in JABA

---

Using JABA

Introduction

JABA stands for Java Architecture for Bytecode Analysis. JABA is a software analysis library to analyze Java programs at the bytecode level. It is also implemented in Java. It is an extensible API...

• for use in software analysis experimentation
• as a foundation for further analysis
• for use in CASE tools such as DejaVOO

Because JABA is an API, to use the system for your analyses or application, you must write a driver to invoke the functionality and query the analysis information. A sample textual driver is provided together with its source code, which can be used as a starting point and easily modified to suit the user's needs.
A GUI-based driver is also provided, which allows for analyzing a system and displaying a subset of the graphs built by JABA.
JABA requires the software under analysis to be prepared in a specified way.
This manual will guide you through the process of using JABA. 

Setting up environment

Unpacking the distribution

To use JABA, you must first unpack the distribution. In the rest of the manual, we assume that JABA is unpacked in directory ${HOME}.
After unpacking, you will get the following directory tree:



              ${HOME}
                |
                +- JABA
                    |
                    +- bin
                    |
                    +- doc
                    |
                    +- lib (contains jaba.jar)
                    |
                    +- src (contains JABA.java)
                    |
                    +- test

Setting environment variable

Once the directory structure has been created, two environment variables need to be set in one of your shell-configuration files (e.g., .cshrc, .bashrc) or in an initialization file executed before running JABA: CLASSPATH, and PATH.

Your CLASSPATH must contain the location of the JABA classes, that is, ${HOME}/JABA/lib/jaba.jar. For example, if you are using the csh shell:

setenv CLASSPATH ${HOME}/JABA/lib/jaba.jar:${CLASSPATH}

Your PATH should contain the location of the Java compiler and virtual machine for Java 1.3 or later. The PATH variable must also include ${HOME}/jaba/bin. For example, if you are using the csh shell and the Sun JDK distribution installed in directory /opt/jdk1.4:

    setenv PATH ${HOME}/JABA/bin:/opt/jdk1.4/bin:${PATH}

Preparing the subject

Compiling the subject

JABA requires that the bytecode files being analyzed have been compiled with the -g (debugging) option. Recompile any subject that you would like to analyze with the javac -g command.

Building and preparing the resource file

The current user interface of JABA uses a resource file to obtain information that is relevant to analyzing a subject. The resource file follows a format that specifies values for a set of fields, and these values are parsed by JABA to obtain the relevant information. The class jaba.main.ResourceFile is used to load a resource file. The resource file uses the following fields:

• ProgramName specifies the name for a subject. This field can be optionally set. An unset ProgramName variable defaults to "UnnamedProgram".
• ClassPath is similar to the CLASSPATH environment variable used by the Java Runtime Environment. It is a colon-separated list of directories where JABA expects to find the classes to be analyzed, and library classes referenced by the analyzed classes.
• ClassFiles is a comma-separated list of classes that are analyzed for a subject. The names are fully-qualified class names, relative to the directories specified in the ClassPath field.

To create a resource file:

• Run the script ${HOME}/JABA/bin/build_jrf.pl (requires Perl) and specify, as parameters to the script, the directory (or directories) where the subject is stored and the directory where libraries used by the subject are stored. The script recursively examines all sub-directories for class files, builds a resource file, and prints it to stdout or to the specified file. (For a complete list of options, run

  ${HOME}/JABA/bin/build_jrf.pl -h.

  For example, the command

  ${HOME}/JABA/bin/build_jrf.pl -c test -l /opt/jdk1.4/jre/lib/rt.jar -p 'Test Program' -o test.rc

  creates a resource file for the test program provided with the distribution and stores it in file test.rc in the current directory. The file looks as follows:

  #
  # JABA resource file
  #
  # generated by build_jrf.pl ver. 
  # on  at  - 
  #
  ProgramName = Test Program
  ClassPath = ./test:/opt/jdk1.4/jre/lib/rt.jar
  ClassFiles = \
  Test, \
  User
  

• remove classes that need not be analyzed (in case you want to analyze only a subsystem).

As an alternative, it is possible to create a resource file using the JABA GUI, as described below.

Running JABA through the provided drivers

Textual driver

To run the textual driver, simply execute

jaba <resource file>

For example, you can analyze the test program provided with the distribution as follows:

jaba test.rc

GUI driver

The GUI driver can be run in two ways:

Using a resource file:

jabaGUI <resourcefile>

In this case, the driver first performs the analysis and then provides the user with an interface that allows for visualizing some of the graphs built by JABA, such as CFGs and ICFGs, using DOTTY. (Dotty is a graph layouting and visualizing program provided by AT&T research. It is a free software and can be downloaded from Graphvizsite at AT&T.)
For example, you can analyze the test program provided with the distribution as follows:

jabaGUI test.rc

and see the ICFG for the program by pressing the "ICFG" button (and suitably zooming-out in the dotty window...)

Without a resource file:

jabaGUI

In this case, the GUI allows the user to graphically browse the directory structure to specify the CLASSPATH and the set of classes to be analyzed. Once the selection has been performed, the user can save the information in a resource file, for future reuse, perform the analysis, and visualize different graphs as described at the previous point.

It is possible to specify some options for the GUI driver by creating a file named .jabarc in the current working directory directory. A sample file is provided with the distribution (file jabarc.sample) in directory ${HOME}/JABA. The format of the file is as follows:

# jaba.workingDirectory
# Sets the working directory for Jaba
# this will be the start directory for all
# file selection dialogs.
#
# Default: user's home directory
#
jaba.workingDirectory = /home/orso/Students/MohamedMansour/Examples

# jaba.useSystemClassPath
# Appends the users CLASSPATH to the Class
# Path List
jaba.useSystemClassPath = false

# jaba.classPath
# List of initial class paths
# This list will be appended to the
# Class Path list on startup
jaba.classPath = /home/orso/java/lib/jdk1.4

# dotty.outpath
# Directory for .dotty file
# Default: current directory
dotty.outpath = /home/orso/jaba/dottyStuff

Building your custom analysis application

Copying and modifying the driver

Because JABA is an API, to use the system for your analyses or application, you must write a driver to invoke the functionality and query the analysis information. To write a driver, create a subclass of jaba.main.JABADriver and redefine method run(). A sample driver, which can be used as a starting point, is provided in ${HOME}/JABA/src/JABA.java. The driver contains some sample queries and can be copied and modified to create your own driver. For example:

cd ${HOME}/JABA
cp src/JABA.java src/myJABA.java

Now, edit your copy of the driver to compute the desired analysis information. Remeber to change the name of the class from JABA to whatever name you chose for the driver---myJABA in the above example. The javadoc documentation of the interface of JABA is included in the distribution, in the directory ${HOME}/JABA/doc/javadoc

Visualizing the analysis graphs in JABA

JABA provides a facility to visualize the graphs like ICFG, ACFG etc, that are produced during the program analysis. The graphs can be output to files. These graphs can be visualized with DOTTY. (The GUI driver uses this facility to display graphs.)

Any explicit graph can be output in the dotty format by calling the function createDottyFile. createDottyFile is a method of the Graph class. It takes two arguments. The first one is a string indicating the name of the file where the graph has to written. The second one is a class specifying the paramaters of the output graph.

Presently, JABA allows specifying the parameters of the nodes of the graph. The user can output any combination of the following node specification parameters.

• Node Number in the graph
• Statement Number of the Statement in the code corresponding to the node
• Byte Code offset
• Node Type indiacting the type of the node.

User can specify any combination of these parameters to be written. This can be done by specifying the parameters in the resource file. To specify the parameters in the resource file, you need to add the following line in the resource file.
DottyOutputParameters = NODE_NUMBER: STATEMENT_NUMBER: BYTECODE_OFFSET: NODE_TYPE
Include each of the parameter name if you want it to be output in the node of the graph. For eample if you need to output only Node Number and Node type then include DottyOutputParameters = NODE_NUMBER: NODE_TYPE in the resource file. If the statement is not included in the resource file, JABA outputs all the parameters as default

Compiling the driver

To compile the driver, you just need to execute, with the CLASSPATH set correctly.

javac ${HOME}/JABA/src/myJABA.java

Running your custom analyzer

First, add to the CLASSPATH, before the jaba.jar entry, the path to your local classes. For example, for the myJABA driver, you would need to add ${HOME}/JABA/src to the CLASSPATH:

setenv CLASSPATH ${HOME}/JABA/src:${CLASSPATH}

On the command line, run the driver you modified followed by the name of the resource file that you created. For the analysis to succeed, it is important to increase the amount of memory used by the JVM, using the -mx option:

java -mx1000m jaba.main.JABADriver myJABA <resource file>

Reporting a bug in JABA

• Description of the failure---report the error message printed by JABA, or the stack trace printed by the Java interpreter.
  Example:

Exception in thread "main" java.lang.ArrayIndexOutOfBoundsException: -1
at jaba.graph.cfg.CFG.determineNodeTypes(CFG.java, Compiled Code)
at jaba.graph.cfg.CFG.constructCFG(CFG.java, Compiled Code)
at jaba.graph.cfg.CFG.__load(CFG.java, Compiled Code)
at jaba.sym.Method.getAttributeOfType(Method.java, Compiled Code)
...

• The subject under analysis with any relevant test file, resource file, and driver program.