Zum Ende meiner Ausbildung zur Fachinformatikerin für Anwendungsentwicklung stand meine Abschlussarbeit an. Dabei fiel die Wahl auf ein Thema, das wir im Entwicklungs-Alltag bei queoflow wirklich gebrauchen können: Codegenerierung mit der Java-eigenen Technologie „Annotation Processing“ (kurz AP).

Besonders zu Beginn eines Projektes würde uns ein solcher Codegenerator extrem viel Arbeit abnehmen. Deswegen habe ich mich, mit der Betreuung unseres Teamleiters Ralph, an die Arbeit gemacht.

Ähnlich wie bei Reflection, lassen sich mit der Java-Technologie „Annotation Processing“ Meta-Daten auslesen und verarbeiten. Der große Unterschied zwischen den beiden Technologien ist der Zeitpunkt:

Reflection arbeitet erst zur Laufzeit, während AP bereits zur Compilezeit greift. Dies bringt einige Probleme mit sich (Testbarkeit), hat aber auch den Vorteil, dass so Dateien generiert werden können, die direkt in den laufenden Compileprozess mit eingebunden werden können.

AP arbeitet dabei in Runden. Erzeugt also Prozessor Dateien, so stehen die im nächsten Durchlauf (der nächsten Runde) sofort wieder zur Verfügung, da eine solche generierte Datei ja wieder Informationen zur Generierung weiterer Dateien beinhalten kann.

Beispiel: Erzeugen von Kindklassen

Im Folgenden möchte ich anhand eines Beispiels zeigen, wie man einen einfachen Generator selbst bauen kann. Am Ende des Artikels werde ich den Generator aus diesem Beispiel mit verlinken.

Der Beispielgenerator soll zu einer gegebenen Klasse erbende Kindklassen erstellen.

Dazu sind zunächst drei separate Maven-Projekte notwendig. Ich werde sie alle unter der groupId „com.queomedia.generator.example“ zusammenfassen, aber verschiedene artifactIds geben:

  • Annotation-Projekt (artifactId „annotation“)
  • AnnotationProcessor-Projekt (artifactId „annotation-processor“)
  • ein Beispielprojekt (artifactId „example“)

Annotation-Projekt („annotation“-artifact)

Im Annotation-Projekt wird eine Annotation „GenerateInheriting“ erstellt:

Damit ist das Annotation-Projekt bereits abgeschlossen

AnnotationProcessor-Projekt („annotation-processor“-artifact)

Zunächst wird der Prozessor selbst erstellt:

Wichtig ist hier die Annotation „@SupportedAnnotationTypes“. Darüber wird AP mitgeteilt, welche Annotation zu dem jeweiligen Prozessor gehört. Gültige Argumente sind die vollqualifizierten Namen der Annotationen.

Damit überprüft werden kann kann, ob der Prozessor prinzipiell registriert ist und aufgerufen wird, wird eine Lognachricht eingefügt.

Jetzt müssen noch zwei Dinge konfiguriert werden: Im Prozessor-artifact selbst muss das Processing deaktiviert werden. Bleibt es hier aktiviert, passiert folgendes: Das Annotation Processing findet vor der Compilezeit statt. Der Compiler würde versuchen, den Processor zu laden, bevor er überhaupt kompiliert ist, was zum Huhn-Ei-Problem führt. Die Compilierung kann nicht ablaufen, weil das Processing noch nicht durch ist, das Processing kann nicht ablaufen, weil keine compilierten Dateien vorliegen.

Um das Processing zu deaktivieren, wird das Maven-Compiler-Plugin in der pom.xml  eingebunden und konfiguriert. Außerdem wird noch eine Dependency zum Annotation-Projekt benötigt:

Den Prozessor selbst wird in der Datei javax.annotation.processing.Processor registriert, die im Verzeichnis src/main/resources/META-INF/services liegen muss:

Möchte man mehrere Prozessoren registrieren, muss jeder einzelne in einer eigenen Zeile stehen, ohne Trennung durch ein Semikolon o.ä.

Example-Projekt („example“-artifact)

Damit ist der Prozessor einsatzbereit. Nun wird überprüft, ob alles korrekt konfiguriert ist und der Prozessor aufgerufen wird.

Dazu wird im Example-Projekt der Prozessor eingebunden und wieder das Maven-Compiler-Plugin konfiguriert :

„showWarnings“ sorgt dafür, dass sämtliche Lognachrichten auch in der Konsole angezeigt werden. Ohne diesen Parameter würden beim Bauen in der Konsole nur Warnings und Errors erscheinen.

Jetzt wird eine Testklasse erstellt, die folgendermaßen annotiert wird:

Wenn jetzt das Example-Projekt über die Konsole gebaut wird, erhält man folgende Ausgabe:

Da der Prozessor jetzt prinzipiell aufgerufen wird und funktioniert, kann man sich die gewünschten Dateien generieren lassen.

Man kann sich dazu mit „roundEnv.getElementsAnnotatedWith(GenerateInheriting.class);“ erst alle Elemente holen lassen, die die Annotation besitzen und von dieser die gewünschten Klassennamen geben lassen und daraus mit Hilfe des Java-eigenen Filers eine Sourcedatei erzeugen:

Alle von AP generierten Dateien werden standardmäßig im Verzeichnis target/generated-sources/annotations abgelegt.

