Im folgenden Beispiel wollen wir ein kleines Doclet schreiben, das Klassen, Methoden und Konstruktoren ausgibt, die das Tag @since 1.8 (bzw. @since 8, was aber eigentlich falsch ist) tragen. So lässt sich leicht ermitteln, was in der Version Java 8 alles hinzugekommen ist. Doclets werden normalerweise von der Kommandozeile aufgerufen und dem javadoc-Tool übergeben. Unser Programm vereinfacht das, indem es direkt das Tool über Java mit dem passenden Parameter aufruft. tools.jar muss dafür im Klassenpfad sein und die Dokumentation ausgepackt am angegeben Ort.

package com.tutego.tools.javadoc;

import java.util.*;
import java.util.function.Predicate;
import com.sun.javadoc.*;
import com.sun.tools.javadoc.Main;

public class SinceJava8FinderDoclet {

  public static boolean start( RootDoc root ) {
    for ( ClassDoc clazz : root.classes() )
      processClass( clazz );
    return true;
  }

  private static void processClass( ClassDoc clazz ) {
    Predicate<Tag> isJava18 = tag -> tag.text().equals( "8" ) || tag.text().equals( "1.8" );

    if ( Arrays.stream( clazz.tags( "since" ) ).anyMatch( isJava18 ) )
      System.out.printf( "Neuer Typ %s%n", clazz );

    for ( MethodDoc method : clazz.methods() )
      if ( Arrays.stream( method.tags( "since" ) ).anyMatch( isJava18 ) )
        System.out.printf( "Neue Methode %s%n", method );

    for ( ConstructorDoc constructor : clazz.constructors() )
      if ( Arrays.stream( constructor.tags( "since" ) ).anyMatch( isJava18 ) )
        System.out.printf( "Neuer Konstruktor %s%n", constructor );

    for ( FieldDoc field : clazz.fields() )
      if ( Arrays.stream( field.tags( "since" ) ).anyMatch( isJava18 ) )
        System.out.printf( "Neues Attribut %s%n", field );
  }

  public static void main( String[] args ) {
    String[] params = {
        "-quiet", "-XDignore.symbol.file",
        "-doclet", SinceJava8FinderDoclet.class.getName(),
        "-sourcepath", "C:/Program Files/Java/jdk1.8.0/src/",
//        "java.lang",  // Nur java.lang
        "-subpackages", "java:javax"  // Alles rekursiv unter java.* und javax.*
    };
    Main.execute( params );
  }
}

Unsere main(String[])-Methode ruft das JDK-Doclet-Programm über Main.execute(String[]) auf und übergibt die eigene Doclet-Klasse per Parameter – die Argumente von execute(String[]) erinnern an die Kommandozeilenparameter. Das Doclet-Hauptprogramm wiederum ruft unsere start(RootDoc root)-Methode auf – das Gleiche würde auch passieren, wenn das Doclet von außen über javadoc aufgerufen würde. Unser start(RootDoc) läuft über alle ermittelten Typen und übergibt zum Abarbeiten der Innereien die Verantwortung an processClass(ClassDoc). Die Metadaten kommen dabei über diverse XXXDoc-Typen. Ein Precidate zieht den Tag-Test heraus, ein weiterer Einsatz der neuen Java 8 Streams würde das Programm nicht übersichtlicher machen.

Das Programm nutzt ein paar Tricks, um die Ausgabe auf das Wesentliche zu konzentrieren. Der Schalter –quit schaltet den üblichen Ladestatus, der zu Ausgaben wie

Loading source files for package java.lang…

Loading source files for package java.applet…

Loading source files for package java.awt…

führt ab.

Der Schalter -XDignore.symbol.file wiederum unterdrückt Meldungen wie diese hier:

C:\…\src\java\lang\Class.java:57: warning: Unsafe is internal proprietary API and may be removed in a future release

import sun.misc.Unsafe;

^

Die Meldungen landen auf dem System.err-Kanal, sodass sie sich auch mit System.setErr(…) in einem ausgabeverwerfenden Strom geschickt werden können um sie zu unterdrücken.

