# 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: 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.

- Java Runtime Environment 1.6.
- SWT 3.3.2 is used for development.
- GNU Trove. 2.0.3 is used for development.
- Javassist. 3.8.0.GA 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`

Note: the distribution archive contains files for Windows. If you use a different operating system, please ignore the files.

## How to use Amida

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

    (Windows) java -classpath swt.jar;trove-2.0.3.jar;amida.jar amida.Amida
    (Other)   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

## 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