AdaptJ: A Dynamic Application Profiling Toolkit for Java Last updated: February 14, 2003

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

AdaptJ is a toolkit which serves two primary purposes:

• To facilitate the collection of dynamic data concerning the execution of a Java program
• To provide a framework for implementing analyses of this collected data quickly and easily

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

• The AdaptJ Agent allows to collect event trace data from a Java program running in a Java Virtual Machine (JVM).
• The AdaptJ Analysis Tool allows to read and analyze the traces generated by the agent, using either the built-in analyses or custom ones.

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

News

• February 14, 2002: AdaptJ version 0.1-beta6 is available for download.
• January 22, 2002: AdaptJ version 0.1-beta5 is available for download.
• January 19, 2002: AdaptJ version 0.1-beta4 is available for download.
• January 16, 2002: AdaptJ version 0.1-beta3 is available for download.
• January 14, 2002: Due to some errors in the packaging of the initial release and some suggestions for improving the usesability of AdaptJ, a second release, 0.1-beta2, is available for download.
• January 13, 2002: The initial release of AdaptJ, tagged 0.1-beta, is available for download.

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 events	Not started
Speed Improvements for both tools	In progress
Allow an even finer granularity when selecting events and their fields	Not started
AdaptJ Trace Analyzer
Implement a data source to allow EVolve to process AdaptJ traces	In progress
Clean up source code	In progress
Add Javadoc comments	In progress
Write the complete documentation	Not started
AdaptJ Agent
Allow outputting bytecode information directly from the agent	Not started
Support IBM's JDK	Not started
Write the complete documentation	Not started

Back to Top

Documentation

Tutorials

The AdaptJ Installation Document and Tutorial is available online.

> Installation and Tutorial:

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

• Various Speed Improvements: caching, code refactoring, etc.
• Several bugfixes

AdaptJ 0.1-beta4 to 0.1-beta5

• Several changes in the Polymorphism Metric, allowing it to provide more representative values

AdaptJ 0.1-beta3 to 0.1-beta4

• Bugfix Release

AdaptJ 0.1-beta2 to 0.1-beta3

• Corrected errors in AdaptJAnalyzer build file
• Added the Control Graph Printer
• Added the Array Metrics
• Added the adaptj.spec.Generator tool to automatically generate and AdaptJ Event Specification file for a list of desired operations
• Moved adaptj.debug.AdaptJSpecExtractor to adaptj.spec.Extractor
• Moved adaptj.spec.AdaptJSpecCompiler to adaptj.spec.Compiler
• Added support for alternate event dependencies (primarily used to allow selecting either the Method Entry or Method Entry2 event when both are available from the trace)
• Modified the HREF parameter in the metrics results (XML) files
• Updated the tutorial

AdaptJ 0.1-beta to 0.1-beta2

• Corrected errors in the packaging (e.g. jar files now extract into their own subdirectory)
• Corrected some errors in the installation document
• Added a shell script to invoke the AdaptJ Analyzer
• Made the default file name for the AdaptJ Analyzer AdaptJ.dat
• Added support for concatenating pack/operation options from the command line:
  -p pack option1:value1 -p pack option2:value2 can now be typed as -p pack option1:value1,option2:value2
• Added an XSL stylesheet for the metrics XML files
• Several bugs fixed

Back to Top

Installation

Installation Requirements

AdaptJ is distributed in various distributions:

• Full distribution: This distribution is the easiest way to install AdaptJ, and is strongly recommended. It contains the entire source code, binary distribution of the AdaptJ analysis tool and the full documentation.
• Source distribution: This distribution only contains the source code for both tools, and is the minimal distribution of AdaptJ.

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):

• BCEL
• fastUtil-2.11
• Jakarta Regexp (required by BCEL)

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