Generate HTML reports from Asciidoc documents including rules and embed results as tables, diagrams or CSV files.
Note
|
This tutorial is written for version 1.8.0 of jQAssistant. |
1. Overview
Rules (i.e. concepts and constraints) may be embedded into Asciidoc files. jQAssistant executes these rules and renders the documents to HTML with embedded results.
By default the results are represented as tables but it is possible to specify different report types:
plantuml-component-diagram
-
Nodes and relationships of the result are converted to a PlantUML component diagram and rendered to an SVG file.
plantuml-class-diagram
-
Nodes representing Java packages, classes, fields or members and their connecting relations are converted to a PlantUML class diagram which is rendered to an SVG file.
plantuml-sequence-diagram
-
Path structures of the result are converted to a PlantUML sequence diagrams which is rendered to an SVG file.
Note
|
For rendering PlantUML diagrams Graphviz needs to be installed and the dot executable available via the system path.
|
Furthermore a report type may be chosen for creating a file of a dedicated format which then will be shown as link:
Tip
|
Usually concepts are used for creating reports as they represent your chosen design & architecture language. |
For this tutorial the following project structure is going to be used:
your.project (1)
your.project.a (2)
your.project.b
your.project.c
-
The root package of the project is
your.project
. -
A package located directly within the root package represents a
Module
. The project consists of the modulesa
,b
andc
whereb
andc
contain Java types depending on types located ina
.
The structure and the metrics of this project shall be continuously reported within each build.
2. Integrate jQAssistant Into The Build Process
The tutorial uses Apache Maven for building the project.
jQAssistant is enabled by adding the plugin to the build/plugins section of the file pom.xml
.
<properties>
<jqassistant.version>1.8.0</jqassistant.version>
</properties>
<build>
<plugins>
<plugin>
<groupId>com.buschmais.jqassistant</groupId>
<artifactId>jqassistant-maven-plugin</artifactId>
<version>${jqassistant.version}</version>
<executions>
<execution>
<id>default</id>
<goals>
<goal>scan</goal>
<goal>analyze</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
Tip
|
To verify the setup a build should be triggered using mvn verify .
The build should succeed and show a console output should containing jQAssistant’s scan and analysis messages.
|
The rules are embedded in Asciidoc documents which are located in the folder jqassistant/
:
jqassistant/index.adoc (1)
jqassistant/module.adoc (2)
jqassistant/metrics.adoc (3)
-
index.adoc: the document used for rendering by Asciidoctor, it contains include directives for both other documents.
-
module.adoc: reports about the project’s module structure as tables, diagrams and GraphML files.
-
metrics.adoc: rules for collecting and reporting metrics as tables and CSV documents.
Tip
|
The file index.adoc is picked up by jQAssistant by default for rendering to HTML.
It must contain at least one rule, usually this is a group declaration.
The rendered HTML documents are located in the folder target/jqassistant/report/asciidoc .
|
3. Structural Reports
3.1. Tables
The file module.adoc
defines concepts related to the module structure of the project and for generating reports in different representations.
A concept module:Module
first adds a label Module
to each child package of the root package your.project
:
[[module:Module]] [source,cypher,role=concept] .All packages in the root package of the main artifact are labeled as `Module`. ---- MATCH (:Main:Artifact)-[:CONTAINS]->(root:Package)-[:CONTAINS]->(module:Package) WHERE root.fqn = "your.project" SET module:Module RETURN module.name as Module, module.fqn as Package ORDER BY module.name ----
The returned result defines two columns Module
(the name of the module) and Package
.
As no report type is specified for this concept its result is rendered to a table containing these columns:

3.2. Component Diagrams
The concept module:Dependencies
which is based on module:Module
aggregates the type dependencies to the module packages:
[[module:Dependencies]] [source,cypher,role=concept,requiresConcepts="module:Module",reportType="plantuml-component-diagram"] .A module depends on another module if there is a dependency of Java types between both. ---- MATCH (module1:Module)-[:CONTAINS*]->(t1:Type), (module2:Module)-[:CONTAINS*]->(t2:Type), (t1)-[:DEPENDS_ON]->(t2) WHERE module1 <> module2 WITH module1, module2, COUNT(*) AS weight MERGE (module1)-[dependsOn:DEPENDS_ON_MODULE]->(module2) SET dependsOn.weight = weight RETURN module1, dependsOn, module2 ----
This concept returns the modules (module1, module2) and their dependency relations (dependsOn).
The result is used for generating a component diagram by setting the reportType
attribute to plantuml-component-diagram
.

Tip
|
The generated .plantuml and .svg files are located in the folder target/jqassistant/report/plantuml .
|
3.3. GraphML Files
If diagrams become more complex it may be useful to export them as GraphML documents.
This can be achieved by setting the report type graphml
as illustrated by the concept module:DependenciesGraphML
:
[[module:DependenciesGraphML]] [source,cypher,role=concept,requiresConcepts="module:Dependencies",reportType="graphml"] .Modules and their dependencies as GraphML report. ---- MATCH (module:Module) OPTIONAL MATCH (module)-[dependsOn:DEPENDS_ON_MODULE]->(:Module) RETURN * ----
The HTML document will provide a link to the GraphML file:

