Andreas Solymosi

Annotationen in Java

Annotationen wurden in der Java-Version 5 eingeführt. Sie sind geeignet, Definitionen von Java-Programmelemente (wie Pakete, Typen, Variablen, Methoden) zu markieren oder mit Metadaten zu versehen. Ihre Namen fangen mit dem Zeichen @ an:

@Deprecated

class EineKlasse …

Sie werden typischerweise nicht vom Java-Compiler bearbeitet sondern unverändert in den Bytecode übernommen; Java-Werkzeuge (auch zur Laufzeit, manchmal unabhängig, manchmal innerhalb vom Compiler) können sie auswerten. Ein Beispiel hierfür ist das Werkzeug javadoc, das Annotationen in Dokumentationskommentaren (sie fangen alle mit @ an) bearbeitet. javadoc wertet das Quellprogramm aus; andere Werkzeuge können dasselbe mit dem Bytecode tun.

Mit Annotationen können fehlende Sprachelemente, (z.B. const-Markierung wie in C++, externe Zusicherungen wie in Eiffel, usw.) nachgebaut werden. Ein zu diesem Zweck entwickeltes Werkzeug kann vor oder nach dem Compiler aufgerufen werden. Manchmal werden Annotationen von einem Compiler-Plugin (sog. annotation processor) bearbeitet. Viele Entwicklungswerkzeuge wie Frameworks oder IDEs verlangen vom Entwickler, dass sie ihre Java-Programme mit Annotationen bereichern.

Vereinbarung von Annotationen

Annotationen sind spezielle Schnittstellen (interface); ihre Namen werden daher konventionsgemäß mit großem Anfangsbuchstaben geschrieben. In ihrer Vereinbarung (Deklaration) steht vor interface das Zeichen @. Sie erweitern implizit die Schnittstelle java.lang.annotation.Annotation. Sie dürfen keine andere Schnittstellen erweitern (d.h. extends ist verboten) und sind nicht generisch. Ihre Methoden sind parameterlos und nicht-generisch. Als Ergebnistypen (return type) sind nur folgende Typen (auch kein void) erlaubt:

·         primitive Typen

·         Aufzählungstypen (enum)

·         Annotationstypen

·         String

·         Class

·         Reihungen (arrays) aus diesen Typen

Ihre Methoden werfen keine Ausnahmen und dürfen nicht Rekursion verwenden. Alle Elemente der Annotationen sind konstant, d.h. sie werden zu Übersetzungszeit einmal berechnet und nicht mehr verändert.

Viele Annotationen sind Markierungsschnittstellen (wie z.B. auch java.io.Serializable), d.h. sie enthalten keine Methoden – sie werden auch Markierungen genannt. Ein Beispiel wäre:

@interface Vorläufig { }

Andere Annotationen enthalten (wie für Schnittstellen üblich) Methodenvereinbarungen[1], allerdings nur mit den oben aufgeführten Ergebnistypen. Wenn eine Annotation nur eine Methode enthält (solche können Werteannotationen genannt werden), ist ihr Name konventionsgemäß value:

@interface Testversion {

   boolean value(); // true solange nicht freigegeben

}

oder

@interface Authoren {

   String[] value(); // Namen der Authoren

}

oder

@interface Kunden {

   Person[] value();

}

wobei Person als Aufzählungstyp (enum) oder Annotation definiert wird, z.B.:

@interface Person {

   String name();

   int alter();

}

Verwendung von Annotationen

Nach ihrer Vereinbarung können Annotationen für Markierung oder Bereicherung von Programmteilen verwendet werden.

Eine Markierung (Annotation ohne Methoden) wie @Vorläufig, kann z.B. einer Klasse vorangestellt werden:

@Vorläufig

class Klasse {

  void methode() {} }

Mit dieser Annotation werden Programmteile (wie Klassen, Methoden, Variablen) als „vorläufig“, also noch nicht fertiggestellt, markiert.

Bei der Benutzung von Annotationen mit Methoden (die also keine Markierungen sind) muss in Klammern ein konstanter (d.h. zur Übersetzungszeit berechenbarer) Wert vom Ergebnistyp dieser Methode in Klammern angegeben werden. Bei einer Werteannotation (mit nur einer Methode) ist dies einfach:

