Built-in and custom annotations

For this lesson, we'll focus on the five built-in annotations you'll use every week, the meta-annotations that control where an annotation can go and how long it survives, writing and reading your own, and processors that check annotations while javac runs. Interviewers ask about annotations because one question ("what does @Retention do?") quickly shows whether you understand the difference between compile time and runtime, which is the whole foundation of how frameworks work.

01Picture it first: sticky notes with an expiry date

Think of annotations as sticky notes on your code, each with an expiry date. Some notes are for the compiler only and get thrown away when compiling finishes (SOURCE). Some are stapled into the class file for bytecode tools but nobody at runtime can see them (CLASS). And some stay readable for the whole life of the program, so a framework can walk up and read them (RUNTIME).

This diagram follows one class through compilation and shows which notes survive each stage.

Fig. 1

SOURCE annotations are discarded by javac, CLASS annotations are stored in the class file as invisible attributes, and RUNTIME annotations are stored as visible attributes that reflection can read

Notice that CLASS is the default. If you write a custom annotation and forget @Retention, it compiles, it shows up in javap, and getAnnotation still returns null. That one detail causes more "my annotation is ignored" bugs than anything else in this lesson.

02The built-in annotations under the hood

class LegacyGateway {
    @Deprecated(since = "3.2", forRemoval = true)
    public void chargeV1(long cents) { }
}

class PaymentGateway extends LegacyGateway {
    @Override
    public String toString() { return "PaymentGateway"; }   // ok: overrides Object.toString()

    @Override
    public boolean equals(PaymentGateway other) { return true; }
    // compile error: method does not override or implement a method from a supertype

    @SuppressWarnings("removal")
    void migrate() { chargeV1(100); }                         // warning suppressed
}

@FunctionalInterface
interface FeeRule {
    long feeFor(long cents);
    String toString();                       // fine: Object's methods don't count
    // long refundFeeFor(long cents);        // adding this would be a compile error
}

Here's what each one actually does:

• @Override (retention SOURCE) makes the compiler prove the method overrides or implements something. The equals(PaymentGateway) above is an overload, not an override, and without @Override it would compile silently and HashSet would never call it. Effective Java Item 40 says to put it on every override for this reason.
• @Deprecated (retention RUNTIME) marks an API you shouldn't use. Since Java 9 (JEP 277) it has since and forRemoval. Callers of a forRemoval = true API get a removal warning, which is on by default and louder than an ordinary deprecation warning. Pair it with the @deprecated Javadoc tag that says what to use instead.
• @SuppressWarnings (retention SOURCE) silences named warnings: "unchecked", "rawtypes", "deprecation", "removal". Put it on the smallest scope possible, ideally a single local variable declaration, with a comment saying why it's safe.
• @FunctionalInterface (retention RUNTIME) makes the compiler check the interface has exactly one abstract method. Any interface with one abstract method works as a lambda target anyway; the annotation stops a teammate from adding a second one. More in Functional interfaces in Java.
• @SafeVarargs (retention RUNTIME) promises a generic varargs method doesn't misuse its T[] array, which removes the "possible heap pollution" warning at every call site. It's only allowed where the method can't be overridden: constructors, static methods, final instance methods and, since Java 9, private instance methods.

final class Batches {
    @SafeVarargs
    static <T> List<T> of(T... items) {   // only reads the array, never stores into it
        return List.of(items);
    }
}