Annotations: built-ins and defining your own

Metadata that travels with code

An annotation attaches metadata to a program element — a class, method, field, parameter, etc. It does not change what the code *does* on its own; it is read by the compiler, by build/test tools, or at runtime via reflection. The syntax is @Name, optionally with element values in parentheses.

### The four built-ins you must know

@Override — declares that a method is intended to override a supertype method. If it does *not* (wrong name, wrong parameter types), the compiler reports an error. This catches the classic bug where you *think* you overrode equals(Object) but actually wrote equals(MyType), silently *overloading* instead.

class Point {
    @Override
    public boolean equals(Object o) {   // correct signature
        // ...
        return true;
    }
}

@Deprecated — marks an element as obsolete. Callers get a compiler warning. Pair it with a Javadoc @deprecated tag explaining the replacement.

@Deprecated
public void oldStart() { /* use start() instead */ }

@SuppressWarnings — silences named compiler warnings for the annotated element. Keep its scope as small as possible (a single statement or method), and document why.

@SuppressWarnings("unchecked")
List<String> names = (List<String>) rawList;

@FunctionalInterface — declares that an interface has exactly one abstract method. The compiler errors if you add a second, protecting interfaces meant to be used as lambda/method-reference targets (like Runnable, Comparator).

@FunctionalInterface
interface Check { boolean test(int n); }

Defining a custom annotation

You declare one with @interface. Its elements look like methods (name + return type), may declare a default, and the special element named value lets callers omit the name:

import java.lang.annotation.*;

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface Test {
    String value() default "";
    int timeout() default 0;
}

Applying it:

@Test                       // both elements use their defaults
void case1() { }

@Test("login flow")          // "login flow" binds to value (name omitted)
void case2() { }

@Test(value = "timeout case", timeout = 500)  // multiple elements: name each
void case3() { }

Legal element types are restricted: primitives, String, Class, an enum, another annotation, or a one-dimensional array of those.

Meta-annotations: annotations *on* annotations

Two are essential when you write your own:

- @Retention — how long the annotation is kept. SOURCE (discarded by the compiler — e.g. @Override), CLASS (kept in the .class file but not loaded at runtime — the default), or RUNTIME (loaded and visible to reflection). You must use RUNTIME if a tool will read it via reflection. - @Target — which program elements the annotation may be applied to: ElementType.TYPE, METHOD, FIELD, PARAMETER, CONSTRUCTOR, LOCAL_VARIABLE, etc. Applying it elsewhere is a compile error.

@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE, ElementType.METHOD})
@interface Audited { }

Reading annotations at runtime

Because the AU course pairs annotations with *testing*, the payoff is reading them reflectively. A RUNTIME-retained annotation is reachable through the reflection API (covered in Module 7):

for (Method m : MyTests.class.getDeclaredMethods()) {
    if (m.isAnnotationPresent(Test.class)) {
        Test t = m.getAnnotation(Test.class);
        System.out.println("running " + m.getName() + ": " + t.value());
        m.invoke(new MyTests());
    }
}

This is exactly how JUnit discovers @Test methods — annotation + reflection, no naming convention required.