Tip
|
The generated .graphml files are located in the folder target/jqassistant/report/graphml .
They may be viewed using yEd.
After opening a file you need to apply a layout, Layout→Hierarchical (Alt-Shift-H).
|

By extending the result structure the GraphML reports may be used to allow an interactive drill-down from module to type level:
[[module:DependenciesGraphMLDrilldown]] [source,cypher,role=concept,requiresConcepts="module:Module",reportType="graphml"] .Modules and their dependencies as GraphML report with drill-down to type level. ---- MATCH (module:Module)-[:CONTAINS*]->(type:Type) OPTIONAL MATCH (type)-[dependsOn:DEPENDS_ON]->(:Type)<-[:CONTAINS*]-(:Module) RETURN { role: "graph", parent: module, nodes: collect(type), relationships: collect(dependsOn) } ----
This concept returns a graph for each module which is rendered as parent
containing types (nodes
) and dependencies (relationships
) per module.
The generated GraphML report file can be interactively explored in yEd by expanding (+
) or collapsing (-
) module nodes and applying the horizontal layout:

3.4. Class Diagrams
Java structures returned by a rule may be rendered to class diagrams. The following elements are supported:
-
Packages (
:Java:Package
) -
Types (
:Java:Type
) -
Members (
:Java:Member
,:Java:Field
,:Java:Method
) -
Inheritance relations between types (
:EXTENDS
,:IMPLEMENTS
) -
any other relations between types (rendered as associations)
The concept module:ClassDiagram
returns all types including their optional fields and methods:
[[module:ClassDiagram]] [source,cypher,role=concept,requiresConcepts="module:Module",reportType="plantuml-class-diagram"] .Class Diagram ---- MATCH (module:Module:Package)-[:CONTAINS*]->(type:Type) OPTIONAL MATCH (type)-[extends:EXTENDS|IMPLEMENTS]->(:Type) OPTIONAL MATCH (type)-[:DECLARES]->(field:Field) OPTIONAL MATCH (type)-[:DECLARES]->(method:Method) RETURN * ----
As the report type is set to plantuml-class-diagram
the following diagram is rendered and embedded into the HTML document:

3.5. Sequence Diagrams
A rule returning a path structure in a column named sequence
can be rendered to sequence diagrams by setting the report type to plantuml-sequence-diagram
:
[[module:SequenceDiagram]] [source,cypher,role=concept,reportType="plantuml-sequence-diagram"] .Sequence Diagram ---- MATCH (:Type{name:"ServiceCImpl"})-[:DECLARES]->(method:Method{name:"run"}), sequence=((method)-[:INVOKES*]->(:Method)) RETURN sequence ----
The nodes of the sequence are interpreted as participants and the relationships between them as messages. This results in the following diagram to be generated:

4. Metrics
4.1. Tables
The results of concepts or constraints are rendered to tables by default.
This may be used to directly embed metrics into the HTML documents as illustrated by the concept metrics:LoCAndComplexity
located in metrics.adoc
:
[[metrics:Top10LoCAndCC]] [source,cypher,role=concept] .The top 10 types with the highest LoC (lines of code) and aggregated CC (cyclomatic complexity). ---- MATCH (:Artifact)-[:CONTAINS]->(type:Type)-[:DECLARES]->(method:Method) RETURN type AS Type, sum(method.cyclomaticComplexity) AS CC, sum(method.effectiveLineCount) AS LoC ORDER BY LoC DESC, CC DESC LIMIT 10 ----
The HTML document will contain the following table:

4.2. CSV Reports
It may be useful to provide metrics as a CSV files for further analysis in other tools.
Fur such cases the report type csv
may be specified:
[[metrics:Top10LoCAndCCAsCSV]] [source,cypher,role=concept,reportType="csv"] .The top 10 types with the highest LoC (lines of code) and CC (cyclomatic complexity). ---- MATCH (:Artifact)-[:CONTAINS]->(type:Type)-[:DECLARES]->(method:Method) RETURN type AS Type, sum(method.cyclomaticComplexity) AS CC, sum(method.effectiveLineCount) AS LoC ORDER BY LoC DESC, CC DESC LIMIT 10 ----
Instead of an embedded table a link to the generated CSV file will be rendered:

Tip
|
Generated .csv files are located in the folder target/jqassistant/report/csv .
|
The file can now be imported into tools providing support for CSV files:

5. Rules in XML files
jQAssistant rules may be located in Asciidoc or XML files.
The latter are not rendered to HTML but the results of concepts and constraints can be reported in a similar way as described in the previous sections.
This can be achieved by adding a <report>
element with a type
attribute:
<jqassistant-rules xmlns="http://schema.jqassistant.org/rule/v1.8">
<concept id="module-xml:DependenciesGraphML">
<description>Modules and their dependencies as GraphML report.</description>
<cypher><![CDATA[
MATCH
(module:Module)
OPTIONAL MATCH
(module)-[dependsOn:DEPENDS_ON_MODULE]->(:Module)
RETURN
*
]]></cypher>
<report type="graphml" />
</concept>
</jqassistant-rules>
The generated files will be located in the according sub-directories of target/jqassistant/report
.