McGill

AdaptJ: A Dynamic Application Profiling Toolkit for Java

Last updated: February 14, 2003
Sable


This software is now deprecated. Please use *J instead.

AdaptJ is a toolkit which serves two primary purposes:

These two main goals are accomplished through the use of two separate tools, the union of which composes the AdaptJ toolkit:

AdaptJ is free software and is licensed under the GNU Lesser General Public License.



News


Back to Top


Planned Features

AdaptJ is still under (heavy) development. A list of planned features will be maintained here so that end-users and beta-testers can know what is being done and how quickly things are advancing. All bug reports, comments, suggestions and feature requests should be sent to Bruno Dufour.

General
Implement support for all JVMPI eventsNot started
Speed Improvements for both toolsIn progress
Allow an even finer granularity when selecting events and their fieldsNot started
AdaptJ Trace Analyzer
Implement a data source to allow EVolve to process AdaptJ tracesIn progress
Clean up source codeIn progress
Add Javadoc commentsIn progress
Write the complete documentationNot started
AdaptJ Agent
Allow outputting bytecode information directly from the agentNot started
Support IBM's JDKNot started
Write the complete documentationNot started


Back to Top


Documentation

Tutorials

The AdaptJ Installation Document and Tutorial is available online.

 > Installation and Tutorial: pdf   html


Back to Top


Downloads

The first and latest release of AdaptJ is version 0.1-beta6.

Current Version
0.1-beta6
This is the complete release of AdaptJ, and bundles the source plus pre-compiled binaries. It also includes the required (precompiled) java libraries. This is the easiest way to install AdaptJ. AdaptJ-0.1beta6.jar (6177 KB)
Source release of AdaptJ. This release only contains the source code plus some files that are part of the full package. This is the minimal distribution of AdaptJ. AdaptJ-0.1beta6-src.jar (472 KB)
Previous Versions
0.1-beta5
This is the complete release of AdaptJ, and bundles the source plus pre-compiled binaries. It also includes the required (precompiled) java libraries. This is the easiest way to install AdaptJ. We strongly recommend using version 0.1-beta6 instead of this version. AdaptJ-0.1beta5.jar (6121 KB)
Source release of AdaptJ. This release only contains the source code plus some files that are part of the full package. This is the minimal distribution of AdaptJ. We strongly recommend using version 0.1-beta6 instead of this version. AdaptJ-0.1beta5-src.jar (455 KB)
0.1-beta4
This is the complete release of AdaptJ, and bundles the source plus pre-compiled binaries. It also includes the required (precompiled) java libraries. This is the easiest way to install AdaptJ. We strongly recommend using version 0.1-beta6 instead of this version. AdaptJ-0.1beta4.jar (6121 KB)
Source release of AdaptJ. This release only contains the source code plus some files that are part of the full package. This is the minimal distribution of AdaptJ. We strongly recommend using version 0.1-beta6 instead of this version. AdaptJ-0.1beta4-src.jar (455 KB)
0.1-beta3
This is the complete release of AdaptJ, and bundles the source plus pre-compiled binaries. It also includes the required (precompiled) java libraries. This is the easiest way to install AdaptJ. We strongly recommend using version 0.1-beta6 instead of this version. AdaptJ-0.1beta3.jar (6115 KB)
Source release of AdaptJ. This release only contains the source code plus some files that are part of the full package. This is the minimal distribution of AdaptJ. We strongly recommend using version 0.1-beta6 instead of this version. AdaptJ-0.1beta3-src.jar (453 KB)
0.1-beta2
This is the complete release of AdaptJ, and bundles the source plus pre-compiled binaries. It also includes the required (precompiled) java libraries. This is the easiest way to install AdaptJ. We strongly recommend using version 0.1-beta6 instead of this version. AdaptJ-0.1beta2.jar (6098 KB)
Source release of AdaptJ. This release only contains the source code plus some files that are part of the full package. This is the minimal distribution of AdaptJ. We strongly recommend using version 0.1-beta6 instead of this version. AdaptJ-0.1beta2-src.jar (445 KB)
API Documentation
0.1-beta5
You can browse the API documentation on-line, or download it in .jar format. AdaptJ-0.1beta6-doc.jar (654 KB)


Back to Top


History of Changes

AdaptJ 0.1-beta5 to 0.1-beta6

AdaptJ 0.1-beta4 to 0.1-beta5

AdaptJ 0.1-beta3 to 0.1-beta4

AdaptJ 0.1-beta2 to 0.1-beta3

AdaptJ 0.1-beta to 0.1-beta2


Back to Top


Installation

Installation Requirements

AdaptJ is distributed in various distributions:

AdaptJ is distributed in various distributions:

AdaptJ requires Java 1.4 or later if you want support for Instruction Start events. Earlier versions of the JDK do also work, but will not send such events to the AdaptJ agent (Instruction Start events have been introduced by Sun in their Java 1.3 implementation, but it only seems to work properly for the Microsoft Windows version of the Java 1.3 SDK). AdaptJ has only been tested with Sun's Java implementation, although support for the upcoming IBM Java2 1.4 is planned.

