Das Dokument behandelt die Implementierung von Architekturkonzepten und Designvorgaben mithilfe von jqassistant und Asciidoc zur automatisierten Überprüfung im Quellcode. Es beschreibt die Funktionsweise von jqassistant, einschließlich des Scannens von Softwarestrukturen, der Validierung von Regelverletzungen und der Generierung von Dokumentationen. Des Weiteren werden graphbasierte Analysen mit Neo4j und die Verwendung von Cypher für Abfragen sowie die Strukturierung der Ergebnisse in Asciidoc angesprochen.

1. Architektur und Code
im Einklang
Umsetzung von Architekturkonzepten
und Designvorgaben mit jQAssistant und AsciiDoc
direkt im Quellcode automatisiert überprüfen
@feststelltaste feststelltaste.de talk@markusharrer.de
Markus Harrer
Sparda Datenverarbeitung e. G.
Java User Group Nürnberg (28.06.2017)

2. “If you think good architecture is
expensive, try bad architecture.”
Brian Foote

3. “If you think bad architecture is
expensive, try undocumented and
non-validated architecture.”
Markus Harrer

4. Plan
Reality

5. + =
scan document validate

6. Grundlegendes
zu jQAssistant

7. jQAssistant Funktionsweise
• Scanne Softwarestrukturen
• Speichere diese in eine Datenbank
• Führe Abfragen aus
• Untersuche Zusammenhänge
• Ergänze Konzepte
• Validiere Regelverletzungen
• Generiere Berichte

8. jQAssistant Kernideen: Concepts
• Gescannte Elemente werden Konzepten
(„concepts“) zugeordnet, z. B.
• Maven Project = Modul
• Java Package = Schicht
• Mit @Entity annotierte Klasse = JPA-Entity

9. jQAssistant Kernideen: Constraints
• Regeln werden auf Basis der Konzepte textuell
formuliert, z. B.
„Alle JPA-Entitäten müssen sich in der
Persistenz-Schicht befinden“
• Abweichungen von den Regeln („constraints“)
werden geprüft, z. B.
„Gib mir alle JPA-Entities, die sich nicht in der
Persistenzschicht befinden.“

10. jQAssistant Kernideen: Constraints
• Regeln werden auf Basis der Konzepte textuell
formuliert, z. B.
„Alle JPA-Entitäten müssen sich in der
Persistenz-Schicht befinden“
• Abweichungen von den Regeln („constraints“)
werden geprüft, z. B.
„Gib mir alle JPA-Entities, die sich nicht in der
Persistenzschicht befinden.“

11. jQAssistant Kernideen: Groups
• Alles wird in einer gemeinsamen
Dokumentation festgehalten, über Gruppen
(„groups“) strukturiert und beim Build
ausgeführt.
Ausschnitt:

12. Graphentheorie
mit Neo4j und Cypher

13. Ein Graph
Knoten
Kante

14. Graph im Detail
Knoten
Mögliche Arten
Java-Klasse
Messpunkt
Datei
Repository
URL
...

15. Graph im Detail
Kanten
Typ einer Beziehung
DECLARES
EXTENDS
IMPLEMENTS
ANNOTATED_BY
DEPENDS_ON
...

16. Ein Graph – sogar mit Daten!
File Class TypeFile
key value
name “entity“
file “Entity.java”
fqn “jpa.thing.Entity”
key value
weight 3key value
name “Pet”
file “Pet.java”
fqn “foo.bar.Pet”
Labels
Properties

17. Beispiel
Spring PetClinic

18. Sprint PetClinic: Verwaltung für Tierpraxis

19. Beispiel-Graph: Sprint PetClinic
visibility: public
name: Pet
fqn: org.springframework.samples.petclinic.model.Pet
…
Class:Type:Java:File

20. Beispiel-Graph: Sprint PetClinic

21. Beispiel-Graph: Sprint PetClinic

22. Beispiel-Graph: Sprint PetClinic
Kann ich abfragen!

23. Cypher
Syntax

24. Cypher
Abfrage von Knoten
MATCH
(p:Class)-[]->(e:Type)
WHERE
p.name = "Pet" AND
e.name = "Entity"
RETURN p, e

25. Explorative Analysen in Neo4j
Demo 1
MATCH
(p:Class)-[]->(e:Type)
WHERE
p.name = "Pet" AND
e.name = "Entity"
RETURN p, e

26. Dokumentieren
mit AsciiDoc und Cypher

27. AsciiDoc
Markup Language
• Rendert zu
• DocBook
• HTML
• PDF
mit Cypher: ausführbare Spezifikation!
• Programmiervorgaben
• Design und Architektur

28. Definition eines Concepts
== JPA Entities
[[jpa2:Entity]]
.Labels all types annotated with @javax.persistence.Entity
with Jpa and Entity.
[source,cypher,role=concept]
----
MATCH
(t:Type)-[:ANNOTATED_BY]->()-[:OF_TYPE]->(a:Type)
WHERE a.fqn ="javax.persistence.Entity"
SET t:Jpa:Entity
RETURN t AS Entity
----

29. Definition eines Constraints
[[model:JpaEntityInModelPackage]]
.All JPA entities must be located in packages named
"model".
[source,cypher,role=constraint,
requiresConcepts="jpa2:Entity"]
----
MATCH
(package:Package)-[:CONTAINS]-
>(entity:Jpa:Entity) WHERE
package.name <> "model"
RETURN
entity AS EntityInWrongPackage
----

30. Definition einer Group
[[default]]
[role=group,includesConstraints=
"model:JpaEntityInModelPackage"]

31. Ergebnisbericht
Z. B. als Maven Site Report

32. Selbstvalidierende Architekturdokumentation
Demo 2
Spring PetClinic

33. Plan
Reality

34. • jQAssistant bietet schnelle und flexible Sichten
auf eine Vielzahl von Softwarestrukturen
• Zusammenhänge können explorativ über die
Graphdatenbank Neo4j erkundet werden
• Definition von Spielregeln über Concepts und
Constraints in Cypher / AsciiDoc
Automatisierte Überprüfung von
• Architekturkonzepten und
• Designvorgaben
• direkt im Code
Zusammenfassung

35. Links
• jQAssistant
• http://jqassistant.org
• Ausführliches Video
• https://www.youtube.com/watch?v=kQr2c7yWbEA
• Spring PetClinic Beispielprojekt
• Repo: http://github.com/buschmais/spring-petclinic
• Output: https://buschmais.github.io/spring-petclinic/
• Meine Erfahrungen soweit
• https://www.feststelltaste.de/my-experiences-with-
jqassistant-so-far/

36. Credits
Einige Beispiele wurden aus Dirk Mahlers
Vortrag “jQAssistant - Verify Your Design And
Architecture” übernommen
• https://jqassistant.org/wp-content/uploads/2016/06/
jQAssistant-Verify-Your-Design-And-Architecture.pdf
Bilder
• https://de.wikipedia.org/wiki/Datei:Yin_yang.svg
• https://commons.wikimedia.org/wiki/File:Achitecture_time.jpg
• https://commons.wikimedia.org/wiki/File:Adelaide_Street_aba
ndoned_house.jpg

37. Fragerunde
Eure Fragen