# Amida: A Sequence Diagram Extraction Toolkit for Java

Amida is a toolkit to record an execution trace of a Java program and visualize the trace as a sequence diagram.

This document describes how to visualize dynamic behavior of a Java program using Amida.

Note: Amida is still under development. This tool is free to use for academic research. We would like to distribute Amida as an open source software but its license is not determined yet.

## Table of Contents

- Installation
- How to use Amida
  - Record an execution trace of a Java program
  - Apply phase detection to a trace
  - Visualize a phase or a trace as sequence diagrams
  - Configuration
- Current Status of Amida
- Contact Information

## Installation

Amida requires the following software as a runtime environment.

- Microsoft Windows, if you would like to record an execution trace on your system.

  This is because the current distribution includes only a profiler DLL compiled for Windows.

- Java Runtime Environment 1.6.
- SWT 3.3.2 is used for development.
- GNU Trove. 2.0.3 is used for development.
- A Perl interpreter and File::ReadBackwards module. ActivePerl 5.10 is used for development.

  Phase Detection functionality is written in Perl. If you would like to only visualize an example data in a distribution archive, you don't need Perl.

  We also use ReadBackwards module. If you installed ActivePerl, the following command can add the module: `ppm install File::ReadBackwards`

## How to use Amida

How to execute Amida: If you already have JRE, GNU Trove and SWT library, you may execute Amida as follows.

    java -classpath swt.jar;trove-2.0.3.jar;amida.jar amida.Amida

Data Files for Amida: An important file is a `.log` file that contains an execution trace. Phase detection analyzes a `.log` file and stores the result into several files such as `.log.amd`.

To create a `.log` file, you have to record an execution trace of a Java program. You may apply phase detection to `.log` file or visualize it as sequence diagrams.

A `.log` file is a text file with some structural elements. If you would like to know the detail of the format, please contact us.

Features of Amida: Please follows the links for three topics: recording an execution trace, applying phase detection and visualizing a phase or a trace.

- Record an execution trace of a Java program
- Apply phase detection to a trace
- Visualize a phase or a trace as sequence diagrams

### Configuration

Amida has a configuration file named `amida.properties`. A configuration file is not necessary to use the current version of Amida, but you can configure Amida for your environment.

Property | Value | Default
--- | --- | ---
jvm | This value specifies a default Java command in Amida Profile Launcher window. | java
amida.script.dir | A value specifies a directory containing Perl scripts for phase detection. | . (current directory)
amida.script.command | You may specify a full path to a Perl command if you would like to change a Perl interpreter. | perl
amida.log.dir | This value specifies a home directory for a file open dialog to load a log file. | . (current directory)
amida.log.default | A default log file name used in phase detection window. | test.log
amida.phase.count.summary | The number of method calls shown in a phase summary window. | 5
amida.phase.count.tooltip | The number of method calls shown in a phase summary tooltip text. | 3
amida.phase.param.PARAM.KIND | The default values for phase detection parameters. PARAM is one of "cache", "window", "threshold" and "scope". KIND is one of "from", "to" and "step". | vary

## Current Status of Amida

The distribution archive contains July 2008 version of Amida.

We are developing a new version for Amida including the following features.

- A new profiler using bytecode-transformation (Javassist).

  The new version is much faster than the current JVMTI implementation, and can work with different platforms. Its release will be announced on a website.

- A Java implementation of phase detection.

  A new implementation will remove Perl from a runtime environment.

- An improved viewer.

  We would like to enable a developer to save/load the state of Amida Viewer. We also have several plans to improve the viewer.

If you have any ideas to improve Amida, please let us know.

## Contact Information

Amida website is available at http://sel.ist.osaka-u.ac.jp/~ishio/amida/.

Takashi Ishio
ishio at ist.osaka-u.ac.jp (please replace "at" with "@".)
Software Engineering Laboratory
Graduate School of Information Science and Technology, Osaka University