4Developers 2022: Explaining annotation magic

### Overview In this talk from 4Developers 2022, Tomasz Borek sets out to demystify Java annotations and dispel the notion that they rely on impenetrable "dark reflection magic." Explaining that annotations are simply code and metadata used for meta-programming, Borek traces their evolution from early marker interfaces like `Serializable` and `Cloneable` to the formal introduction of annotations in Java 5. The presentation walks through basic mechanics, targeting, retention policies, built-in annotations, runtime reflection, classpath scanning alternatives, code generation via Project Lombok versus Java records, and compile-time annotation processing.

### Key Topics - **Origins and Purpose of Annotations**: Early Java used marker interfaces with no methods to convey intent or capability. Annotations formalized this as structured metadata that can signal intent, instruct compilers or build tools, or trigger behavior at runtime. - **Annotation Targets and Retention Policies**: Discussion of `ElementType` targets (classes, methods, fields, parameters, packages, records, etc.) and `RetentionPolicy` levels (`SOURCE`, `CLASS`, and `RUNTIME`), highlighting that only `RUNTIME` annotations remain accessible when an application executes. - **Standard Built-in Annotations**: Analysis of built-in annotations including `@Override`, `@FunctionalInterface`, and `@SuppressWarnings`. The talk highlights common traps, such as placing `@SuppressWarnings` too broadly or relying on it without checking compiler warnings. - **Building a Custom Test Runner with Reflection**: Demonstration of building a basic test runner using Java reflection to discover methods marked with custom `@Test` and `@Ignore` annotations. - **Classpath Scanning vs. Indexing**: How frameworks like Spring scan the classpath (e.g., using libraries like Reflections) and why scanning large classpaths with jars and zip files incurs performance overhead ($O(N)$), contrasted with indexing techniques using the ClassIndex library. - **Code Generation (Lombok vs. Records)**: Comparing boilerplate reduction using Project Lombok (e.g., `@Value`) against built-in Java records introduced in Java 14. - **Compile-Time Annotation Processing**: Introduction to writing custom compile-time annotation processors by extending `AbstractProcessor` to inspect elements and generate code or diagnostic messages during compilation.

### Technical Details - **Targeting**: Demonstrated declaring annotations without `@Target` (which allows them almost everywhere except certain type uses) versus scoping them strictly to `ElementType.LOCAL_VARIABLE` or `ElementType.METHOD`. - **Retention Behavior**: Inspected bytecode and runtime reflection calls to show that `@Retention(RetentionPolicy.SOURCE)` annotations disappear after compilation, while `@Retention(RetentionPolicy.RUNTIME)` annotations remain accessible via reflection methods such as `isAnnotationPresent()`. - **Reflection Mechanism**: Constructed a runner executing `clazz.getDeclaredMethods()`, filtering methods using reflection streams for `@Test`, checking optional parameters like an `ignore` boolean attribute, and invoking test methods using `Method.invoke()`. - **Classpath Scanning Performance**: Discussed how Reflections-style scanning inspects packages, archives, and jars on the classpath, contrasting it with compile-time indexing using the Polish library `ClassIndex` to track annotated types without runtime scanning. - **Package-Level Annotations**: Explained the role of `package-info.java` as a dedicated file to hold package-level annotations and documentation, referencing `java.util.concurrent` as an example. - **Lombok vs. Records**: Showed how Lombok's `@Value` generates getters, `equals()`, `hashCode()`, `toString()`, and constructors, versus native Java records, noting Lombok provides more customization (such as `@NonFinal` and no-arg constructors). - **AbstractProcessor**: Outlined the core structure of an annotation processor, including defining supported annotation types, supported source versions, and implementing the `process()` method using `RoundEnvironment` and diagnostic messaging.

### Takeaways Annotations are not magical constructs but straightforward mechanisms grounded in metadata, reflection, and compiler processing. Developers should understand retention policies to avoid expecting source-level annotations at runtime, scope targeting appropriately, avoid blanket use of `@SuppressWarnings`, and weigh the trade-offs between expensive runtime classpath scanning and compile-time indexing or processing. When choosing between Lombok and Java records, native records are preferable for simple, immutable data carriers, whereas Lombok remains useful when specialized configurability is required.