@Testversion(true)

public void methode() { }

Wenn der Ergebnistyp eine Reihung ist, soll ein Reihungsliteral verwendet werden:

@Authoren({"Solymosi", "Grude"})

String buch = "Algorithmen und Datenstrukturen mit Java";

Wenn die Reihung keine Elemente enthält, muss ({})angegeben werden. Wenn die Reihung nur ein Element enthält, können die geschweiften Klammern weggelassen werden:

@Authoren("Solymosi")

String anderesBuch = "Programmieren in Scala";

Einer Annotation mit mehreren Methoden muss jeder ihrer Methoden in Klammern ein konstanter Wert zugeordnet werden; die Reihenfolge ist dabei unwichtig:

@Person(name = "Andreas Solymosi", alter = 56)

Konto konto = new Konto();

Die Möglichkeit, den Wert mit dem Namen anzugeben, besteht auch für Werteannotationen (ist allerdings überflüssig, dient höchstens der Lesbarkeit):

@Testversion(value = true)

Eine komplexe (geschachtelte) Annotation muss geschachtelt angewendet werden:

@Kunden(@Person(name = "Andreas Solymosi", alter = 56))

class Unternehmen { … }

In der Vereinbarung der Annotation können den Methoden Standardwerte[2] mit default zugeordnet werden; dann kann der entsprechende Wert bei der Verwendung weggelassen werden. Da Annotationen Schnittstellen sind, können sie selber mit Annotationen (auch mit Zugriffschutz, usw.) versehen werden:

@Authoren("Solymosi")

public @interface Testversion {

   boolean wert() default false; // muss nicht unbedingt value heißen

}

Standard-Annotationen

Die Standardbibliotheken enthalten einen Satz von Annotationvereinbarungen; deren Namen dürfen für andere Annotationen nicht verwendet werden.

Im Paket java.lang gibt es drei vordefinierte Annotationen, die auch vom Compiler ausgewertet werden:

·         @Override – für Methoden, die eine aus der Oberklasse überschreiben. Wenn nicht, gibt der Compiler eine Fehlermeldung aus.

·         @Deprecated – für Typen (Klassen, usw.) lokale und globale Variablen (d.h. Objekt- und Klassenattribute), Methoden, Konstruktore und Parameter  (typischerweise in Bibliotheken), die langfristig durch andere ersetzt werden sollen. Der Compiler gibt bei der Verwendung dieser Programmteile eine Warnung aus.

·         @SuppressWarnings – für dieselben Programmelemente wie @Deprecated, mit einer Methode String[] value(). In der String-Liste wird compilerspezifisch angegeben, welche Art von Warnungen unterdrückt werden sollen, z.B. "unused" (wenn eine unbenutzte Methode oder Variable gestrichen werden könnte).

Die Annotation @Override ist wichtig, um schwer lokalisierbare Programmiererfehler zu vermeiden. In Java ist sie optional; in einigen Programmiersprachen (z.B. in Scala) wird ihre Funktionalität duch obligatorische Sprachelemente vertreten. Wenn nämlich eine Methode in einer Unterklasse überschrieben werden sollte, ist es leicht, infolge von Tipp- oder Denkfehler statt dessen sie zu überladen (z.B. durch einen fehlerhaften Namen oder eine fehlerhafte Parameterliste). Durch die konsequente Verwendung von @Override werden solche Fehler vom Compiler ausgefiltert. Ggf. kann eine selbstvereinbarte Annotation @Overload diese Konvention weiter stärken.

Im Paket java.lang.annotation befinden sich vordefinierte Annotationen, die nur für (andere) Annotationen (in ihrer Vereinbarung) verwendet werden dürfen. Sie beschreiben Eigenschaften dieser Annotationen:

·         @Documented –  wird von javadoc ausgewertet: Die Vorkommnisse der Annotation werden in die generierte HTML-Dokumentation übernommen.

·         @Inherited – die markierte Annotation wird an Untertypen vererbt.

