Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Java Annotations: Syntax, Retention, and Runtime Use

A practical guide to Java annotations: declaration syntax, retention policies, reflection-based runtime lookup, and common pitfalls when creating custom annotations.

~5 min readJava
#java#annotations#reflection#custom-annotations
Illustration of a Java class blueprint with annotation tags attached and a magnifying glass representing runtime reflection

Java annotations are metadata attached to declarations in source code. They do not change the behavior of the annotated code by themselves; instead, they carry information that a compiler, framework, or runtime can read and act on. A method annotated with @Override is not executed differently because of the annotation. The compiler uses it to verify that the method actually overrides a superclass method and reports an error when it does not.

Annotations can appear on types, methods, fields, parameters, local variables, and even on other annotations. Their placement is controlled by the @Target meta-annotation, which is declared on the annotation type itself. When you see @Deprecated on a class or @Autowired on a field, you are looking at metadata that influences tooling or framework behavior, not the direct execution of the code.

Built-In Annotations You Will Encounter

The Java language ships with several built-in annotations that appear in almost any project. The most common are @Override, @Deprecated, and @SuppressWarnings. The compiler treats these specially.

@Override tells the compiler that the annotated method overrides a method from a superclass or implements an interface method. If no such method exists, the compiler raises an error. @Deprecated marks an element as no longer recommended for use, and the compiler emits a warning when other code references it. @SuppressWarnings suppresses compiler warnings for the annotated element, such as unchecked casts or unused variables.

Beyond these, the standard library provides annotations used by the runtime and by tools. @FunctionalInterface tells the compiler that an interface is intended to be a functional interface, meaning it has exactly one abstract method. That property is what makes the interface usable with a lambda expression. The annotation itself is not required for lambda use, but it makes the compiler report an error if a second abstract method is added. @SafeVarargs suppresses warnings about unsafe varargs usage in generic methods.

Retention Policies Control the Annotation Lifecycle

A key decision when creating an annotation is its retention policy. The @Retention meta-annotation determines how long the annotation is kept:

RetentionPolicyStored in class fileVisible via reflection at runtimeTypical use
SOURCENoNoCode generators, source-level tools
CLASSYesNoDefault retention; bytecode tools
RUNTIMEYesYesFrameworks, reflection-based processing

Most frameworks that read annotations at runtime, such as Spring or JUnit, require RUNTIME retention. If you write a custom annotation and forget the retention policy, it defaults to CLASS, which means reflection will not see it. This is one of the most common mistakes when defining custom annotations.

Declaring a Custom Annotation

Declaring an annotation type uses the @interface keyword. The declaration looks like an interface, but the members are called elements, not methods, and they cannot have parameters or throw exceptions.

java
import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.METHOD) public @interface LogExecution { String level() default "INFO"; boolean includeArgs() default false; }

This annotation can be placed on methods. It has two elements: level, which defaults to "INFO", and includeArgs, which defaults to false. When you apply it, you can provide values for either element:

java
@LogExecution(level = "DEBUG", includeArgs = true) public void processOrder(Order order) { // business logic }

Elements must be of a primitive type, String, Class, an enum, another annotation, or an array of those. They cannot be arbitrary objects. This restriction exists because annotation values are stored as constants in the class file and resolved at compile time.

Reading Annotations at Runtime with Reflection

An annotation with RUNTIME retention is visible through reflection. The java.lang.reflect.AnnotatedElement interface provides methods such as isAnnotationPresent, getAnnotation, and getAnnotations. Since Class, Method, Field, and Parameter all implement AnnotatedElement, you can inspect annotations on any of these declarations.

java
Method method = OrderService.class.getMethod("processOrder", Order.class); if (method.isAnnotationPresent(LogExecution.class)) { LogExecution config = method.getAnnotation(LogExecution.class); String level = config.level(); boolean includeArgs = config.includeArgs(); // build logging behavior from the annotation values }

This pattern is how many frameworks work internally. A framework scans classes or methods, reads annotations, and wires behavior based on the values found. When you write your own annotation processor, you are responsible for the same scanning logic, either at startup time or lazily when a method is first invoked.

Runtime Cost and Performance Considerations

Reflection-based annotation lookup is not free. Calling getAnnotation on the same method repeatedly, for example inside code that processes every request, can repeat the same reflection lookup instead of reusing a previously resolved value. In a hot path, that repeated work can add avoidable overhead, so it is a good idea to cache the result.

The practical solution is to cache the annotation lookup result. Once you have read the annotation values, store them in a map keyed by the Method or Class object and reuse them on subsequent calls. This avoids repeated reflection calls while keeping the behavior identical.

java
private final Map<Method, LogExecution> cache = new ConcurrentHashMap<>(); LogExecution config = cache.computeIfAbsent(method, m -> m.getAnnotation(LogExecution.class));

Caching is particularly important in frameworks that process many annotated methods during startup. Reading annotations once at initialization and storing the resolved configuration keeps reflection work out of the request path.

Common Mistakes and Design Constraints

Several mistakes appear regularly when developers create custom annotations. The most common is forgetting @Retention(RetentionPolicy.RUNTIME) and then wondering why getAnnotation returns null. Another is placing an annotation on the wrong target, which produces a compile-time error unless the target is broadened with @Target.

A design constraint worth respecting: annotations should carry declarative metadata, not logic. If you find yourself writing complex code to process annotations, consider whether a regular class or a configuration object would be clearer. Annotations are most maintainable when they describe intent in a compact, readable form, and the processing logic stays in a dedicated component.

Also note that annotation element values are fixed at compile time. You cannot compute a value dynamically when an application runs, and you cannot use an instance field of a class as an element value. If you need runtime-dependent configuration, a regular configuration object is the right tool, not an annotation.

Try matching browser tools

All tools

Small utilities that fit Java work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Java guides

More in Java

All Java guides

The guides filed next to this one in Java, in library order.