Java Annotations from Scratch: A Step‑by‑Step Guide

Annotations (also called “标注”) are metadata attached to program elements; they are not part of the program logic but can be read by compilers, development tools, or deployment tools to perform validation or generate additional artifacts.

Typical uses include providing information to the compiler (e.g., to detect errors or suppress warnings), allowing tools to generate code or XML files during compilation and deployment, and supplying data that can be inspected at runtime.

Annotations can be placed on packages, types, constructors, methods, fields, parameters, local variables, and other declarations. They may contain named or unnamed values and are usually written on the first line of the annotated element.

Example of a simple annotation with named elements:

@Author(
    name="王老师",
    date="2022-12-12"
) class MyClass() { }

Example of using @SuppressWarnings with an explicit element name:

@SuppressWarnings(value = "unchecked")
void myName(){}

If an annotation has only a single value, the element name can be omitted:

@SuppressWarnings("unchecked")
void myName(){}

Annotations without any elements can also omit the parentheses:

@Override
void myName(){}

Standard predefined annotations in the java.lang package include @Deprecated, @Override, and @SuppressWarnings. @Deprecated marks a program element as discouraged; the compiler issues a warning when the element is used, and Javadoc can include an @deprecated tag to document the reason.

// Javadoc comment
/**
 * @deprecated explains why it is discouraged
 */
@Deprecated
static void deprecatedMethod(){}

@Override

asserts that a method overrides a superclass method; if the method does not actually override, the compiler generates an error.

// Overriding a method from an interface
interface Closable { void close(); }
class File implements Closable {
    @Override
    public void close() { /* close file */ }
}

@SuppressWarnings

can selectively silence compiler warnings such as "unchecked" or "deprecation". When a generic collection interacts with legacy code, the compiler may emit an unchecked warning, which can be suppressed by annotating the method.

@SuppressWarnings("deprecation")
void useDeprecatedMethod(){
    objectOne.deprecatedMethod();
}

Multiple warning types can be suppressed simultaneously:

@SuppressWarnings({"unchecked", "deprecation"})

Custom annotations are defined with the @interface keyword. Elements resemble method declarations and can have default values.

@interface TaggingInfo {
    String 作者();
    String 日期();
    int 当前版本() default 1;
    String 最后修改日期() default "N/A";
    String[] 参与者();
}

Using the custom annotation:

@TaggingInfo(
    作者="王老师",
    日期="2022-12-12",
    当前版本=7,
    最后修改日期="2022-12-28",
    参与者={"王老师","张老师","李老师"}
)
public class B extends A { }

To make annotation information available at runtime, the annotation must be marked with @Retention(RetentionPolicy.RUNTIME):

import java.lang.annotation.*;
@Retention(RetentionPolicy.RUNTIME)
@interface AnnotationForRuntime { }

Annotation processors (e.g., the JDK’s apt tool) can generate auxiliary code or enforce coding patterns based on custom annotations.