Mastering Java Annotations: Definitions, Uses, and Custom Creation

Java annotations are an important concept used to describe code, allowing annotation of packages, classes, interfaces, fields, method parameters, and local variables. Mastering Java annotations helps in understanding the underlying implementation of frameworks. @mikechen

Java Annotation Definition

Java annotations, also called Java markers, were introduced in JDK 5 as a form of metadata.

They provide a safe, comment‑like mechanism to associate any information or metadata with program elements such as classes, methods, and member variables.

Java annotations are additional metadata attached to code, used by tools during compilation or runtime for explanation and configuration purposes.

Java Annotation Applications

1. Generating documentation – the earliest and most common use of annotations.

2. Compile‑time checks – e.g., @Override placed before a method triggers a warning if the method does not actually override a superclass method.

3. Reducing configuration – annotation‑based configuration (e.g., Spring since 2.5) replaces XML files.

4. Runtime reflection – annotations can be inspected via the Class, Method, Field APIs.

Java Annotation Categories

1. Standard Built‑in Annotations

Includes @Override, @Deprecated, @SuppressWarnings, etc.; using these causes the compiler to perform checks.

2. Meta‑Annotations

Meta‑annotations define other annotations and include @Retention, @Target, @Inherited, @Documented, @Repeatable.

@Override Example

class Parent {
    public void test() {}
}

class Child extends Parent {
    /**
     * Uncomment the following code to see a compile‑time warning.
     */
    // @Override
    // public void test() {}
}

@Deprecated Example

@Deprecated
class TestClass {
    // do something
}

@SuppressWarnings Examples

Suppress specific warnings:

@SuppressWarnings("unchecked")
public void addItems(String item) {
    @SuppressWarnings("rawtypes")
    List items = new ArrayList();
    items.add(item);
}

Suppress multiple warnings:

@SuppressWarnings(value={"unchecked", "rawtypes"})
public void addItems(String item) {
    List items = new ArrayList();
    items.add(item);
}

Suppress all warnings:

@SuppressWarnings("all")
public void addItems(String item) {
    List items = new ArrayList();
    items.add(item);
}

Common @SuppressWarnings parameter values:

@FunctionalInterface

@FunctionalInterface indicates that the annotated interface is a functional interface, introduced in JDK 8.

@FunctionalInterface
public interface UserService {
    void getUser(Long userId);
    default void setUser() {}
    static void saveUser() {}
    boolean equals(Object obj);
}

A functional interface has exactly one abstract method but may contain multiple non‑abstract methods.

Java Meta‑Annotations

@Retention defines how long the annotation is retained: SOURCE, CLASS, or RUNTIME.

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)
public @interface Retention {
    RetentionPolicy value();
}

public enum RetentionPolicy {
    SOURCE, // discarded by compiler
    CLASS,  // stored in class file, not available at runtime
    RUNTIME // retained at runtime for reflection
}

@Target specifies where an annotation can be applied (e.g., METHOD, FIELD, TYPE, etc.).

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.SOURCE)
public @interface Override {}

@Documented
@Retention(RetentionPolicy.RUNTIME)
public @interface Deprecated {}

@Target({TYPE, FIELD, METHOD, PARAMETER, CONSTRUCTOR, LOCAL_VARIABLE})
@Retention(RetentionPolicy.SOURCE)
public @interface SuppressWarnings {
    String[] value();
}

@Documented indicates that the annotation should be included in Javadoc.

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface Column {
    String name() default "fieldName";
    String setFuncName() default "setField";
    String getFuncName() default "getField";
    boolean defaultDBValue() default false;
}

@Inherited allows subclasses to inherit the annotation from a superclass.

@Inherited
public @interface Greeting {
    enum FontColor { BLUE, RED, GREEN }
    String name();
    FontColor fontColor() default FontColor.GREEN;
}

@Repeatable enables an annotation to be applied multiple times.

@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface Schedules {
    Scheduled[] value();
}

@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Repeatable(Schedules.class)
public @interface Scheduled {
    // ...
}