Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / Java

Annotation types — @interface

An @interface declaration defines an annotation type: metadata attached to code. Elements describe the annotation's data, while meta-annotations control allowed locations, retention, repeatability, and inheritance.

Version: 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 defines an annotation type. An element such as String value(); is a parameterless method without a body. Allowed types are primitives, String, Class, enums, annotation types, and one-dimensional arrays of these; values cannot be null. An element without default is required. @Label("demo") abbreviates @Label(value = "demo") when the other elements have defaults.

@Retention controls metadata lifetime: RetentionPolicy.SOURCE means discarded by the compiler, RetentionPolicy.CLASS means recorded in the class file without guaranteed reflective availability, and RetentionPolicy.RUNTIME means retained at runtime. Reflective access, however, depends on where the annotation is used. For example, a type-use annotation on a cast with RetentionPolicy.RUNTIME can be recorded in the class file, but the standard reflection API in Java SE 21 does not expose it. Declaration annotations on local variables or lambda parameters are not recorded in the class file, even with RetentionPolicy.RUNTIME. Without @Retention, RetentionPolicy.CLASS applies. An annotation does not execute logic itself: a tool or code must interpret it.

@Target restricts legal locations. ElementType.TYPE covers class, interface, enum, and record declarations; ElementType.FIELD covers fields, including enum constants; ElementType.METHOD covers methods; ElementType.CONSTRUCTOR covers constructors. ElementType.TYPE does not mean arbitrary uses of a type: that is the role of ElementType.TYPE_USE.

@Repeatable identifies a container that permits repeated annotations of the same type. The container declares value() returning an array of the repeated type, and its other elements must have defaults. It must also satisfy the JLS compatibility rules for retention, targets, and meta-annotations.

@Inherited lets appropriate reflective queries for class annotations search superclasses. It neither transfers annotations from implemented interfaces nor causes annotations on methods, fields, or constructors to be inherited. The example demonstrates four allowed targets and reads an explicit value and a default value.

Examples

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

Result

demo:0
read:2

The displayed code and declared result were verified in an isolated environment using the method recorded in the verification evidence for this exact version.

Sources