Normalerweise nutzen Entwickler Annotationen wie einmalige Modifizierer, und es ergibt keinen Sinn, etwa @Override @Override String toString() zu schreiben, genauso wenig wie es keinen Sinn ergibt final static final double PI zu deklarieren. Doch da es durchaus Meta-Daten gibt, die mehrmals auftauchen können, gibt es seit Java 8 eine Erweiterung, dass Annotationen wiederholt werden dürfen. Allerdings müssen die Annotationstypen dieser wiederholbaren Annotationen selbst mit einer besonderen Meta-Annotation @Repeatable ausgezeichnet werden. Damit ist es aber noch nicht getan, denn @Repeatable muss als Element einen Typ bekommen, der den Container angibt.

Beispiel: Der Annotationstyp für Autoren kann so aussehen:

public @interface Author { String name(); }

Soll nun die Annotation mehrfach verwendet werden, ist die Meta-Annotation nötig und mit ihr die Angabe eines Containers:

@Repeatable( Authors.class )
public @interface Author { String name(); }

Der Container ist selbst ein Annotationstyp mit einem Feld als Element. Der Typ des Feldes ist exakt der wiederholbare Annotationstyp.

public @interface Authors {
  Autor[] value;
}

Ohne @Repeatable am Annotationstyp wird eine mehrmalige Verwendung einer Annotation zu einem Compilerfehler führen. Im Java SE 8 gibt es bisher keine Verwendung dieses Annotationstyps, also auch keine wiederholbaren Annotationen.

Die Meta-Annotation @java.lang.annotation.Target beschreibt, wo eine Annotation angeheftet werden kann. Ist kein ausdrückliches @Target gewählt, gilt es für alle Elemente, die Annotation kann also etwa an Klassen stehen, aber auch an lokalen Variablen. In der Regel gibt es bei @Target ein Element, und das ist von der Aufzählung java.lang.annotation.ElementType; es deklariert die folgenden Ziele:

ElementType	Erlaubt Annotationen …
ANNOTATION_TYPE	nur an anderen Annotationstypen, was @Target(ANNOTATION_TYPE) somit zu einer Meta-Annotation macht.
TYPE	an allen Typdeklarationen, also Klassen, Schnittstellen, Annotationstypen, Aufzählungen.
CONSTRUCTOR	an Konstruktor-Deklarationen
METHOD	an Deklarationen von statischen und nicht-statischen Methoden.
FIELD	an Deklarationen von statischen Variablen und Objekt-Variablen.
PARAMETER	an Parametervariablen von Methoden.
LOCAL_VARIABLE	an lokalen Variablen.
PACKAGE	an package-Deklarationen.
TYPE_PARAMETER	an der Deklaration einer Typ-Variablen für generische Typ-Parameter. Neu in Java 8. Wenn es etwa heißt class List<@AnAnnotation T>.
TYPE_USE	an allen Stellen, wo Typen eingesetzt werden, adressiert also Typ-Annotationen. Ebenfalls neu in Java 8. So etwas wie @NonNull (keine Annotation aus der Java SE!) ist ein Beispiel

Tabelle 1.3: ElementType bestimmt Orte, an denen Annotationen erlaubt sind.

Annotationen lasen sich setzen an allen Deklarationen und bei Typnutzungen (ab Java 8).

Deklarationen	Typnutzung
Typendeklarationen (Klassen, Schnittstellen, Aufzählungen, anderen Annotationtypen)	new-Operator
Eigenschaften (Konstruktoren, Methoden, Attributen)	Typ-Anpassung
	implements-Klausel
	throws-Klausel bei Methoden

Wo Annotationen möglich sind

Die Annotationen bei der Typnutzung nennen sich kurz Typ-Annotationen.

Java bringt einige Annotationstypen mit, doch die werden bisher ausschließlich für Deklarationen eingesetzt, wie das gekannte @Override. Vordefinierte Typ-Annotationen sind bisher in der Java SE nicht zu finden.