# Amida Users Guide - Visualizing a phase or a trace

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

## Visualize a phase or a trace as sequence diagrams

Double-clicking on a phase opens an Amida Viewer window. If you would like to directly open a viewer, please use `-viewer` option.

    (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

If you have activated a viewer for a phase, the viewer window shows sequence diagrams representing the phase. If the phase involves two or more threads, each thread is represented as an independent sequence diagram.

If you would like to visualize a `.log` file without phase detection, you can use `[File]-[Open a log file]` menu.

A sequence diagram is provided with an overview that is located in the right side. A red rectangle indicates where the left side view is located in the whole diagram.

### Tools to explore a sequence diagram

Command | Functionality
--- | ---
Double-Clicking on a method execution (a vertical rectangle) | Double-clicking on a method execution (a vertical rectangle) hides the execution. The hidden part is indicated as a black rectangle.
`[Extract a diagram]` Context Menu | When you are interested in a single method call, you may use `[Extract a diagram]` menu, that is shown by a right-click on a method call. A selected method call (indicated by blue) is extracted as a separated diagram. The new tab has the copy of the filters applied in the original diagram.
Keyword Search: `[Tool]-[Search]` Menu | If a diagram is too large to scroll, you may use a keyword search `[Tool]-[Search]` to find an object, a method call or a return type.
Filtering Events and Objects: `[Tool]-[Filters]` Menu | Amida provides filters that hide or delete uninteresting method calls. Selecting `[Tool]-[Filters]` menu to open a filter configuration dialog. The detail is described here.
Loop Detection: `[Tool]-[Compaction]` Menu | `[Tool]-[Compaction]` menu provides a set of rules to detect and remove loops from a diagram. Detected loops are indicated by annotations in a diagram. Double-clicking on an annotation expands the contents of a loop. The following figure shows an example of `[Tool]-[Compaction]-[Object difference loop]`.
Sorting Objects: `[Tool]-[Sort Objects]` Menu | `[Tool]-[Sort Objects]` menu sorts objects in the top of a diagram. Objects can be sorted by their timestamp, IDs, package names and class names. Timestamp of an object indicates the minimum event ID that object is used in the sequence diagram.
Filtering Local Objects: `[Tool]-[Apply dominance analysis]` Menu | `[Tool]-[Apply dominance analysis]` menu classifies objects into groups using a dominance algorithm. `[Tool]-[Load-time dominance analysis]` is to automatically apply the dominance analysis when loaded an execution trace.

### Filters to reduce the size of a sequence diagram

Amida provides filters that hide or delete uninteresting method calls. Selecting `[Tool]-[Filters]` menu to open a filter configuration dialog.

Sequence diagrams have their own filters (shown as diagram names) and share global filters (shown as "default filters"). You may configure filters but the current version of Amida cannot save the configured filters to a disk.

Object Filters Tab has two tables. One is to edit filters to hide/delete objects from a diagram. The other is to edit filters to replace objects with a group.

To add a filter, click on `[Add]` button on the right side of the tables. You can edit the following attributes.

Column | Value
--- | ---
Filter Type | A `Hide` filter removes objects but don't remove method calls. A `Delete` filter completely remove objects and related method calls. For example, consider an object X calls Y, Y calls another object Z. A Hide filter removing Y from a diagram shows an indirect method call from X to Z on a diagram. A Delete filter removing Y removes transitive method calls between X and Z. Hide/Delete filters are applied in a sequential order, top to bottom. If you would like to change the order, please use `[Up] and [Down]`buttons.`` A `Unify` filter replaces all objects matched to the filter with a representative object. When an object included in two or more groups, the groups are merged.
Package Name Pattern | A string with a wild card character "`*`" to select objects by their package names. If you selected Yes in `Use Regex` column, you may use a regular expression.
Class Name Pattern | A string with a wild card character "`*`" to select objects by their class names. If you selected Yes in `Use Regex` column, you may use a regular expression.
Object IDs | You may directly select objects by a list of their IDs. For example, `-7,15-17,19,50-` selects objects 1-7, 15-17, 19, 50 and all objects whose ID is larger than 50. Note that "0" is a special ID to select static objects.
Use Regex | Please select "Yes" if you would like to use a regular expression in Name Pattern columns.

The below figure shows an object filter that `Hide`s objects whose ID is `0`. ScheduleList object in the diagram is a group object containing 7 objects.

Method Filters tab has a table to edit filters Fold/Hide/Delete method calls in a diagram.

These filters are almost same as object filters, but affect only an execution of a method. To add a filter, click on `[Add]` button on the right side of the tables. You can edit the following attributes.

Column | Value
--- | ---
Filter Type | You can select the type of a filter from `[Fold]`, `[Hide]` and `[Delete]`. A `Fold` filter works in the same way as a double-click compresses a method execution. A `Hide` filter hides a method execution, but adds indirect method calls for transitive method calls. A `Delete` filter completely remove objects and related method calls. When a method X calls Y, Y calls another method Z, a Hide filter removing Y from a diagram shows an indirect method call from X to Z. A Delete filter removing Y removes transitive method calls between X and Z. Method filters are applied in a sequential order, top to bottom. If you would like to change the order, please use `[Up] and [Down]`buttons.``
Timestamps | This value directly select method call events by a list of their timestamps. This is same as Object IDs, for example, `1,2,10-20` selects method calls whose timestamps are involved in 1, 2 and 10 to 20.
Package Name | A string with a wild card character "`*`" to select objects by their package names. If you selected Yes in `Use Regex` column, you may use a regular expression.
Class Name | A string with a wild card character "`*`" to select objects by their class names. If you selected Yes in `Use Regex` column, you may use a regular expression.
Method Name | A string with a wild card character "`*`" to select objects by their method names. If you selected Yes in `Use Regex` column, you may use a regular expression.
Object IDs | This value select objects by a list of their IDs. For example, `-7,15-17,19,50-` selects objects 1-7, 15-17, 19, 50 and all objects whose ID is larger than 50. Note that "0" is a special ID to select static objects.
Use Regex | Please select "Yes" if you would like to use a regular expression in Package, Class and Method Name columns.

The following figure is the result of a `Fold` filter that compresses method calls whose timestamps are `10-20`.