Base de connaissancesCentre d’examen
FRFrançais
Choisir la langue13

CKTIS / Java

Lire les annotations de classe par réflexion

Récupérez les annotations répétables dans un tableau et testez la présence d’une annotation marqueur. Distinguez la recherche avec héritage de celle limitée à la classe examinée.

Version : Java SE 21

Syntaxe

On java.lang.Class<T> (instance methods; Annotation is java.lang.annotation.Annotation):
<A extends Annotation> A[] getAnnotationsByType(Class<A> annotationClass)
boolean isAnnotationPresent(Class<? extends Annotation> annotationClass)
<A extends Annotation> A[] getDeclaredAnnotationsByType(Class<A> annotationClass)
<A extends Annotation> A getDeclaredAnnotation(Class<A> annotationClass)

Class literals: Child.class has type Class<Child>; Tag.class has type Class<Tag>.
Example call: Child.class.getAnnotationsByType(Tag.class)

Le littéral de classe Child.class fournit l’objet Class<Child> à inspecter ; Tag.class fournit l’objet Class<Tag> qui désigne le type d’annotation recherché. Il s’agit de méthodes d’instance de Class : il n’est pas nécessaire de créer un objet Child. Pour lire par réflexion les annotations d’une déclaration de classe, annotez leur type avec @Retention(RetentionPolicy.RUNTIME).

getAnnotationsByType(Tag.class) renvoie un Tag[], ou un tableau vide et non null s’il n’y a aucun résultat. La méthode extrait les annotations du conteneur désigné par @Repeatable, dans l’ordre de ses éléments. Si le type recherché porte @Inherited et si la classe ne contient aucune correspondance, ni directement ni dans le conteneur, la recherche remonte les superclasses, pas les interfaces. Elle ne combine pas les résultats de plusieurs niveaux. getDeclaredAnnotationsByType extrait aussi les annotations du conteneur, mais ne consulte que la classe examinée.

isAnnotationPresent(A.class) renvoie un boolean et équivaut à getAnnotation(A.class) != null. Cette méthode est utile pour les annotations marqueurs, dépourvues d’éléments. En l’absence de correspondance directe, si le type recherché porte @Inherited, elle consulte les superclasses, pas les interfaces. Elle ne regarde pas dans le conteneur : des répétitions présentes uniquement dans celui-ci ne donnent pas true pour le type répétable. getDeclaredAnnotation ne cherche qu’une correspondance directe sur la classe et renvoie null s’il n’en trouve pas.

Toutes les méthodes ci-dessus qui prennent un type d’annotation lèvent une NullPointerException pour un argument null. Pour tester l’existence d’au moins une correspondance, y compris dans le conteneur, utilisez getAnnotationsByType(Tag.class).length > 0.

Exemples

import java.lang.annotation.*;
import java.util.Arrays;

public class AnnotationDemo {
    @Retention(RetentionPolicy.RUNTIME)
    @Target(ElementType.TYPE)
    @Inherited
    @interface Flag {}

    @Retention(RetentionPolicy.RUNTIME)
    @Target(ElementType.TYPE)
    @Inherited
    @Repeatable(Tags.class)
    @interface Tag { String value(); }

    @Retention(RetentionPolicy.RUNTIME)
    @Target(ElementType.TYPE)
    @Inherited
    @interface Tags { Tag[] value(); }

    @Flag
    @Tag("alpha")
    @Tag("beta")
    static class Base {}

    static class Child extends Base {}

    @Tag("local")
    static class Local extends Child {}

    public static void main(String[] args) {
        System.out.println("Child tags: " + values(Child.class.getAnnotationsByType(Tag.class)));
        System.out.println("Child declared tags: " + Child.class.getDeclaredAnnotationsByType(Tag.class).length);
        System.out.println("Child flag: " + Child.class.isAnnotationPresent(Flag.class));
        System.out.println("Child declared flag: " + (Child.class.getDeclaredAnnotation(Flag.class) != null));
        System.out.println("Base Tag present: " + Base.class.isAnnotationPresent(Tag.class));
        System.out.println("Local tags: " + values(Local.class.getAnnotationsByType(Tag.class)));
    }

    private static String values(Tag[] tags) {
        return Arrays.stream(tags).map(Tag::value).toList().toString();
    }
}

Résultat

Child tags: [alpha, beta]
Child declared tags: 0
Child flag: true
Child declared flag: false
Base Tag present: false
Local tags: [local]

`Child` hérite de `@Flag` et des deux occurrences de `@Tag`, mais n’en déclare aucune. Les deux occurrences de `@Tag` sur `Base` sont stockées dans le conteneur `@Tags` : le test de présence de `Tag.class` sur `Base` renvoie donc `false`. L’annotation `@Tag` de `Local` prend la place des occurrences héritées dans le résultat, au lieu de s’y ajouter.

Leçons associées

  • Java · Leçon 58 · Avancé · Version : 2

Sources