Heute will ich von einem letztlich gescheiterten Experiment erzählen. Um mal ein Zitat aus einem Song zu benutzen: "Ja, auch das muss ab und zu mal sein!"

Ich habe im Urlaub überlegt, wie man die Dokumentation der Scripting- und Plugin-Schnittstellen in - zum Beispiel - sQLshell und dWb+ verbessern könnte und bin auf die Idee gekommen, UML-Diagramme dafür zu erstellen. Das sollte natürlich alles ohne teure Software, bei der man für den Vendor-Lockin gleich mitbezahlt laufen - also setzte ich mir als Ziel, das mit PlantUML lösen zu wollen.

Da kam natürlich sofort die Frage auf, ob nicht schon Leute vor mir dieselbe Idee hatten und das eventuell schon als fertige Lösung existieren würde. Ich recherchierte ein wenig und fand tatsächlich einige Alternativen: uml-parser als standalone-Lösung, Kotlin2PlantUML als standalone-Lösung mit API, so dass man diese Lösung auch in eigenen Programmen einsetzen könnte und livingdoc Als Lösung, die sich in den Build-prozess mit Maven integrieren ließe.

Da livingdoc auf Annotations setzte und das PlantUML mittels Annotation Processor erzeugt fiel meine Wahl hierauf. Nun tauchte ich zunächst mal in ein Rabbithole ab, denn wie gesagt: Die Lösung war für Maven gedacht. Da ich Configuration by Convention als Irrweg empfinde habe ich durchaus noch viele Projekte, die auf ANT basieren. Die, um die es hier gehen sollte, waren dieser Kategorie zuzurechen.

Also benötigte ich eine Methode, aus Maven-Dependencies einer pom.xml ein ivy.xml zu erzeugen. Die Lösung besteht aus drei Modulen, daher musste das dreimal - je einmal für jedes Modul - geschehen. Glücklicherweise verfügt Ivy über Möglichkeiten, die Konfiguration beider Tools in beiden Richtungen zu konvertieren. Die Dependencies der Lösung waren jedoch so zahlreich, dass ich unbegingt vermeiden wollte, diese in meine fachlich motivierten Dependencies zu mischen.

Da kam mir ein Artikel gerade recht, der auf eindrucksvolle Art und Weise beschreibt, wie man Ivy- und Ant-Setups modularisieren kann.

Die letzte Hürde schließlich bestand darin, dass das Verzeichnis, das die Ergebnisse aufnehmen sollte in der Lösung über einen custom Parameter für den Processor festgelegt wurde und nicht über den dafür bereits vorgesehenen Kommandozeilenschalter. Dafür musste ich mich erst einmal daran erinnern, wie man javac diese Processor-Parameter bei der Ausführung mitgibt...

Nachdem auch diese Herausforderung gemeistert war (alle diese Experimente fanden selbstredend auf einem separaten Branch statt - ich war mir ja noch nicht sicher, ob ich mit den Ergebnissen wirklich so zufrieden sein würde, dass das ein dauerhafter Teil des Projekts würde...), begann ich einige der Klassen der sQLshell mit den entsprechenden Annotations zu versehen und startete das Rendering. Hier ist zu sehen, wie weit ich bei meinem Experiment gekommen bin:

Klassen der Scripting- und Plugin-API der sQLshell als UML-Diagramm

Hier sieht man auch direkt einiger der Gründe, warum ich die Arbeit nicht in den master-Branch übernommen habe - Der Hauptgrund ist, dass Assoziationen keine Labels haben und nicht von den korrespondierenden Feldern ausgehen, sondern einfach irgendwo an der jeweiligen Klasse starten. In dieser Form würde die Darstellung die Bevölkerung mehr verwirren, als dass sie hilfreich wäre.

Ich könnte natürlich das Projekt in meinem Sinne erweitern. Vielleicht tue ich das tatsächlich auch irgendwann. Bei Interesse kann man selbst damit experimentieren - ich habe das Projekt auf Codeberg geforkt und eine Release davon erzeugt.