KennisbankExamencentrum
NL · NLNederlands (Nederland)
Taal kiezen13

CKTIS / Java

Annotatietypen — @interface

Een @interface-declaratie definieert een annotatietype: metadata die aan code wordt gekoppeld. Elementen beschrijven de gegevens van de annotatie; meta-annotaties bepalen waar deze mag worden gebruikt en regelen retentie, herhaalbaarheid en overerving.

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

Syntax

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

@interface definieert een annotatietype. Een element zoals String value(); is een parameterloze methode zonder body. Toegestane typen zijn primitieve typen, String, Class, enums, annotatietypen en eendimensionale arrays daarvan; de waarde mag niet null zijn. Een element zonder default is verplicht. @Label("demo") is een verkorte vorm van @Label(value = "demo") wanneer de andere elementen standaardwaarden hebben.

@Retention bepaalt hoelang metadata bewaard blijven: RetentionPolicy.SOURCE betekent dat de compiler ze verwijdert; RetentionPolicy.CLASS betekent dat ze in het classbestand worden opgeslagen, zonder garantie dat ze via reflection beschikbaar zijn; RetentionPolicy.RUNTIME betekent dat ze ook tijdens de uitvoering bewaard blijven. Of een annotatie via reflection kan worden uitgelezen, hangt echter af van waar die wordt gebruikt. Zo kan een annotatie met RetentionPolicy.RUNTIME op het type in een cast in het classbestand worden opgeslagen, maar de standaard-API voor reflection van Java SE 21 geeft er geen toegang toe. Annotaties op declaraties van lokale variabelen of parameters van lambda-expressies worden niet in het classbestand opgeslagen, ook niet met RetentionPolicy.RUNTIME. Zonder @Retention geldt RetentionPolicy.CLASS. Een annotatie voert zelf geen logica uit: een tool of code moet deze interpreteren.

@Target beperkt de toegestane locaties. ElementType.TYPE omvat declaraties van klassen, interfaces, enums en records; ElementType.FIELD omvat velden, waaronder enumconstanten; ElementType.METHOD omvat methoden; ElementType.CONSTRUCTOR omvat constructors. ElementType.TYPE betekent niet elk willekeurig gebruik van een type: daarvoor is ElementType.TYPE_USE bedoeld.

@Repeatable wijst een container aan die herhaalde annotaties van hetzelfde type mogelijk maakt. De container declareert value(), dat een array van het herhaalde type retourneert, en de overige elementen moeten standaardwaarden hebben. Ook moet de container voldoen aan de JLS-compatibiliteitsregels voor retentie, doelen en meta-annotaties.

@Inherited zorgt ervoor dat geschikte reflectievragen naar klasseannotaties ook superklassen doorzoeken. Het draagt annotaties niet over van geïmplementeerde interfaces en zorgt er niet voor dat annotaties op methoden, velden of constructors worden overgeërfd. Het voorbeeld toont vier toegestane doelen en leest een expliciete waarde en een standaardwaarde uit.

Voorbeelden

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());
    }
}

Resultaat

demo:0
read:2

De getoonde code en het opgegeven resultaat zijn in een geïsoleerde omgeving geverifieerd met de methode die in het verificatiebewijs voor exact deze versie is vastgelegd.

Bronnen