ESSeRE Lab Arcan – ARChitecture ANalyzer

Arcan – ARChitecture ANalyzer

Arcan is a Java software analysis tool, supporting the detection of architectural smells. Currently, it supports the following three architectural smells (AS):

  • Unstable Dependency: describes a subsystem (component) that depends on other subsystems that are less stable than itself. Subsystems affected by this may cause a ripple effect of changes in the system .
  • Hub-Like Dependency: this smell arises when an abstraction has (outgoing and ingoing) dependencies with a large number of other abstractions.
  • Cyclic Dependency: refers to a subsystem (component) that is involved in a chain of relations that break the desirable acyclic nature of a subsystems dependency structure. The subsystems involved in a dependency cycle can be hardly released, maintained or reused in isolation.

Reference

Arcelli Fontana, Francesca, Ilaria Pigazzini, Riccardo Roveda, and Marco Zanoni. 2016. “Automatic Detection of Instability Architectural Smells.” In Proceedings of the 32nd International Conference on Software Maintenance and Evolution (Icsme 2016). Raleigh, North Carolina, USA: IEEE. PDF

Arcelli Fontana, Francesca, Ilaria Pigazzini, Riccardo Roveda, Damian Andriew Tamburri, Marco Zanoni and Di Nitto Elisabetta.2017. “Arcan: a Tool for Architectural Smells Detection.” International Conference On Software Architecture (ICSA 2017). Gothenburg, Sweden, April 3-7, IEEE.PDF

Riccardo Roveda, Francesca Arcelli Fontana, Ilaria Pigazzini and Marco Zanoni, ​“Towards an Architectural Debt Index” in Proceedings of ​The Euromicro Conference on Software Engineering and Advanced Applications (SEAA 2018)​. doi: https://doi.org/10.1109/SEAA.2018.00073

Antonio Martini, Francesca Arcelli Fontana, Andrea Biaggi, Riccardo Roveda: Identifying and Prioritizing Architectural Debt Through Architectural Smells: A Case Study in a Large Software Company. ECSA 2018: 320-335. doi: https://10.1007/978-3-030-00761-4\_21

Please, in order to download Arcan write an email to :

  • arcelli <at> disco <dot> unimib <dot> it
  • ilaria <dot> pigazzini<at> unimib <dot> it

Requirements

Java 8

Arcan is available both from Terminal and GUI. Usage examples are presented below:

Arcan Terminal

AS Detection Example

Download Arcan from the download page. Arcan analyzes the project contained in my_project_location, stores the generated graph database at my_database_location, and performs the detection of all architectural smells (Cyclic Dependency, Hub-like dependency and Unstable dependency), with filtered results (saved in separated files), and computation of all metrics at class and package level (i.e. fan-in, CBO, LCOM), through the following command which will generate results reports (csv files) in the my_project_location/output folder:

 java -jar Arcan.jar -p my_project_location -neo4j -d my_database_location -all

Download Arcan from the download page. Arcan analyzes the project contained in my_project_location, and performs the detection of Unstable dependency, with filtered results, through the following command:

 java -jar Arcan.jar -p my_project_location -UD

Summarized Documentation of Terminal Commands

Few parameters are needed to run Arcan. To specify what project has to be analyzed, use option -p and add the folder which contains it. Arcan supports three different kinds of input: a folder of compiled java files, a jar file, and a folder of jar files. Use respectively options -CL, -JR and -FJ to set the input type.

The dependency graph resulting from the analysis can be stored in a database using the command -neo4j, otherwise a default in-memory one will be instantiated. Use command -d followed by the database location to save the graph in it (only Neo4j is supported currently), otherwise will stored inside in a folder inside the project path.

Once the project to analyze and the database folder are set, use the analysis options to choose which analyses should be performed: architectural smells and/or metrics.

The output csv files will be stored in a specified folder using the -out parameter, otherwise will be created by default a sub-folder in the project called output.

The tool supports the following main command line parameters:

  • Default:
    • -projectFolder, -p: The project folder (default is a folder of java classes)
    • -all: Calculates all metrics and all type of architectural smells
  • Architectural smells detection parameter:
    • -CycleDependency, -CD, -cd: Calculates the class and package cycles of the graph. If the graph is already written and it is specified the project folder it will be read from the db folder.
    • -HubLikeDependencies, -HL, -hl: Search for Hub-Like dependencies
    • -UnstableDependencies, -UD, -ud: Search for Unstable dependencies
  • Metric:
    • -ClassMetrics, -CM, -cm:: Compute the metrics on classes
    • -PackageMetrics, -PM, -pm: Compute Robert C. Martin metrics on packages
  • Project read configuration parameter:
    • -class, -CL, -cl: The project folder contains only classes
    • -folderOfJars, -FJ, -fj: The project folder contains only jars
    • -jar, -JR, -jr: The project to analyze is only one jar
  • Neo4j database parameter:
    • -neo4j: if set write the neo4j database
    • -neo4jDBFolder, -d: Database folder (default here_path\Neo4j\default.graphdb)
  • Output folder of CSV files:
    • -outputDir, -out: output dir of results
  • Other:
    • -log, -verbose, -v: Level of verbosity
    • -help, -h: Print this help

