Creating and Processing Custom Annotations in Java

You declare a custom annotation with `@interface`. Parameters are declared as methods with optional defaults — String value() default "";. The single-parameter-named-value convention enables the shorthand @MyAnn("foo").

The configuration comes from meta-annotations. `@Target` specifies where it can be applied — METHOD, TYPE, FIELD, PARAMETER. `@Retention` controls lifetime — SOURCE discards it at compile time, CLASS keeps it in bytecode but not at runtime, RUNTIME keeps it available to reflection. `@Documented` includes it in Javadoc. `@Inherited` makes it transfer to subclasses — but only for class-level annotations, not methods or fields.

The retention choice matters. Spring, Jackson, JPA, JUnit — all use reflection to read annotations at runtime, so their custom annotations need `RUNTIME` retention. Annotation processors like Lombok, AutoValue, and Dagger read annotations at compile time and generate code, so they use `SOURCE` retention — the annotation isn't even in the bytecode. Using the wrong retention breaks the framework.

Processing an annotation happens in one of three ways.

First, runtime reflection — Spring, Hibernate, Jackson. You iterate methods or fields and call getAnnotation(MyAnn.class). Simple, flexible, slightly slower at runtime.

Second, compile-time annotation processing — APT. You extend AbstractProcessor, declare @SupportedAnnotationTypes, and generate new Java source files using tools like JavaPoet. Lombok, MapStruct, Dagger, AutoValue all use this approach. Zero runtime cost because the processing is done before the program ever runs.

Third, bytecode manipulation — AspectJ, ASM, ByteBuddy. The tool directly modifies .class files after compilation. Most powerful, most complex.

For most custom annotations you'd write in an application, you want RUNTIME retention plus Spring AOP — define an @Aspect with @Around("@annotation(myAnn)") and your logic runs whenever a method with that annotation is called.