Skip to content
Tutorials Center
My learning

Topics

Java Reference ยท Keywords and Statements

Java annotation syntax

Reference for Java annotation syntax: applying annotations, declaring your own with @interface, meta-annotations, retention, targets and reading them by reflection.

An annotation attaches metadata to code: classes, methods, fields, parameters, local variables, packages, modules, and even type uses. Annotations do not change what the code does by themselves. They are read by the compiler (@Override), by build-time tools (annotation processors), or at run time by frameworks through reflection.

You apply an annotation with @Name and optional arguments in parentheses. You declare a new annotation type with @interface.

Java
@Override
public String toString() { return "x"; }

@SuppressWarnings({"unchecked", "rawtypes"})
void legacy() { }

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
@interface Audited {
    String by() default "system";
    int level() default 1;
}

Try it

Java Declaring and reading an annotation

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Java Single-value, arrays, repeatable

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Syntax

Java
@Name                      // marker annotation
@Name(value)               // single-element shorthand (element named value)
@Name(a = 1, b = "x")      // named elements

[@MetaAnnotations] @interface Name {
    Type element() [default constant];
}
Meta-annotation Purpose
@Retention SOURCE (compiler only), CLASS (in the class file, default), or RUNTIME (readable by reflection).
@Target Where the annotation may appear (TYPE, FIELD, METHOD, PARAMETER, CONSTRUCTOR, LOCAL_VARIABLE, ANNOTATION_TYPE, PACKAGE, TYPE_PARAMETER, TYPE_USE, MODULE, RECORD_COMPONENT).
@Documented Include the annotation in generated Javadoc.
@Inherited Class annotation is inherited by subclasses (classes only, not interfaces).
@Repeatable Allows repeating the annotation; needs a container annotation.

Allowed element types: primitives, String, Class, enums, other annotations, and one-dimensional arrays of those. Defaults must be constants; null is not allowed.

Usage notes

  • Retention matters most for frameworks. Without @Retention(RUNTIME), getAnnotation returns null at run time, a very common first mistake.
  • No behavior and no inheritance: annotation types cannot extend other types, and they cannot have methods with parameters. They implicitly extend java.lang.annotation.Annotation.
  • Elements are written like methods but read like properties; calling a.level() just returns the value stored in the class file.
  • Compile-time checking: @Override makes the compiler verify the override, @FunctionalInterface checks a single abstract method, @SafeVarargs and @SuppressWarnings control warnings, and @Deprecated(since = "9", forRemoval = true) marks APIs.
  • Annotation processors run during compilation and can generate code or report errors (Lombok-style libraries and MapStruct use this); they are not available in the sandbox.
  • Type annotations (TYPE_USE) can annotate types: List<@NonNull String>. They are used by static analysis tools such as the Checker Framework.
  • Order of annotations is not significant, and getDeclaredMethods() order is unspecified, which is why the examples sort the methods.
  • Records: annotations on a record component propagate to the field, accessor, or constructor parameter depending on their @Target.
  • Keep it lean. An annotation-heavy design hides logic; use annotations for declarative information, not control flow.