18.05.2017, DeveloperCamp 2017, Nürnberg Umsetzung von Architekturkonzepten und Designvorgaben mit jQAssistant direkt im Quellcode überprüfen jQAssistant ist ein Werkzeug zur statischen Analyse von Softwareartefakten. Mit jQAssistant ist es möglich, Architektur- und Designkonzepte als einen Satz von Regeln zu definieren. Die Einhaltung dieser Regeln kann anschließend bei jedem Bau einer Software automatisiert überprüft werden. Dadurch kann sichergestellt werden, dass eine vorgegebene Architektur sowie Designvorgaben auch wirklich im Quellcode umgesetzt wurden. In meinem Vortrag stelle ich die Grundlagen von jQAssistant vor und zeige an einem Beispiel, wie sich mit dem Werkzeug eine sich selbst prüfende Architekturdokumentation erstellen lässt.

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

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

3. “If you think good 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: Groups
• Alles wird in einer gemeinsamen
Dokumentation festgehalten, über Gruppen
(„groups“) strukturiert und beim Build
ausgeführt.
Ausschnitt:

11. Technische Umsetzung: Alles Plugins
Command
Line/
Maven
Scan
Analyze
Report
Plugins
Plugins
Plugins

12. Scanner
*.class
RDBMS Schema
Git
JaCoCo
FindBugsCheckStyle
JAR, WAR, EAR
ZIP
application.xml
web.xml
MANIFEST.M
F
beans.xml
pom.xml
surefire-reports.xml
GZ
*.properties
*.xsd
M2 Repository
*.yaml
*.xml

13. Scanner
*.class
RDBMS Schema
Git
JaCoCo
FindBugsCheckStyle
JAR, WAR, EAR
ZIP
application.xml
web.xml
MANIFEST.M
F
beans.xml
pom.xml
surefire-reports.xml
GZ
*.properties
*.xsd
M2 Repository
*.yaml
*.xml

14. Scanner
*.class
RDBMS Schema
Git
JaCoCo
FindBugsCheckStyle
JAR, WAR, EAR
ZIP
application.xml
web.xml
MANIFEST.M
F
beans.xml
pom.xml
surefire-reports.xml
GZ
*.properties
*.xsd
M2 Repository
*.yaml
*.xml

15. Scanner
*.class
RDBMS Schema
Git
JaCoCo
FindBugsCheckStyle
JAR, WAR, EAR
ZIP
application.xml
web.xml
MANIFEST.M
F
beans.xml
pom.xml
surefire-reports.xml
GZ
*.properties
*.xsd
M2 Repository
*.yaml
*.xml

16. Scanner
*.class
RDBMS Schema
Git
JaCoCo
FindBugsCheckStyle
JAR, WAR, EAR
ZIP
application.xml
web.xml
MANIFEST.M
F
beans.xml
pom.xml
surefire-reports.xml
GZ
*.properties
*.xsd
M2 Repository
*.yaml
*.xml

17. Scanner
*.class
RDBMS Schema
Git
JaCoCo
FindBugsCheckStyle
JAR, WAR, EAR
ZIP
application.xml
web.xml
MANIFEST.M
F
beans.xml
pom.xml
surefire-reports.xml
GZ
*.properties
*.xsd
M2 Repository
*.yaml
*.xml

18. Graphentheorie
mit Neo4j und Cypher

19. Ein Graph
Knoten
Kante

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

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

22. Ein Graph
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

23. Graph im Detail
Labels
Markierung eines Knotens
:Class
:Type
:Java
:File
...
File

24. Graph im Detail
Properties
Eigenschaften eines Knotens
fqn
name
visibility
abstract
static
final
...
key value
name “Pet”
file “Pet.java”
fqn “foo.bar.Pet”

25. Beispiel
Spring PetClinic

26. Sprint PetClinic: Verwaltung für Tierpraxis

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

28. Beispiel-Graph: Sprint PetClinic

29. Beispiel-Graph: Sprint PetClinic

30. Beispiel-Graph: Sprint PetClinic

31. Beispiel-Graph: Sprint PetClinic

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

33. Cypher
Syntax

34. Cypher
Syntax

35. Cypher
Syntax

36. Cypher
Syntax

37. Cypher
Abfrage von Knoten
()-[]->()

38. Cypher
Abfrage von Knoten
(p)-[]->(e)

39. Cypher
Abfrage von Knoten
(p:Class)-[]->(e:Type)

40. Cypher
Abfrage von Knoten
(p:Class {name:"Pet"})-[]->(e:Type {name:"Entity"})

41. Cypher
Abfrage von Knoten
MATCH
(p:Class {name:"Pet"})-[]->(e:Type {name:"Entity"})
RETURN p, e

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

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

44. Dokumentieren
mit AsciiDoc und Cypher

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

46. 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
----

47. 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
----

48. Definition einer Group
[[default]]
[role=group,includesConstraints=
"model:JpaEntityInModelPackage"]
== Naming Rules
The following naming rules apply:
- <<model:JpaEntityInModelPackage>>

49. Ergebnisbericht
Z. B. als Maven Site Report

50. Selbstvalidierende Architekturdokumentation
Demo 2
Spring PetClinic

51. Plan
Reality

52. • 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

53. 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/

54. 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

55. Fragerunde
Eure Fragen