Nun ist das Dateierzeugen über Stringkonkatenierung / Stringbuilder nicht besonders gut lesbar. Sobald die Generierung über einzelne Codezeilen hinausgeht, wird das ganze sehr unübersichtlich und schwer wartbar. Ich persönlich benutze deswegen die Templating-Engine Freemarker, prinzipiell sollte es aber auch mit jeder anderen Engine funktionieren.

Dazu erstellt man sich ein Template und ändert den Code so ab, dass  dieses statt Stringkonkatenierung in der benutzt wird:

Refactoring

Der Prozessor funktioniert damit wie gewünscht. Er ist nun allerdings weder getestet, noch testbar und verletzt das Prinzip der Single-Responsibility.

Deswegen trennt man nun den Prozessor in mehrere Serviceklassen auf: Eine zum Auslesen der annotierten Klassen und eine zum Generieren der Dateien. Der Prozessor delegiert die einzelnen Aufgaben nur noch an diese Services ab. Außerdem erstellt man eine Hilfsklasse, welche alle benötigten Informationen zu einer annotierten Klasse kapselt. Bei einem so einfachen Prozessor wie diesem, sieht eine Hilfsklasse auf den ersten Blick nach zu viel Inhalt aus. Der Aufwand lohnt sich aber, sobald die benötigten Informationen umfangreicher werden. Im Rahmen meiner Abschlussarbeit musste ich beispielsweise auch die Felder jeder Klasse auswerten und nach bestimmten Kriterien gruppieren. Das wäre über Listen oder Maps nicht mehr vernünftig handhabbar.

Nach dem Refactoren sieht das Ganze so aus:

Hilfsklasse AnnotatedClazz

ElementParsingService:

SourceFileWritingService:

Processor:

Automatisierte Unit-Tests

Bei queo nehmen automatisierte Tests einen sehr großen Stellenwert ein. AP greift zur Compilezeit, während Tests aber erst zur Laufzeit ausgeführt werden. Mit herkömmlichen Mitteln ist der Code zum Auslesen und Generieren damit nicht testbar.

Um dieses Problem zu lösen benutze ich zwei externe Bibliotheken:

CompileTesting bietet Funktionen, um das Auslesen/Parsen von Klassen zu simulieren.

JavaMirrorMocks ahmt u.a. das Verhalten des AP-eigenen Filers nach, d.h. damit lässt sich die Generierung der Dateien testen.

Um das Parsen zu testen, erstelle ich mir eine simple Dummyklasse, welche meine Annotation besitzt:

Im Testfall benutze ich die CompileTesting-Bibliothek, um mir ein diese Klasse als TypeElement geben zu lassen. Dieses TypeElement ist fast identisch mit dem, welches mir mein Prozessor für diese Klasse erzeugen würde. Ich kann es also in meinen ElementParsingService hinein geben und überprüfen, ob er alle Informationen korrekt auswertet:

Hinweis: Die CompileTesting-Bibliothek selbst arbeitet zur Laufzeit, das heißt, dass alle Elemente, die nur zur Compilezeit verfügbar sind, von dieser Bibliothek nicht erkannt werden können.

An der Annotation GenerateInheriting kann man definieren, ob diese nur zur Compile- (RetentionPolicy.SOURCE) oder auch später zur Laufzeit (RetentionPolicy.RUNTIME / CLASS) verfügbar sein soll.

Mit RetentionPolicy.SOURCE ist die Annotation bereits verworfen / nicht mehr existent, wenn die Bibliothek wirksam wird. Annotiert man eine Klasse mit einer Annotation mit RetentionPolicy.SOURCE und versucht über die CompileTesting-Bibliothek auf die Annotation zuzugreifen, wird eine NullpointerException fliegen, da diese eben zur Laufzeit nicht mehr vorhanden ist.

Um den SourceFileWritingService zu testen, benötigt man ein Element, das sich möglichst exakt so verhält, wie der AP-Filer.

Deswegen lasse ich mir von JavaMirrorMocks einen Mock der ProcessingEnvironment erzeugen und von dieser den Filer geben:

Codegenerierung On Demand

Es gibt Fälle, in denen keine permanente Generierung (d.h. bei jedem Build) gewünscht ist, sondern nur on demand.

In diesem Fall kann man sich in der pom.xml des jeweiligen Projektes (in meinem Fall das Example-Projekt) ein Maven-Profil definieren, welches den Prozessor als Dependency hat. Dies führt dazu, dass der Prozessor erst eingebunden (und damit aufgerufen) wird, wenn der Build mit dem entsprechenden Profil gestartet wird.

Startet man jetzt den Build nur mit „mvn clean install“, so werden keine Dateien generiert, mit „mvn clean install -PgenerateInheriting“ hingegen wird der Prozessor mit durchlaufen und erzeugtt die gewünschten Dateien.

Die Einsatzmöglichkeiten von AP sind nahezu unbegrenzt und gerade in großen Projekten mit vielen ähnlichen Strukturen kann es sich lohnen, über eine solche Automatisierung nachzudenken.

Ich hoffe, dass ich mit diesem Artikel einen kleinen Einblick in die Codegenerierung unter Java geben konnte.

Beispielprojekt:
CodeGenerator (Download)