·         @Retention – definiert, wie lange soll die markierte Annotation aufbewahrt werden. Die value()-Methode dieser Wertannotation kann die Werte des Aufzählungstyps RetentionPolicy annehmen:

·         SOURCE

·         CLASS

·         RUNTIME

Dementsprechend ist die markierte Annotation nur im Quelltext (z.B. für javadoc), in der gespeicherten class-Datei (für Auswertungswerkzeuge) oder auch in der geladenen Klasse (für Reflexion) verfügbar. Standardwert ist CLASS, d.h. wenn einer Annotation keine @Retention angegben ist, wird sie in die .class-Datei, nicht aber in die geladene Klasse übernommen.

·         @Target – beschreibt, für welche Programmelemente die Annotation verwendet werden darf. Die möglichen value()-Werte (vom Aufzählungstyp ElementType) sind:

·         PACKAGE – für Pakete

·         TYPE – für Klassen, Schnittstellen (auch Annotationen) und Aufzählungstypen (enum)

·         ANNOTATION_TYPE – nur für Annotationen

·         METHOD – für Methodenvereinbarungen

·         CONSTRUCTOR – für Konstruktorvereinbarungen

·         FIELD – für globale Variablen (Klassen- und Objektvariablen), auch enum-Konstante

·         LOCAL_VARIABLE – für lokale Variablen

·         PARAMETER – für Parameter von Methoden

Ohne @Target dürfen Annotationen für alle diese Programmelemente (aber für keine andere, z.B. für Anweisungen) verwendet werden.

Beispielsweise sind alle Annotationsvereinbarungen im Paket java.lang.annotation mit den Annotationen

@Documented

@Retention(value=RUNTIME)

@Target(value=ANNOTATION_TYPE)

versehen. Hierdurch werden sie alle von javadoc ausgewertet, im Bytecode mit geladen und können so zur Laufzeit ausgewertet werden; des weiteren dürfen sie nur für Annotationstypen verwendet werden.

Auswertung von Annotationen

Die Annotationen und ihre Werte können also immer aus dem Quelltext ermittelt werden, die ohne @Retention auch aus dem Bytecode der Klasse, und die mit @Retention(RUNTIME) werden sie mit der Klasse zusammen geladen. Der Interpreter wertet sie nicht aus, aber jedes Java-Programm (so auch eine Methode der Klasse selbst) kann sie darin mit Hilfe von Reflexion finden. Beispielsweise kann es feststellen, ob die Markierung Vorläufig vorhanden ist oder nicht[3]:

boolean istVorläufig = Klasse.class.isAnnotationPresent(Vorläufig.class);

Die Methode isAnnotationPresent stammt aus der Schnittstelle java.lang.reflect.Anno­tated­Element, die von der Klasse java.lang.Class implementiert wird; so kann sie für das Objekt Klasse.class (ein Literal vom Typ Class) aufgerufen werden.

Wenn das Programm festgestellt hat, dass die Annotation vorhanden ist, dann kann es auch ihren Wert lesen, z.B. ob die Methode noch im Testzustand ist oder nicht:

boolean istTest = Klasse.class.getMethod("methode", new Class[]{}).    getAnnotation(Testversion.class).value();

Hier wird zuerst aus der Klasse Klasse (wie oben definiert) die parameterlose (new Class[]{}) Methode methode mit Hilfe von getMethod() herausgelesen. Dies ist ein Objekt vom Typ java.lang.reflect.Method; diese Klasse implementiert java.lang.reflect.An­no­­tated­­Element. Also, getAnnotation kann für es aufgerufen werden. Die Signatur dieser generischen Methode ist

<A extends Annotation> A getAnnotation(Class<A> annotationClass)

Dies bedeutet, sie liefert ein Objekt vom selben Typ (A), mit dem für sein Parameter Class instanziiert wurde (dieser muss Annotation erweitern) – also im obigen Beispiel Testversion. Für dieses Objekt wird die Methode value()aufgerufen, deren konstantes Ergebnis vom Typ boolean ist – der gesuchte Wert der Annotation. Die Methode getAnnotation() wirft (unglücklicherweise) NullPointerException, falls die methode nicht mit der Annotation Testversion versehen ist.

