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

CKTIS / Java

Types d’annotations — @interface

Une déclaration @interface définit un type d’annotation, c’est-à-dire des métadonnées associées au code. Les éléments décrivent les données de l’annotation, tandis que les méta-annotations contrôlent les emplacements autorisés, la rétention, la répétition et l’héritage.

Version : Java SE 21; repository runtime, production runtime not attested

Syntaxe

@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE, ElementType.FIELD, ElementType.METHOD, ElementType.CONSTRUCTOR})
@interface Label {
    String value();
    int priority() default 0;
}

@interface définit un type d’annotation. Un élément tel que String value(); est une méthode sans paramètre et sans corps. Les types autorisés sont les types primitifs, String, Class, les enums, les types d’annotation et leurs tableaux à une dimension ; une valeur ne peut pas être null. Un élément sans default est obligatoire. @Label("demo") est une forme abrégée de @Label(value = "demo") lorsque les autres éléments ont des valeurs par défaut.

@Retention détermine la durée de conservation des métadonnées : RetentionPolicy.SOURCE signifie que le compilateur les élimine ; RetentionPolicy.CLASS signifie qu’elles sont enregistrées dans le fichier de classe sans garantie d’accès par réflexion ; RetentionPolicy.RUNTIME signifie qu’elles sont conservées à l’exécution. L’accès par réflexion dépend toutefois de l’emplacement de l’annotation. Par exemple, une annotation avec RetentionPolicy.RUNTIME qui porte sur l’utilisation d’un type dans une conversion explicite (cast) peut être enregistrée dans le fichier de classe, mais l’API de réflexion standard de Java SE 21 ne permet pas d’y accéder. Les annotations qui portent sur les déclarations de variables locales ou de paramètres d’expressions lambda ne sont pas enregistrées dans le fichier de classe, même avec RetentionPolicy.RUNTIME. Sans @Retention, RetentionPolicy.CLASS s’applique. Une annotation n’exécute pas elle-même de logique : un outil ou du code doit l’interpréter.

@Target limite les emplacements autorisés. ElementType.TYPE concerne les déclarations de classes, d’interfaces, d’enums et de records ; ElementType.FIELD concerne les champs, y compris les constantes d’enum ; ElementType.METHOD concerne les méthodes ; ElementType.CONSTRUCTOR concerne les constructeurs. ElementType.TYPE ne signifie pas que l’annotation peut être utilisée partout où apparaît un type : c’est le rôle de ElementType.TYPE_USE.

@Repeatable indique un conteneur qui permet de répéter une annotation du même type. Le conteneur déclare value(), qui renvoie un tableau du type répété, et ses autres éléments doivent avoir des valeurs par défaut. Il doit également respecter les règles de compatibilité du JLS concernant la rétention, les cibles et les méta-annotations.

@Inherited permet aux requêtes de réflexion appropriées sur les annotations de classe de parcourir les superclasses. Il ne transmet pas les annotations des interfaces implémentées et ne fait pas hériter les annotations des méthodes, des champs ou des constructeurs. L’exemple montre quatre cibles autorisées et lit une valeur explicite ainsi qu’une valeur par défaut.

Exemples

import java.lang.annotation.*;

public class Main {
    @Retention(RetentionPolicy.RUNTIME)
    @Target({ElementType.TYPE, ElementType.FIELD,
             ElementType.METHOD, ElementType.CONSTRUCTOR})
    public @interface Label {
        String value();
        int priority() default 0;
    }

    @Label("demo")
    static class Item {
        @Label("id")
        int id;

        @Label("create")
        Item() {}

        @Label(value = "read", priority = 2)
        void read() {}
    }

    public static void main(String[] args) throws ReflectiveOperationException {
        Label type = Item.class.getAnnotation(Label.class);
        Label method = Item.class.getDeclaredMethod("read").getAnnotation(Label.class);
        System.out.println(type.value() + ":" + type.priority());
        System.out.println(method.value() + ":" + method.priority());
    }
}

Résultat

demo:0
read:2

Le code affiché et le résultat déclaré ont été vérifiés dans un environnement isolé selon la méthode consignée dans la preuve de vérification de cette version exacte.

Sources