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
- Java SE 21 API — Class.getAnnotationsByType
- Java SE 21 API — Class.isAnnotationPresent
- Java SE 21 API — Class.getDeclaredAnnotationsByType
- Java SE 21 API — Class.getDeclaredAnnotation
- Java SE 21 API — AnnotatedElement: kinds of annotation presence
- Java SE 21 API — Inherited
- Java SE 21 API — RetentionPolicy.RUNTIME
- Java Language Specification, Java SE 21 — §9.6.3 Repeatable Annotation Interfaces
- Java Language Specification, Java SE 21 — §9.7.5 Multiple Annotations of the Same Interface
- Java Language Specification, Java SE 21 — §15.8.2 Class Literals