Diese Überlegung zeigt, dass zwar kein Java-Programm ein Annotation-Objekt erzeugen kann (zumal Annotationen Schnittstellen sind), Annotation-Methoden trotzdem aufgerufen werden können, weil im Hintergrund (infolge der Reflexion) Annotation-Objekte doch existieren.

Die obige Programmzeile wird der Praxis mit Variablen anstelle der Literale Klasse.class, "methode" und Testversion.class benutzt. Für Wertannotationen mit einem boolean-Wert kann zum Beispiel vereinbart werden:

interface BooleanAnnotation extends Annotation {

   boolean value();

}

<A extends BooleanAnnotation> boolean annotationswert(String beliebigeKlasse,

        String parameterloseMethode, String booleanAnnotation)

     throws ClassNotFoundException, NoSuchMethodException {

   Class<?> klasse = Class.forName(beliebigeKlasse);

   Method methode = klasse.getMethod(parameterloseMethode, new Class[]{});

   Class<A> annotation = (Class<A>)Class.forName(booleanAnnotation);

   return methode.isAnnotationPresent(annotation) &&

     methode.getAnnotation(annotation).value();

 }

Diese generische Methode kann mit den Namen einer beliebigen Klasse, einer ihrer parameterlosen Methoden, und eine Annotation aufgerufen werden. Sie wirft ClassNotFoundException, falls die Klasse oder die Annotation mit dem gegebenen Namen nicht geladen wurde (oder werden kann), und NoSuchMethodException, falls die Klasse die gegebene parameterlose Methode nicht enthält: Sie liefert (wie oben erläutert) den boolean-Wert dieser Annotation:

boolean istTest = new Annotationen().annotationswert("Klasse", "methode",

  "Testversion");

Das Ergebnis dieses Aufrufs wird allerdings nur dann true ergeben, wenn die Annotation Testversion zur Laufzeit ausgewertet werden kann:

@Retention(RUNTIME)

@interface Testversion {

   boolean value();

}

Komplexere Annotationen werden ähnlich ausgewertet. Aus ihnen müssen die Elemente einzeln selektiert werden:

Person ersteKunde = Unternehmen.class.getAnnotation(Kunden.class)[0];

Auf ähnliche Weise funktionieren alle Werkzeuge, die Annotationen auswerten. Es gibt mehrere Arten von ihnen:

1.       Introspektoren; das sind vom Interpreter ausgeführte Java-Programme, die sich selbst (evtl. andere Klassen) auf Annotationen untersuchen

2.       (typischerweise Java-) Programme, die geladene Java-Klassen untersuchen

3.       Programme, die .class-Dateien untersuchen, ohne sie auszuführen

4.       Programme, die Java-Quelltexte untersuchen, die möglicherweise gar nicht übersetzt werden.

Beispiele hierfür sind Frameworks und IDEs, die jetzt häufig Annotationen anstelle von externen Metainformationen (z.B. in XML-Dokumenten) verwenden, um das Framework- oder IDE-spezifische Verhalten von Programmelementen zu definieren. Beispielsweise verwendet JUnit die spezielle Annotationen @Before und @After um bestimmte Methoden vor und nach dem Test auszuführen.

Annotationen für Dokumentationen

Die folgenden Namen für Annotationen wurden konventionsgemäß für Dokumentationskommentare reserviert:

@author

@version

@param

@return

@exception und @throws

@see        

@since      

@serial oder @serialField oder @serialData

@deprecated

Diese wurden allerdings nicht in den Standardklassen als interface vereinbart, weil sie in den Kommentaren nicht vom Compiler als Annotationen erkannt, nur von javadoc ausgewertet werden.


Annotationen.pdf

Version: 20. Februar 2011

© Prof. Solymosi, 2010, Beuth-Hochschule für Technik Berlin, Faculty for Computer Science and Media

solymosibht-berlin.de

[1] etwas verwirrend: Aus Benutzersicht werden diese Methoden wie Variablen verwendet, und sie liefern immer konstante Ergebnisse.

[2] mit einer nur für Annotationen geltender Syntax

[3] true nur wenn sie mit @Retention(RUNTIME)vereinbart wurde