CKTIS / Java
Annotations Java : cibles, rétention, répétition et réflexion
Dans Java SE 21, une déclaration d’annotation définit ses données, ses emplacements autorisés et sa visibilité à l’exécution. Apprenez à lire ces métadonnées par réflexion, à repérer les annotations héritées et à limiter la suppression des avertissements.
Version : Java SE 21
Syntaxe
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE, ElementType.FIELD, ElementType.CONSTRUCTOR})
@interface Marker {}
@Target({ElementType.FIELD, ElementType.METHOD})
@interface MemberMarker {}
@Inherited
@Repeatable(Tags.class)
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@interface Tag { String value(); }
@Inherited
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@interface Tags { Tag[] value(); }
Consumer<? super Integer> subscriber = new Consumer<Number>() {
@Override public void accept(Number value) { System.out.println(value); }
};
Class<?> type = String.class;
Object payload = List.of("ok");
@SuppressWarnings("unchecked")
List<String> names = (List<String>) payload;@interface déclare une interface d’annotation. String value(); définit un élément et @Tag("core") abrège @Tag(value = "core"). La méta-annotation Target de java.lang.annotation fixe les emplacements autorisés. @Target(ElementType.TYPE/FIELD/CONSTRUCTOR) est un raccourci descriptif, pas une syntaxe Java : écrivez @Target({ElementType.TYPE, ElementType.FIELD, ElementType.CONSTRUCTOR}). ElementType.TYPE vise les déclarations de classes et d’interfaces, pas les utilisations d’un type (TYPE_USE). ElementType.FIELD/METHOD désigne deux constantes : ElementType.FIELD pour les champs et ElementType.METHOD pour les méthodes. Les constructeurs ont une cible distincte.
Retention règle la durée de conservation : SOURCE ne figure pas dans le fichier de classe, CLASS, par défaut, y est enregistré mais n’est pas exposé par réflexion à l’exécution, et @Retention(RetentionPolicy.RUNTIME) rend les annotations de l’exemple accessibles par réflexion. Les annotations de déclaration des variables locales et des paramètres de lambda font exception : elles ne sont pas stockées dans le fichier de classe. Un littéral de classe comme Base.class donne un objet Class<Base> ; Class<?> l’accepte sans exposer l’argument de type précis. ConfigKey, Init, Component et Inject sont des métadonnées personnalisées : sans code pour les interpréter, elles ne configurent, n’appellent ni n’injectent rien.
@Repeatable(Tags.class) autorise plusieurs @Tag au même emplacement. Le compilateur les regroupe dans un conteneur avec Tag[] value() ; ses autres éléments éventuels doivent avoir une valeur par défaut. Le conteneur doit avoir une rétention au moins aussi longue et des cibles compatibles ; ici les cibles sont identiques. Si Tag porte @Inherited, le conteneur doit aussi le porter. getAnnotationsByType(Tag.class) déballe le conteneur et, grâce à Inherited, consulte les superclasses si la classe n’a pas ses propres tags. Il ne fusionne pas les tags de plusieurs niveaux, ne consulte pas les interfaces et n’hérite pas des annotations de méthode ou de champ. getDeclaredAnnotationsByType déballe aussi le conteneur, sans consulter les superclasses ; getAnnotation ne déballe pas le conteneur.
new Consumer<Number>() { ... } déclare et instancie une classe anonyme. @Override permet au compilateur de vérifier que accept(Number) implémente la méthode de l’interface au lieu de la surcharger par erreur. Java 21 admet aussi les signatures équivalentes pour la redéfinition à celles des méthodes publiques de Object, et les accesseurs explicites de composants de record.
Consumer<? super Integer> accepte un consommateur de Integer ou d’un de ses supertypes, comme Number ou Object, et on peut lui passer un Integer. Le joker non borné ?, comme dans Consumer<?>, laisse l’argument de type inconnu : on ne peut pas lui passer un Integer non nul. @SuppressWarnings("unchecked") masque l’avertissement du compilateur, mais ne vérifie pas les types des éléments de la liste et n’empêche pas une ClassCastException. Évitez les conversions de type inutiles ; si l’une est justifiée, supprimez l’avertissement sur la déclaration la plus limitée où cela fonctionne.
Exemples
import java.lang.annotation.ElementType;
import java.lang.annotation.Inherited;
import java.lang.annotation.Repeatable;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import java.util.List;
import java.util.function.Consumer;
public class Demo {
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.FIELD)
@interface ConfigKey { String value(); }
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
@interface Init {}
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@interface Component {}
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD, ElementType.CONSTRUCTOR})
@interface Inject {}
@Inherited
@Repeatable(Tags.class)
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@interface Tag { String value(); }
@Inherited
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@interface Tags { Tag[] value(); }
@Component
@Tag("core")
@Tag("fast")
static class Base {
@ConfigKey("port") final int port = 8080;
boolean started;
@Inject Base() {}
@Init void start() { started = true; }
}
static class Child extends Base {}
static void publish(Consumer<? super Integer> subscriber) {
subscriber.accept(21);
}
public static void main(String[] args) throws ReflectiveOperationException {
Class<?> type = Base.class;
Base service = new Base();
var field = type.getDeclaredField("port");
System.out.println("Config: " + field.getAnnotation(ConfigKey.class).value());
boolean before = service.started;
var method = type.getDeclaredMethod("start");
if (method.isAnnotationPresent(Init.class)) {
method.invoke(service);
}
System.out.println("Started: " + before + " -> " + service.started);
System.out.println("Component/Inject: " + type.isAnnotationPresent(Component.class)
+ "/" + type.getDeclaredConstructor().isAnnotationPresent(Inject.class));
Tag[] tags = Child.class.getAnnotationsByType(Tag.class);
int declared = Child.class.getDeclaredAnnotationsByType(Tag.class).length;
System.out.println("Tags: " + tags[0].value() + ", " + tags[1].value()
+ "; declared: " + declared);
publish(new Consumer<Number>() {
@Override public void accept(Number value) {
System.out.println("Subscriber: " + value);
}
});
Object payload = List.of("ok"); // This list is known here to contain only strings.
@SuppressWarnings("unchecked")
List<String> names = (List<String>) payload;
System.out.println("Cast: " + names.get(0));
}
}Résultat
Config: port Started: false -> true Component/Inject: true/true Tags: core, fast; declared: 0 Subscriber: 21 Cast: ok
`started` ne change qu’à l’appel explicite de `method.invoke(service)`. `Child` lit deux tags de `Base` sans en déclarer. La conversion de type est justifiée ici par l’origine connue de la liste, `List.of("ok")`, et non par `@SuppressWarnings`.
Leçons associées
- Java · Leçon 44 · Avancé · Version : 2
- Java · Leçon 54 · Avancé · Version : 2
- Java · Leçon 58 · Avancé · Version : 2
- Java · Leçon 59 · Avancé · Version : 2
Sources
- Java SE 21 Language Specification §9.6 — Annotation Interfaces and Predefined Annotation Interfaces
- Java SE 21 Language Specification §9.7.5 — Multiple Annotations of the Same Interface
- Java SE 21 API — ElementType
- Java SE 21 API — RetentionPolicy
- Java SE 21 API — AnnotatedElement
- Java SE 21 API — SuppressWarnings
- Java SE 21 Language Specification §4.5.1 — Type Arguments of Parameterized Types
- Java SE 21 Language Specification §15.8.2 — Class Literals
- Java SE 21 Language Specification §15.9.5 — Anonymous Class Declarations