The jqassistant-c4-plugin integrates the two open-source projects jQAssistant and C4-PlantUML with each other.
With the plugin, it is possible to scan PlantUML files (.puml) that contain one of the following diagram types from the C4-Model :
-
Context Diagram
-
Container Diagram
-
Component Diagram
With that, the documented architecture can be enriched in the software graph created by jQAssisstant. The ability to scan C4 diagrams also allows to validate the as-is architecture (implemented structures) against the to-be architecture (documented architecture).
To be able to use the plug-in, it must be speified as a plug-in to jQAssistant. Additionally, it must be configured as a scan-include where jQAssistant can find the .puml-files.
|
Note
|
The versions of jQAssistant and the plugin needs to be set accordingly. |
|
Note
|
In this example, the .puml-files reside in documentation/c4.
|
jqassistant:
plugins:
- group-id: org.jqassistant.plugin (1)
artifact-id: jqassistant-c4-plugin
version: ${jqassistant.c4-plugin.version}
scan:
include:
files:
- ${project.basedir}/documentation/c4</path> (2)-
Dependency to the C4 plugin
-
Location of the
.puml-files
The C4 Model describes multiple different building blocks on different abstraction levels. The plugin for jQAssistant has support for building blocks coming from the following abstractions:
-
Context Diagram
-
Container Diagram
-
Component Diagram
As the C4-PlantUML integration is used, this means that the jqassistant-c4-plugin can parse the elements listed at C4-PlantUML for the aforementioned diagrams, i.e.:
-
Context Diagram
-
Person(alias, label, ?descr, ?sprite, ?tags, $link)
-
Person_Ext(…)
-
System(alias, label, ?descr, ?sprite, ?tags, $link)
-
SystemDb(…)
-
SystemQueue(…)
-
System_Ext(…)
-
SystemDb_Ext(…)
-
SystemQueue_Ext(…)
-
Boundary(alias, label, ?type, ?tags, $link)
-
Enterprise_Boundary(alias, label, ?tags, $link)
-
System_Boundary(…)
-
-
Container Diagram
-
Container(alias, label, *techn, ?descr, ?sprite, ?tags, $link)
-
ContainerDb(…)
-
ContainerQueue(…)
-
Container_Ext(…)
-
ContainerDb_Ext(…)
-
ContainerQueue_Ext(…)
-
Container_Boundary(alias, label, ?tags, $link)
-
-
Component Diagram
-
Component(alias, label, *techn, ?descr, ?sprite, ?tags, $link)
-
ComponentDb(…)
-
ComponentQueue(…)
-
Component_Ext(…)
-
ComponentDb_Ext(…)
-
ComponentQueue_Ext(…)
-
Additionally, following relation types are supported:
-
Rel(from, to, label, ?techn, ?descr, ?sprite, ?tags, $link)
-
Rel_U(…), Rel_Up(…)
-
Rel_D(…), Rel_Down(…)
-
Rel_L(…), Rel_Left(…)
-
Rel_R(…), Rel_Right(…)
-
BiRel(from, to, label, ?techn, ?descr, ?sprite, ?tags, $link)
-
BiRel_U(…), BiRel_Up(…)
-
BiRel_D(…), BiRel_Down(…)
-
BiRel_L(…), BiRel_Left(…)
-
BiRel_R(…), BiRel_Right(…)
Additionally, properties are also supported:
-
AddProperty(col1, col2)
Following elements are supported by being ignored during parsing, i.e. not leading to data enrichment in the graph:
-
SHOW_LEGEND(…)
Notice the list of parameters above. Parameter swith a * (optional list), ? (optional), and $ are also supported.
By default, the order as documented is expected.
However, C4-PlantUML supports also skipping in-between optional parameters and shuffling of the parameter order.
This is done by always specifying the name of the parameter with it’s value as shown in the example below and is also supported by the jqassistant-c4-plugin:
Component($label=alias, $alias=label, "Tech", $descr = "asjsa", $tags="abab", $sprite="ababa")The :File-node representing the .puml-file will have a label :C4 added for moe convenient filtering.
Furthermore, an outgoing relation :CONTAINS will be created to a :C4:Diagram-node.
From this node, all building blocks will be reachable via a :HAS relation.
For each building block, a new node in the graph is created. Following labels will be added to them:
Primary Type |
Secondary Type |
Labels |
Person |
|
|
Boundary |
|
|
Enterprise |
Boundary |
|
System |
|
|
DB |
|
|
Queue |
|
|
Boundary |
|
|
Container |
|
|
DB |
|
|
Queue |
|
|
Boundary |
|
|
Component |
|
|
DB |
|
|
Queue |
|
|
Note
|
Each building block can have a $tags parameter, which is a +-separated list. All elements from this will be used as additional labels.
|
|
Note
|
The Boundary(…) building block has a $type parameter, which will be also used as additional label.
|
Following properties will be transferred to the nodes and relations, respectively:
-
alias (String)
-
name (String)
-
description (String)
-
technologies (String[])
-
external (boolean)
-
This property is based on the specification of _Ext when declaring the building block in PlantUML
-
For each relation specified, a relation will be created between the listed building blocks.
By default, if nothing is specified, this will have the label :DEPENDS_ON.
If, however, one specified the $tags-parameter, the first tag in the potentially comma-seperated list will be applied.
In case the BiRel is used, two relations will be created between the two building blocks, one in each direction.
For each building block containing another building block, a :CONTAINS will be created between them.
Once the jqassistant-c4-plugin is integrated and configured as shown above, all available .puml-files will be considered for scanning automatically during the execution of jQAssistant.
Since a PlantUML diagram could contain something else than a C4 diagram, the plugin checks if the file contains one of the following statements:
-
!include <C4/C4_Context> -
!include <C4/C4_Container> -
!include <C4/C4_Component>
|
Note
|
The jqassistant-c4-plugin uses a custom ANTLR-grammar.
Thus, parsing will fail when using anything else than the elements documented above (building blocks, properties, relations, preprocessor-statements (lines starting with !), @startuml, @enduml).
This was done to enforce the diagrams to be kept simple and to reduce the complexity of the grammar.
|