JarCasting
Highwheel-Modules
Highwheel modules is an extension of the class dependency visualisation tool Highwheel by Henry Coles to express, measure and verify the structure and the design of Java projects.
In general it is reasonable to expect that Java project are organised in logical entities (or modules) that serve a specific concern: a module is used to contain the core business logic of the application, a module is used to accomodate the outer interface through a web api, a module is used to contain the clients to connect to persistent storage devices and external services etc. Highwheel modules offers:
- A language to describe and define software modules and the relation between them (module specification).
- An analysis scanner that takes the classes of a project and fits them in the defined modules.
- A dependency calculator that determines if the provided module specification is observed by the project or not.
- Command line tool and a maven plugin to apply validate the specification.
- Measurement of architectural metrics (fan-in and fan-out) useful to verify stability and abstractness of the modules.
Specification language
Highwheel-module specification language can be described by the following grammar in EBNF form:
Modules ::= ["prefix:" RegexLiteral "\n"]
["whitelist:" RegexLiteral{, RegexLiteral} "\n"]
["blacklist:" RegexLiteral{, RegexLiteral} "\n"]
["mode:" Mode]
"modules:" "\n"
{ ModuleDefinition }
"rules:" "\n"
{ RuleDefinition }
ModuleDefinition ::= ModuleIdentifier = RegexLiteral{ , RegexLiteral } "\n"
ModuleIdentifier ::= <java identifier>
RegexLiteral ::= "<glob regex>"
Mode ::= "STRICT" | "LOOSE"
RuleDefinition ::= DependencyRule | NoDependencyRule | OneToManyRule | ManyToOneRule
DependencyRule ::= <java identifier> "->" <java identifier> { "->" <java identifier> } "\n"
NoDependencyRule ::= <java identifier> "-/->" <java identifier>
OneToManyRule ::= <java identifier> "->" "(" <java identifier> {"," <java identifier>} ")"
ManyToOneRule ::= "(" <java identifier> {"," <java identifier>} ")" "->" <java identifier>
In order for a specification to be compiled correctly:
- At least one module needs to be defined.
- All the identifiers used in the rules section need to be defined in the modules section.
- The file needs to end with a new-line
An example of specification can be found in this project in the spec.hwm files of every project modules and would look like this:
prefix: "com.github.fburato.highwheelmodules."
modules:
Utils = "utils.*"
Core = "core.*"
Cli = "cli.*"
MavenPlugin = "maven.*"
Parser = "bytecodeparser.*"
Model = "model.*"
rules:
(MavenPlugin, Cli) -> Core
Core -> Parser
(Core, MavenPlugin, Cli, Parser, Model) -> Utils
(Core, Parser) -> Model
An equivalent way of providing the specification is to use the prefix preamble, which allows to automatically add to all module specification a prefix to compact the definition.
With the usage of prefix, the following definition:
modules:
Algorithms = "com.github.fburato.highwheelmodules.core.algorithms.*"
ExternalAdapters = "com.github.fburato.highwheelmodules.core.externaladapters.*"
Specification = "com.github.fburato.highwheelmodules.core.specification.*"
ModuleAnalyser = "com.github.fburato.highwheelmodules.core.analysis.*"
Facade = "com.github.fburato.highwheelmodules.core.AnalyserFacade"
rules:
Facade -> (ModuleAnalyser, Specification, ExternalAdapters)
ModuleAnalyser -> Algorithms
Facade -/-> Algorithms
is equivalent to
prefix: "com.github.fburato.highwheelmodules.core."
modules:
Algorithms = "algorithms.*"
ExternalAdapters = "externaladapters.*"
Specification = "specification.*"
ModuleAnalyser = "analysis.*"
Facade = "AnalyserFacade"
rules:
Facade -> (ModuleAnalyser, Specification, ExternalAdapters)
ModuleAnalyser -> Algorithms
Facade -/-> Algorithms
Whitelisting and blacklisting of modules is also supported (as of 1.5.0). By specifying whitelist and blacklists in the specification, you can force Highwheel modules to focus only on certain classes or exclude certain classes from analysis respectively.
By whitelisting you are forcing the bytecode analyser to consider elements identified to be added to the dependency graph building algorithm only if they match any of the regexes in the whitelist.
By blacklisting, you are forcing the bytecode analyser to ignore elements identified to be added to the dependency graph building algorithm if they match any of the regexes in the blacklist.
Modes of operation
Highwheel modules supports two modes of operation: strict and loose.
When running on strict mode, the rules are interpreted as follows:
A -> Brequires that there must exist a direct dependency between a class in moduleAand a class in moduleB. The rule is violated if there is no such dependency or ifAdepends onBindirectly through other modulesA -/-> Brequires that ifBis reachable fromAthen there is no explicit dependency between classes ofAand classes ofB. The rule is violated if there is such a direct dependency.
Moreover, a strict analysis fails if there are dependencies in the actual dependency graph calculated from the bytecode that do not appear in the specification. Basically a strict analysis requires the entire dependency graph to be explicitly written in the specification in order for it to pass.
It is an analysis mode suggested to identify circular dependencies (i.e. if there is no such rule as A -> A in the specification but the circular dependency on A exists, the analysis will fill) and to enforce strong design decisions.
When running on loose mode, the rules are interpreted as follows:
A -> Brequires thatBis reachable fromAin any way. The rule is violated ifBis not reachable fromAA -/-> Brequires thatBis not reachable fromAin any way. The rule is violated ifAdepends onB
Basically, the loose analysis is a whitelisting and blacklisting analysis: certain dependency are allowed to exist and certain are not.
It is an analysis mode suggested to ensure very specific properties in the dependency graph and not the entire structure of it.
In order to use the loose analysis mode, specify the mode in the specification file as follows.
prefix: "com.github.fburato.highwheelmodules.core."
mode: LOOSE
modules:
Algorithms = "algorithms.*"
ExternalAdapters = "externaladapters.*"
Specification = "specification.*"
ModuleAnalyser = "analysis.*"
Facade = "AnalyserFacade"
rules:
Facade -> (ModuleAnalyser, Specification, ExternalAdapters)
ModuleAnalyser -> Algorithms
Facade -/-> Algorithms
The default mode is STRICT, but the mode can be explicitly indicated with mode: STRICT in the same position.
Command line tool
The highwheel modules command line tool is contained in the module cli. In order to build the tool just build the entire project with
mvn clean install
The executable jar will be available at cli/target/modulesAnalyser-jar-with-dependencies.jar.
Using the command line tool
The command line tool base syntax is
java -jar moduleAnalyser-jar-with-dependencies.jar <directories and jar to analyse>
The tool will:
- Read a module specification file named
spec.hwmin the current working directory and compile it, reporting any errors. - Read all
*.classfiles in the directories and jars passed as argument - Start a strict analysis using the specification read from
spec.hwmon the resources passed. - Provide the result of the analysis and the fan-in/fan-out measurement on all modules.
It is possible to change both the specification file and the mode with the following options:
--spec | -s: path to the specification file to use. Add multiple of these options to include more specification in the analysis.
Highwheel modules maven plugin
The highwheel modules maven plugin is contained in the module maven-plugin. In order to build the tool, just build the entire project with:
mvn clean install
Using the plugin
In order to run the plugin on a project execute:
mvn com.github.fburato:highwheel-modules-maven-plugin:analyse
You can also run a specific version of the plugin without including it in your build with:
mvn com.github.fburato:highwheel-modules-maven-plugin:1.6.1:analyse
The plugin will:
- Read a module specification file named
spec.hwmin the project base-directory and compile it, reporting any errors. - Read all
*.classfiles in the project output directory (target/classes) - Start a strict analysis using the specification read from
spec.hwmon the resources passed. - Provide the result of the analysis and the fan-in/fan-out measurement on all modules.
- The build will fail if any of the rules are violated
It is possible to change the behaviour of the plugin as follows:
-DhwmSpecFiles=<comma separated list of paths to spec files>: use the paths provided instead ofspec.hwmfrom the base dir if the path is relative, otherwise use the path as is if the path is absolute.-DhwmChildOnly=true: in a multi-module build, run the analysis only on the child modules (skips pom packaging modules).-DhwmParentOnly=true: in a multi-module build, run the analysis only on the parent (skips non-pom packaging modules).-DhwmEvidenceLimit=<integer>: limit the pieces of evidence that are displayed when the analysis fails (i.e. code dependencies between the modules that make the dependency hold or not hold).
In a multi-module build, the plugin will use all the child output directories as elements of the analysis.
If you want to prevent one module from being analysed, add the <hwmSkip>true</hwmSkip> property to the configuration of the plugin.
Add the plugin to your build
Add the following dependency to your build/plugins section:
<dependency>
<groupId>com.github.fburato</groupId>
<artifactId>highwheel-modules-maven-plugin</artifactId>
<version>1.6.2</version>
</dependency>
And configure it to run the appropriate phase.