Annotation Interface

A Java annotation interface is a specialized interface type declared using the @interface keyword, utilized to define custom annotations. At compile time, the Java compiler generates a .class file for this declaration with both the ACC_INTERFACE and ACC_ANNOTATION flags set. It remains a specialized annotation interface at the bytecode level and implicitly extends the java.lang.annotation.Annotation interface. Because of this implicit inheritance, an annotation interface cannot explicitly extend other interfaces.

Syntax and Declaration

The declaration replaces the standard interface keyword with @interface.

public @interface StandardAnnotation {
    // Element declarations
}

Annotation Elements

Data within an annotation interface is defined using method declarations, which act as the annotation’s attributes or elements. These elements are implicitly public and abstract. Unlike standard interfaces, annotation interfaces are strictly prohibited from declaring default or private methods.

Elements are subject to strict compiler rules:

1. No Parameters: The method declaration must not accept any arguments.
2. No Exceptions: The method must not have a throws clause.
3. No Type Parameters: Generic methods are not permitted.
4. No Cyclic Dependencies: An annotation interface cannot contain an element of its own type, either directly or indirectly.

public @interface ConfigMetadata {
    String author();
    int revision();
}

Permitted Return Types

The return type of an annotation element is strictly limited to the following:

• Primitive types (int, boolean, double, etc.)
• java.lang.String
• java.lang.Class (including parameterized forms like Class<?> or Class<? extends Number>)
• enum types
• Other annotation interfaces
• Single-dimensional arrays of any of the types listed above

import java.lang.annotation.ElementType;

public @interface ComplexAnnotation {
    boolean isEnabled();                  // Primitive
    String[] tags();                      // Array of String
    Class<?> targetClass();               // Class type
    ElementType targetEnum();             // Enum type
    StandardAnnotation nestedConfig();    // Nested annotation
}

Default Values

Elements can be assigned default values using the default keyword. If a default value is provided, the element becomes optional when the annotation is applied.

Crucial constraint: An annotation element can never evaluate to null. Therefore, default values cannot be null, and arrays cannot contain null elements.

public @interface Timeout {
    int duration() default 1000;
    String unit() default "MILLISECONDS";
    String[] fallbackMethods() default {}; // Empty array instead of null
}

The value Element

If an annotation interface declares an element named exactly value, and it is the only element specified when the annotation is applied (or all other elements have default values), the element name value= can be omitted during application.

public @interface SingleValueAnnotation {
    String[] value();
}

Meta-Annotations

An annotation interface is typically decorated with meta-annotations—annotations applied to other annotations—to define its behavior and scope within the JVM and compiler:

• @Target: Specifies the Java elements (e.g., TYPE, METHOD, FIELD) to which the annotation interface can be applied.
• @Retention: Dictates the lifecycle of the annotation (SOURCE, CLASS, or RUNTIME).
• @Inherited: Indicates that the annotation should be automatically inherited by subclasses of the annotated class.
• @Documented: Instructs Javadoc to include the annotation in the generated documentation.
• @Repeatable: Allows the same annotation interface to be applied multiple times to a single declaration.

import java.lang.annotation.*;

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE, ElementType.METHOD})
public @interface ScopedAnnotation {
    String value() default "singleton";
}

Master Java with Deep Grasping Methodology!

Learn More