Use parameter -h to resume the command list with associated description. This is the result for Arcan:

 java -jar Arcan.jar -h

Arcan GUI

Video tutorial of Arcan GUI

Video tutorial of Arcan is available on YouTube:

Tutorial of Arcan GUI

Tutorial of Arcan:

Download Arcan from the download page. Select from welcome window Build new project:

Select a .jar file or a folder with .class files or .jar files. Indicate a name folder where save the data base. Indicate the path of the folder where the results of the computation will be saved (in csv file). (n.b. if database folder and output folder will be not indicated where chosen default location instead).

Press execute button of the architectural smells you need analyse and/or metrics you need compute.

File Output

Hub Like dependency

HL.csv file collect all the Hub Like architectural smells founded in the analyzed project.

  • Class: class name
  • FanIn: value of the FanIn metrics of the class
  • FanOut: value of the Fan Out metrics of the class
  • TotalDependency: total amount of dependency of the class

Example:

 HL.csv: Class,FanIn,FanOut,Total Dependences
         org.apache.hadoop.security.SecurityUtil,40,36,76
         ...

Unstable Dependency

UD.csv file collect all the Unstable Dependency architectural smells founded in the analyzed project. UD30.csv has the same structure of the UD.csv file but it contains only filtered results.

  • UnstableDependenciesPackage: package name with Unstable dependency
  • InstabilityUnstableDependenciesPackage: value of the Instability metrics of Robert C. Martin of the UnstableDependenciesPackage
  • CorrelatedPackage: package name of correlated to UnstableDependenciesPackage
  • InstabilityCorrelatedPackage: value of the Instability metrics of Robert C. Martin of the CorrelatedPackage

Example:

 UD.csv: UnstableDependenciesPackage,InstabilityUnstableDependenciesPackage,CorrelatedPackage,InstabilityCorrelatedPackage
         org.apache.hadoop.hdfs.server.namenode.metrics,0.6666666666666666,org.apache.hadoop.metrics2.source,0.6842105263157895
         ...

Cyclic Dependency

classCycleShapeTable.csv file collect all the Cyclic dependency architectural smells by shape founded in the analyzed project. The file packageCycleShapeTable.csv reports in addition packages cycles and the classes involved in the package cycle.

  • IdCycle: ID of the cycle (a number)
  • CycleType: shape of the cycle
  • MinWeight: min weight of all dependsOn edges
  • MaxWeight: max weight of all dependsOn edges
  • numVertices: number of vertex class type involved in the cycle
  • ElementList: list of the class involved in the cycle

Example:

 classCycleShapeTable.csv: IdCycle,CycleType,MinWeight,MaxWeight,numVertices,ElementList
                           3559,circle,1,12,3,"org.apache.hadoop.mapred.FileInputFormat,..."
                           ...

classCyclicDependencyMatrix.csv file collect all the Cyclic dependency architectural smells among two classes founded in the analyzed project. The file packageCyclicDependencyMatrix.csv is similar but at packages level.

  • Cycle: class name
  • ClassX: 0 if there isn’t a cycle, else 1

Example:

 classCyclicDependencyMatrix.csv: Cycle,Class1,Class2,...
                                  Class1,0,1...
                                  ...

classCyclicDependencyTable.csv file collect all the Cyclic dependency architectural smells among classes founded in the analyzed project. The file packageCyclicDependencyTable.csv is similar but at packages level.

  • Cycle: class id
  • ClassX: 0 if the class isn’t in the cycle, else 1

Example:

 classCyclicDependencyTable.csv: Cycle,Class1,Class2,...
                                 Cycle1,0,1...
                                 ...

Class Metrics

CM.csv file collect all the classes metrics of the analyzed project

Class: class name
FI: Fan In metric value of the class
FO: Fan Out metric value of the class
CBO: coupling between objects metric value
LCOM: Lack of Cohesion of Methods

Example:

CM.csv: Class,FI,FO,CBO,LCOM
org.apache.tools.ant.AntClassLoader$ResourceEnumeration,1,3,3,0.5833333333333334

Package Metrics

PM.csv file collect all the package metrics of the analyzed project

  • Package: Package Name
  • CA: Count Afferent classes of the package
  • CE: Count Efferent classes of the packege
  • RMI: Robert C. Martin instability metrics
  • RMA: Robert C. Martin abstraction metrics
  • RMD: Robert C. Martin Distance from the main sequence metrics

Example:

 PM.csv: Package,CA,CE,RMI,RMA,RMD
         org.apache.hadoop.hdfs.protocol,73,21,0.22340425531914893,0.12903225806451613,0.4844131200867443
         ...