Tutorial
Document Actions
Tutorial describing the use of AURA.
Introduction
AURA is a tool to identify framework evolution. It combines call-dependency and text similarity analyses in a multi-iteration algorithm to detect change rules from old versions to new versions of a program. It is able to automatically generate one-to-one, many-to-one, one-to-many and simply-deleted rules.
AURA includes two components:
AURA Model Builder: It converts the source code of the old version and the new version of a program to a language-independent model (AURA Model), used by AURA Rule Generator to identify the change rules. The current version of AURA Model Builder is an Eclipse plugin.
AURA Rule Generator: It generates change rules according to AURA Model. It can be used both as an Eclipse plugin and as a standalone java program.
System Requirement
1. JRE 1.6
2. Eclipse 3.5
Installation
Please see the download page to access the following files:
1. Eclipse Plugin: Download AURA-plugin.zip and extract it to the Eclipse directory, then restart Eclipse.
2. Standalone Rule Generator: Download AURA-RuleGenerator.zip and extract it to the directory where it supposed to be installed.
Usage
1. Create AURA Task Config File:
Build AURA Task Config File as an xml file with the following content:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<configurations>
<!-- The directory where the analysis result is saved -->
<workingDirectory>D:\MIneSweeperTest\jEdit\</workingDirectory>
<!-- The name of the old version project of Eclipse of the program to be analyzed -->
<!-- It must be in the current workspace -->
<oldVersionProject>jEdit_4.1</oldVersionProject>
<!-- Reserved field, Don't change -->
<oldVersionWihtNewFramework></oldVersionWihtNewFramework>
<!-- The name of the new version project of Eclipse of the program to be analyzed -->
<!-- It must be in the current workspace -->
<newVersionProject>jEdit_4.2</newVersionProject>
<!-- Reserved field, Don't change -->
<operation>modelBuilding</operation>
</configurations>
2. Set proper maximum heap size: <configurations>
<!-- The directory where the analysis result is saved -->
<workingDirectory>D:\MIneSweeperTest\jEdit\</workingDirectory>
<!-- The name of the old version project of Eclipse of the program to be analyzed -->
<!-- It must be in the current workspace -->
<oldVersionProject>jEdit_4.1</oldVersionProject>
<!-- Reserved field, Don't change -->
<oldVersionWihtNewFramework></oldVersionWihtNewFramework>
<!-- The name of the new version project of Eclipse of the program to be analyzed -->
<!-- It must be in the current workspace -->
<newVersionProject>jEdit_4.2</newVersionProject>
<!-- Reserved field, Don't change -->
<operation>modelBuilding</operation>
</configurations>
Depends on the size of the program to be analyzed, we need to set the heap sized of Java VM to proper value. Here are the values of heap size used during our evaluation:
-Xmx1096m for JEdit, JFreeChart, JHotDraw and Struts
-Xmx8000m for org.eclipse.jdt.core and org.eclipse.jdt.ui
To set the heap size of Eclipse, modify the
eclipse.ini in eclipse directory as follows (set the last two rows to
proper values):-Xmx8000m for org.eclipse.jdt.core and org.eclipse.jdt.ui
-startup
plugins/org.eclipse.equinox.launcher_1.0.201.R35x_v20090715.jar
--launcher.library
plugins/org.eclipse.equinox.launcher.win32.win32.x86_1.0.200.v20090519
-showsplash
org.eclipse.platform
-vmargs
-Xms1096m
-Xmx1096m
plugins/org.eclipse.equinox.launcher_1.0.201.R35x_v20090715.jar
--launcher.library
plugins/org.eclipse.equinox.launcher.win32.win32.x86_1.0.200.v20090519
-showsplash
org.eclipse.platform
-vmargs
-Xms1096m
-Xmx1096m
3. Analyzing:
To analyze medium or samll programs such as Struts 1.1 and 1.2.4, it only takes a couple of minutes. We recommand to run Eclipse plugin version of AURA to perform both model building and change rule generating in the following steps:
Start Eclipse, click on menu AURA->Run All, choose AURA Task Config File to build models and to generate change rules.
To analyze large programs such as org.eclipse.jdt.core and org.eclipse.jdt.ui, it takes a couple of hours. So it is better to build AURA models with Eclipse plugin version, than run standalone AURA Rule Generator on a high-performance server as a background process.
Start Eclipse, click on menu AURA->Build Old Model, choose AURA Task Config File to build the old version model.
Repeat the the same operations with menu AURA->Build Old Model to build the new version model.
Run AURARuleGenerator.bat (on Windows) or AURARuleGenerator.sh (on Linux) in AURARuleGenerator directory with three parameters: working-dir old-version-AURA-model.xml new-version-AURA-model.xml to generate change rules.
4. Consult Change Rules:
The change rules are generated in two formats: plain text (.txt) and XML (.xml). The former is readable for human, the latter is supposed to be used by further automatic analyses. The description of the generated files:
| Description |
File Name (with .txt and .xml) |
| Complete change rule file | rules_Old-Version_New-version_Date |
| Abridged complete change rule file (without package names in return value and parameters): |
rules_Old-Version_New-version_Date_abridged_Date |
| The rules generated after X iterations of step 4a | rules_iter_NoX_Old-Version_New-version_Date |
| The rules generated after step 4b | x-to-many_rules_Old-Version_New-version_Date |
| The rules generated after step 4c | rules_by_name_invoc_Old-Version_New-version_Date |
| The rules generated after step 5 | rules_by_name_def_Old-Version_New-version_Date |
Uninstallation:
AURA can be deleted clearly without any leftover on your system.
1. Eclipse plugin: Delete AURA_*.jar from Eclipse plugins directory.
2. Standalone Rule Generator: Delete AURARuleGenerator.jar, AURARuleGenerator.bat and AURARuleGenerator.sh.
