ASTracker is a Java tool that parses Arcan's output and tracks the architectural smells detected in each versionString analysed by Arcan.
The requirements to install and execute the application are:
- JDK 11 (or newer)
- Maven 3 (3.6.0 is the one used, but other minor versions should work fine too)
The installation process is simple, but it requires git
and mvn
(Maven) to be installed on your system.
git clone https://github.com/darius-sas/astracker
cd astracker
mvn clean compile assembly:single -DskipTests=true
or, to run it as web service:
mvn spring-boot:run
This will compile the project and will create a astracker
directory within the ./target
directory.
The directory will contain a .jar
and a lib
folder, namely the executable and the necessary libraries.
ASTracker can be run as any standard executable .jar
file:
java -jar astracker.jar -help
This command will provide further information on the available commands.
As an example, try running the following command on the folder sample-data
, which contains the .grampml
, describing the Architectural smells affecting multiple versions of Antlr:
java -jar target/astracker-0.7-jar-with-dependencies.jar -i sample-data -p antlr -o sample-data -pC
Optionally, you can execute tests by running
./test-data/git-projects/clone-repos.sh # Clone test repositories on locally
mvn clean compile test
though ensure you have test-data
in the root directory of the project and that you clone all the necessary git repositories (using the handy script).
Test reports on coverage are available in target/site
and output logs are available in target/surefire
.
ASTracker is able to parse the .graphML
files produced by Arcan representing the system dependency graph and the detected smells.
In order to be able to detect the versionString of the system analysed,these files must conform to the following naming pattern:
<project-name>-<versionString>.graphml
The files must all have the same root directory, hence it is not necessary to have them all under the same folder.
ASTracker will recursively find all the .graphml
files in the given folder.
The versions release order shall respect the lexicographical order in order to guarantee a correct tracking.
ASTracker can also execute Arcan by itself and avoid you the trouble. The only requirement is to provide the input JAR files that conform to the same name convention mentioned for the .graphml
files.
The following input folder structures are supported by ASTracker in order to correctly provide the JAR files to Arcan:
input-folder
|-- <project-name>-version1
| |-- jar-name1.jar
| `- jar-nameN.jar
|-- <project-name>-version2
| |-- jar-name1.jar
| `-- jar-nameN.jar
...
input-folder
|-- jar-version1.jar
|-- jar-version2.jar
...
`-- jar-versionN.jar
By default two graph files will be output by ASTracker:
condensed-graph-consecOnly.xml
track-graph-consecOnly.xml
These files contain the same information, but in different formats, each suitable for different types of analyses. The information described are the architectural smells tracked starting from the first version to the final one. Additional information, such as architectural smells characteristics, are stored as node properties.
In order to print the properties as a single CSV file, the -pC
option can be added to the initial command line.
A file named smell-characteristics-consecOnly.csv
will also appear in the output directory.
This section briefly explains the general architecture of the AStracker and the responsibility of every component.
Explanation:
-
The Tracker module has the responsibility to track architectural smells throughout versions. This component has the following interfaces:
- ASTracker which is responsible of the actual logic for performing the tracking;
- SimilarityLinker which is responsible for the logic of establishing when two smells from two versions match (i.e. can be linked);
-
The Runners module contains all the code to perform an analysis as a whole on a given
Project
, for example to track the smells on that project or to also run Arcan on it; -
The Persistence module is responsible to write the relevant data to disk in order to save the results of the tracking and collect the necessary data; This module is designed with a "subscriber" design: data is sent to a central persistence writer (master), and if there are any specific writer subscribed to write that type of data (object), than such object is delivered to all subscribers. This allows for a flexible and lightweight management of output writing of data;
-
The Data module is the biggest module of ASTracker. All the data handled by ASTracker is modeled by this module:
- The Architectural smells sub-module contains all the models of the smells supported by ASTracker for tracking.
- The Characteristics sub-module contains the smells characteristics and component characteristics that are computed by ASTracker as a complementary task to the tracking of smells itself.
- The Project sub-module contains key components that abstract the project under analysis as versions and allow a client to retrieve the source code of a class/package/file of the analysed project starting from its
Vertex
in the dependency graph. Different project types require different implementations of theProject
andVersion
interfaces, though most of the functionality is common and dedicated abstract classes handled those aspect. These interfaces are mostly responsible of representing in-memory the project on the file system.
If you are here because you are looking for the dataset (and scripts) of our paper at ICSME'19 Investigating instability architectural smells evolution: an exploratory case study
, you can find it here. Scripts to read and plot the data are instead here.