To compile the AdaptJ Agent, the typical GNU tools (gcc and GNU make) are strongly recommended. You must also have a copy of 'zlib' installed on your system. Visit http://www.gzip.org/zlib/ if you don't. Most Linux systems have it installed by default (you can type 'locate libz' at your shell prompt to check).

Jakarta Ant is also recommended if you ever need to (re-)compile AdaptJ. It is not necessary for the full distribution of AdaptJ, but is strongly recommended for the source distribution. You can get a copy of the latest version of at http://jakarta.apache.org/ant/.

AdaptJ makes use of the following Java libraries (all of which are included in the full-distribution):

The following installation instructions assume that a UN*X system is used. There is currently no support for AdaptJ under Microsoft Windows, although only minor modifications should be required in order to get AdaptJ to run under a Windows OS.

Obtaining a copy of the latest AdaptJ distribution

If you have not already done so, get the latest copy of the AdaptJ distribution. AdaptJ is available from this page. The full distribution is strongly recommended.

Unjar the archive file into a directory of your choice (which we will refer to as ${ADAPTJ_HOME} in the present instructions). This can be done using the following command (which should be executed from the directory in which you saved the AdaptJ distribution file). Note that in all shell commands presented in this document, '$' represents your shell prompt and is not part of the command:

$ jar -xvf <your-downloaded-archive.jar>
e.g.
$ jar -xvf AdaptJ-0.1beta2.jar

Then make the created subdirectory the current directory:
e.g.

$ cd AdaptJ-0.1beta2

Now, in order to allow typing the commands exactly as shown here, set the value of the ADAPTJ_HOME environment variable to point to your current directory by typing the following:

$ export ADAPTJ_HOME=`pwd`

If you do not want to perform the last step, remember to replace every occurence of the expression ${ADAPTJ_HOME} by the appropriate directory name throughout the installation process.

Installing the AdaptJ JVMPI Agent

The installation of the AdaptJ JVMPI Agent requires the compilation of the Agent itself, and is automated using GNU make.

First, make the AdaptJAgent source directory the current one by typing:

$ cd src/AdaptJAgent

Then, edit the file named 'Makefile' in the following way:
   Locate the line which reads:

   JAVA_HOME=/opt/j2sdk-1.4.1

and adjust the right-hand part of it to point to the root of your local java installation. To tell whether you have found to correct directory, try to locate a subdirectory named 'include'.

If you do not want to use the default C compiler (gcc), change the line which reads 'CC=gcc' to suit your needs.

Then, type 'make' at the prompt to compile the Agent and install it.

In order to get Java to find the agent you just compiled, you must add ${ADAPTJ_HOME}/ldlib to your LD_LIBRARY_PATH.

If you are using the 'bash' shell, this can be done by typing:

$ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:${ADAPTJ_HOME}/ldlib

You may want to put the above line in your .bash_profile or .bashrc script to make the required change each time you login to your account.

Finally, because the command line that is needed to execute both tools can get tedious to type, tiny convenience scripts are provided in the ${ADAPTJ_HOME}/bin directory. You may want to add this directory to your PATH if you want to use them, like so:

$ export PATH=$PATH:${ADAPTJ_HOME}/bin

You should also make both scripts executable by typing:

$ chmod a+x ${ADAPTJ_HOME}/bin/*

since the jar tool does not preserve the executable bit.

Installation of the AdaptJ Analysis Tool

If you have the full distribution of AdaptJ, then you only need to add every .jar file in the ${ADAPTJ_HOME}/lib directory to your CLASSPATH.

Using the 'bash' shell, this is achieved as follows:

$ export CLASSPATH=$CLASSPATH:${ADAPTJ_HOME}/lib/AdaptJ.jar:\ 
${ADAPTJ_HOME}/lib/bcel.jar:${ADAPTJ_HOME}/lib/jakarta-regexp-1.2.jar:\ 
${ADAPTJ_HOME}/lib/fastUtil-2.11.jar

If you have the source distribution of AdaptJ, you need to compile it first. This can be automated using Jakarta Ant. From the ${ADAPTJ_HOME} directory, type:

$ ant makejar

This will create the ${ADAPTJ_HOME}/lib directory containing the file 'AdaptJ.jar'. Add it to your CLASSPATH in a way the same way as for the full distribution. The remaining libraries (see the installation requirements) must be obtained and installed too.


Back to Top


Related Projects

A number of projects at Sable are related to visualization, softare understanding or execution traces.

STEP

STEP is a system for encoding and compressing program traces in a flexible format.

More information is available at: http://www.sable.mcgill.ca/step/

EVolve

EVolve is a system for visualizing trace data in a variety of ways.

More information is available at: http://www.sable.mcgill.ca/evolve/

Dynamic Metrics

The Dynamic Metrics project aims at developing new and meaningful dynamic software metrics for Java programs.

More information is available at: http://www.sable.mcgill.ca/metrics/


Back to Top




Maintained by Bruno Dufour