2.1. Grundlagen

Der Zweck einer Annotation ist es, für ein bestimmtes Programmelement wie z.B. einer Methode oder einer Klasse, zusätzliche Informationen (Metadaten) bereitzustellen. Eine Annotation kann als zusätzlicher Modifikator angesehen werden. Er besteht aus der Namensbezeichnung des Annotationstyps und kann in einem anschließenden Klammerpaar mehrere Element-Wert-Paare enthalten. Für einen Annotationstyp können verschiedene Elemente definiert werden, die mit entsprechenden Werten belegt werden können. Annotationen beginnen mit einem "@"-Zeichen, um diese als solche zu kennzeichnen. Zunächst soll aber der vordefinierte Annotationstyp Deprecated beispielhaft genannt werden, der überholte (veraltete) Methoden kennzeichnet:

@Deprecated public void ueberholteMethode() {
  ...
}

Es wird vorgeschlagen, dass Annotationen vor allen anderen Modifikatoren stehen sollten. Das ist aber nicht zwingend notwendig, auch die Modifaktorenreihenfolge public @Deprecated wäre zulässig. Eine Annotation hat den folgenden allgemeinen Aufbau:

@TypName(ElementWertPaare_opt)

Ein Beispiel hierfür mit drei Element-Wert-Paaren wäre:

@TypName(Identifier1 = ElementWert1, 
         Identifier2 = ElementWert2, 
         Identifier3 = ElementWert3)

Die Angabe von Element-Wert-Paaren ist optional und kann daher weggelassen werden. Das resultierende leere Klammerpaar könnte auch entfallen. So wäre die Bedeutung der folgenden beiden Angaben gleich:

@TypName()
@TypName

Derartige Annotationen ohne Element-Wert-Paare werden als Marker-Annotationen bezeichnet. Besitzt ein Annotationtyp hingegen nur ein einziges Element, sollte der Name (Identifier) des Solo-Elements value sein (Konvention). Bei solchen Single-Element-Annotationen kann auch eine vereifachte Notation angewendet werden. Die beiden folgenden Annotationsangaben wären gleichbedeutend:

@TypName(value = ElementWert)
@TypName(ElementWert)

Annotationen können wiederum bei anderen Annotationstyp-Deklarationen verwendet werden - sie werden dann auch als Meta-Annotationen bezeichnet.

Überblick über vordefinierte Annotationstypen

Ab Java SE 5 werden mehrere Annotationstypen standardmäßig zur Verfügung gestellt, die zunächst kurz erläutert werden sollen (eine ausführlichere Darstellung steht in Abschnitt 2.4):

Annotationstyp Deprecated. Ein Programmelement, das mit @Deprecated gekennzeichnet wurde, sollte bei der Programmerstellung nicht mehr verwendet werden, da es in Folgeversionen möglicherweise nicht mehr verfügbar sein wird oder es sollen alternativ andere Programmelemente genutzt werden. Der Compiler gibt eine Warnmeldung aus, falls ein derart gekennzeichnetes Programmelement verwendet wurde.
Annotationstyp Override. Mit @Override kann eine Methode gekennzeichnet werden, die verbindlich die Methode ihrer Oberklasse überschreibt. Falls die Superklassen-Methode nicht überschrieben wird, erzeugt der Compiler eine Fehlermeldung.
Annotationstyp SuppressWarnings. Bei Verwedung dieses Annotationstyps bei bestimmten Programmelementen, werden eventuell erzeugte Warnmeldungen unterdrückt. Um festzulegen, welche Warnmeldungen unterdrückt werden sollen, wird der Annotation ein String-Array als Argument übergeben. Das String-Array enthält die einzelnen Namensbezeichnungen der zu unterdrückenden Warnungen.
Meta-Annotationstyp Documented. Die Annotation @Documented wird innerhalb von Definitionen weiterer Annotationstypen verwendet (Meta-Annotation). Falls innerhalb einer Annotationstyp-Deklaration @Documented verwendet wird, erscheint die dadurch definierte Annotation innerhalb der API-Dokumentation des verwendenden Programms (eine API-Dokumetation kann durch Verwendung von javadoc erstellt werden).
Meta-Annotationstyp Inherited. Dieser Annotationstyp wird ebenfalls innerhalb von Definitionen weiterer Annotationstypen verwendet (Meta-Annotation). Eine unter Verwendung von @Inherited erstellten Annotation kann eine Klasse annotieren. Falls diese Klasse vererbt wird, wird auch die genannte Annotation mit vererbt.
Meta-Annotationstyp Target. Eine Target-Meta-Annotation wird bei der Definition von Annotationen verwendet. @Target bestimmt für welche Programmelemente die neu erstellte Annotation verwendet werden darf. Dazu können der Meta-Annotation verschieden Konstanten als Argument übergeben werden.
Meta-Annotationstyp Retention. Der Annotationstyp Retention (dt. Aufrechterhaltung) bestimmt wie lange Annotationen, bei deren Definition dieser Typ verwendet wurde, aufrecht erhalten werden (Zugriff auf Annotationen möglich). Dabei können der Meta-Annotation verschiedene Konstanten als Argument übergeben werden, die bestimmen, ob die Annotation eventuell auch während der Laufzeit der Anwendung augelesen werden kann.