Merge branch 'master' of https://github.com/tobias-dv-lnu/s4rdm3x

.gitignore

@@ -0,0 +1,3 @@
+.gradle
+build
+

JOSS-paper/paper.md

@@ -28,7 +28,10 @@ bibliography: paper.bib
 
 Architectural drift and erosion, where the implementation starts to deviate from the intended software architecture or the rules set by it, are common problems in long-lived software systems. This can be avoided by using techniques, such as Reflexion modeling [@murphy1995software], to validate that the implementation conforms to the indented architecture. Unfortunately, such techniques require a mapping from source code modules (e.g., classes) to elements of the architecture, something that is not always available or up to date. This is a known problem when, e.g., companies want to adopt static architecture conformance checking; the effort to manually create or bring this mapping up to date is just too time-consuming and error-prone [@Ali2017ArchitectureRequirements; @InfoRetrieval].
 
-The ``s4rdm3x`` tool suite is designed for researchers and practitioners to study and evaluate algorithms that perform part of the mapping automatically, such as orphan-adoption clustering [@HuGMe] or information retrieval techniques [@InfoRetrieval]. It includes a graphical user interface to define the architecture, define and run experiments with mapping algorithms and their parameters, and visualize and explore the results of these experiments. The experiments can be executed locally or in a remote high-performance computing environment. The tool suite includes reference implementations of state of the art mapping algorithms and a set of Java systems with validated mappings between classes and architecture elements. The tool suite is extensible, so it is easy to add new mapping algorithms and visualizations to explore their performance.
+The ``s4rdm3x`` tool suite is designed for researchers and practitioners to study and evaluate algorithms that perform part of the mapping automatically, such as orphan-adoption clustering [@HuGMe] or information retrieval techniques [@InfoRetrieval]. It includes a graphical user interface to define and run experiments with mapping algorithms and their parameters, and visualize and explore the results of these experiments. The experiments can be executed locally or in a remote high-performance computing environment. The tool suite includes reference implementations of state of the art mapping algorithms and a set of Java systems with validated mappings between classes and architecture elements. The tool suite is extensible, so it is easy to add new mapping algorithms and visualizations to explore their performance.
+
+# Statement of Need
+To faciliate the further development and evaluiation of mapping techniques the software provides reference implementations of the current state-of-the-art mapping techniques and the means to implement new techniques and run experiments. It includes the HuGMe orphan adoption clustering method [@HuGMe], and four attraction functions to decide which architectural element a source code module should be mapped to: `CountAttract` [@HuGMe], `IRAttract`, `LSIAttract` [@InfoRetrieval] and `NBAttract` [@NaiveBayes]. There is also a reference implementation of our novel technique to create a textual representation of source code dependencies at an architectural level; Concrete Dependency Abstraction (CDA). It also contains a set of validated mappings between source code classes and architectural elements that are often used in software architecture erosion research. These systems have either been recovered from replication packages [@brunet2012evolutionary; @LenhardExploringSCMIndicatingArchInconsistency] or the [SAEroCon workshop repository](https://github.com/sebastianherold/SAEroConRepo). 
 
 # The ``s4rdm3x`` Tool Suite
 
@@ -42,7 +45,7 @@ The *graphical editor* is used to define, visualize, analyze, and compare how we
 
 The graphical editor can be used to run experiments, but these generally require a large number of combinations of, e.g., parameters, initial sets, and systems, so they can take a long time to run. The suite includes a command-line tool that runs these combinations in parallel on many-core machines. The command-line tool can read experiment definitions in XML exported from the graphical editor and save the results in a format that can be imported and visualized.
 
-The tool suite includes reference implementations of the most common mapping algorithms, such as the HuGMe orphan adoption clustering method [@HuGMe], and four attraction functions to decide which architectural element a source code module should be mapped to: `CountAttract` [@HuGMe], `IRAttract`, `LSIAttract` [@InfoRetrieval] and `NBAttract` [@NaiveBayes]. There is also a reference implementation of our novel technique to create a textual representation of source code dependencies at an architectural level; Concrete Dependency Abstraction (CDA). It also contains a set of Java systems with validated mappings between source code classes and architectural elements that are often used in software architecture erosion research. These systems have either been recovered from replication packages [@brunet2012evolutionary; @LenhardExploringSCMIndicatingArchInconsistency] or the [SAEroCon workshop repository](https://github.com/sebastianherold/SAEroConRepo).
+
 
 ``S4rdm3x`` is implemented in Java and depends on [ASM](https://asm.ow2.io), [Weka](https://www.cs.waikato.ac.nz/ml/weka), and [Dear JVM ImGui](https://github.com/kotlin-graphics/imgui).
 

README.md

@@ -10,16 +10,16 @@
 
 
 # s4rdm3x
-A tool suite to perform experiments in automatic mapping of source code to modular architecure definitions, also called the orphan adoption problem. It consists of a reusable base code (core) and two tools (v3xt & CMDExRunner).
+A tool suite to perform experiments in automatic mapping of source code to modular architecture definitions, also called the orphan adoption problem. It consists of a reusable base code (core) and two tools (v3xt & CMDExRunner).
 
 ## core
 The base code provides Java bytecode analysis to extract a dependency graph (and naming information) as well as loading an architectural definition and source to module mapping. Furthermore it implements the HuGMe method and four attraction functions to map a source code file to an architectural module. The attraction functions are CountAttract, IRAttract, LSIAttract and NBAttract.
 
 ## v3xt
-A tool that provides a GUI to define and run small scale experiments as well as visualize the results in real-time. This can be used to quickly try and asses new ideas and define larger experiments. Supports loading and saving of experiments definitions as experiments.
+A tool that provides a GUI to define and run small scale experiments as well as visualize the results in real-time. This can be used to quickly try and assess new ideas and define larger experiments. Supports loading and saving of experiments definitions as experiments.
 
 ## CMDExRunner
-A command line tool for executing experiments in parrallell. It reads an experiment definition xml-file and distributes the experiments over a number of threads. Typically useful for running experiments in multicore computing clouds.
+A command line tool for executing experiments in parallel. It reads an experiment definition xml-file and distributes the experiments over a number of threads. Typically useful for running experiments in multicore computing clouds.
 
 # Documentation
 Documentation is available in [docs](docs) and published: https://tobias-dv-lnu.github.io/s4rdm3x/
@@ -33,7 +33,7 @@ Released under
 GNU GENERAL PUBLIC LICENSE Version 3, 29 June 2007
 https://www.gnu.org/licenses/gpl-3.0.html
 
-See LICENCE for furher details
+See LICENCE for further details
 
 
 

docs/index.md

@@ -21,6 +21,10 @@ A command line tool for executing experiments in parrallell. It reads an experim
 # Installation
 Download the latest [Release](https://github.com/tobias-dv-lnu/s4rdm3x/releases) from GitHub, it includes precompiled versions of the tools as jar applications for all plattforms.
 
+# Prerequisites
+
+- Java 11 or superior
+
 # Running
 Run via commandline:
 
@@ -37,7 +41,12 @@ Check the included readme for further details.
 ## Data Systems
 S4rdm3x is distributed with architectural models and source code to implementation mappings for a number of systems (see the data/systems directory). Models and mappings are based on work during the [SAEroCon workshop](https://saerocon.wordpress.com/) and a replication package provided by Joao Brunet et. al. [On the Evolutionary Nature of Architectural Violations](https://code.google.com/archive/p/on-the-nature-dataset/wikis/ReplicabilityOfTheStudy.wiki)
 
-To complement the models and mappings, the actual compiled systems are also needed (i.e. jar files). These are not included in this distribution as this would create a problematic licensing situation. However, the jar file dependencies are documented in the respective model file and should be available by either looking through the links from the sources above, or finding them in the actual official distributions of the systems.
+To complement the models and mappings, the actual compiled systems are also needed (i.e. jar files). These are not included in this distribution as this would create a problematic licensing situation. However, the jar file dependencies are documented in the respective model file and should be available by either looking through the links from the sources above, or finding them in the actual official distribution of the systems.
+
+### Some Official Distributions
+* [JabRef-3.7.jar](https://github.com/JabRef/jabref/releases/tag/v3.7)
+* [ProM 6.9](http://www.promtools.org/doku.php?id=prom69)
+
 
 ## How To Use It
 The release contains a ready to use test experiment as explained in the release README