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.
@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
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.
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
@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),getAnnotationreturnsnullat 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:
@Overridemakes the compiler verify the override,@FunctionalInterfacechecks a single abstract method,@SafeVarargsand@SuppressWarningscontrol 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.