Java Annotations Overview

1. What Are Annotations?

---

Annotations in Java serve as metadata markers that can be applied to classes, fields, methods, and other program elements. They provide additional information about these elements without affecting the actual code execution. Modern Java frameworks rely heavily on annotations for configuration, validation, and various runtime behaviors.

2. Defining Custom Annotations

---

In Java, annotations are created using the @interface keyword. This syntax closely resembles interface definition, with the exception of the preceding @ symbol.

public @interface MyMarker {
}

Think of this as creating a label named MyMarker that can be attached to program elements.

3. Applying Annotations

---

Once an annotation is defined, it can be applied to various program elements:

@MyMarker
public class UserService {
    // class implementation
}

The annotation acts like a tag placed on the UserService class. Without additional configuration, this marker annotation doesn't provide meaningful functionality.

4. Meta-Annotations

---

4.1 Introduction to Meta-Annotations

Meta-annotations are annotations specifically designed to annotate other annotations. They provide context and define how custom ennotations should behave.

4.2 Five Core Meta-Annotations

4.2.1 @Retention

This meta-annotation determines the lifecycle of the annotated annotation:

• SOURCE: Annotation exists only in source code and is discarded during compilation
• CLASS: Annotation is retained during compilation but not loaded into the JVM
• RUNTIME: Annotation persists at runtime and can be accessed via reflection

@Retention(RetentionPolicy.RUNTIME)
public @interface Configuration {
}

4.2.2 @Documented

When applied, this meta-annotation ensures that the annotated annotation's elements are included in the Javadoc documentation.

4.2.3 @Target

This restricts where an annotation can be applied. Valid targets include:

• ANNOTATION_TYPE - For annotating other annotations
• CONSTRUCTOR - For constructors
• FIELD - For class fields
• LOCAL_VARIABLE - For local variables
• METHOD - For methods
• PACKAGE - For packages
• PARAMETER - For method parameters
• TYPE - For classes, interfaces, and enumerations

@Target(ElementType.METHOD)
public @interface BusinessLogic {
}

4.2.4 @Inherited

This meta-annotation allows subclasses to inherit annotations from parent classes:

@Inherited
@Retention(RetentionPolicy.RUNTIME)
public @interface LegacySupport {
}

@LegacySupport
public class ParentEntity {
}

public class ChildEntity extends ParentEntity {
    // Automatically inherits @LegacySupport annotation
}

4.2.5 @Repeatable

Introduced in Java 8, this allows the same annotation to be applied multiple times:

@interface Roles {
    Role[] value();
}

@Repeatable(Roles.class)
@interface Role {
    String designation() default "";
}

@Role(designation="Developer")
@Role(designation="Architect")
@Role(designation="TeamLead")
public class Employee {
}

5. Annotation Attributes

---

5.1 Understanding Annotation Attributes

Annotation attributes are declared as abstract methods within the annotation interface. The method name becomes the attribute name, and the return type defines the attribute type. Annotations contain only attributes, not traditional methods.

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface EntityMapping {
    String tableName();
    int version();
}

When applying this annotation, attributes must be assigned values:

@EntityMapping(tableName="users", version=1)
public class User {
}

Multiple attributes are separated by commas. When an attribute named value is the only attribute, the assignment can be simplified.

5.2 Default Attribute Values

Attributes can have default values specified using the default keyword:

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface Component {
    String name() default "";
    boolean lazyLoad() default false;
}

@Component
public class DataProcessor {
    // Uses default values for all attributes
}

6. Built-in Java Annotations

---

6.1 @Deprecated

Marks elements as obsolete. The compiler generates warnings when deprecated elements are used:

public class MessagePrinter {
    @Deprecated
    public void printOld() {
        System.out.println("Deprecated method");
    }
    
    public void printNew() {
        System.out.println("Current method");
    }
}

6.2 @Override

Indicates that a method must override a parent class method or implement an interface method:

public class StringProcessor implements Processor<String> {
    
    @Override
    public String process(String input) {
        return input.toUpperCase();
    }
}

6.3 @SuppressWarnings

Suppresses compiler warnings for specific situations:

@SuppressWarnings("deprecation")
public void legacyAccess() {
    MessagePrinter printer = new MessagePrinter();
    printer.printOld(); // No warning displayed
}

6.4 @SafeVarargs

Asserts that a method does not perform unsafe operations on its varargs parameters. Added in Java 7:

@SafeVarargs
static void collectData(List<String>... dataLists) {
    Object[] container = dataLists;
    List<Integer> numbers = Arrays.asList(100);
    container[0] = numbers;
    String item = dataLists[0].get(0); // ClassCastException at runtime
}

6.5 @FunctionalInterface

Introduced in Java 8, this marks an interface as a functional interface (single abstract method):

@FunctionalInterface
public interface Action {
    void execute();
}

This annotation enables easy conversion to lambda expressions in functional programming contexts.

7. Annotation Processing Mechanism

---

Annotations are processed at runtime using Java's reflection API:

@EntityMapping(tableName="customers", version=2)
public class CustomerService {
    public static void main(String[] args) {
        boolean isAnnotated = CustomerService.class.isAnnotationPresent(EntityMapping.class);
        
        if (isAnnotated) {
            EntityMapping mapping = CustomerService.class.getAnnotation(EntityMapping.class);
            System.out.println("Table: " + mapping.tableName());
            System.out.println("Version: " + mapping.version());
        }
    }
}

8. Practical Use Cases

---

Annotation Processing Tools (APT)

While annotations provide metadata, they require external processors to take effect. Annotation Processing Tools (APT) are compilers that analyze annotations and generate additional code or perform validation during the build process.

Common use cases include:

• Dependency injection frameworks
• Code generation tools
• Validation frameworks
• Dependency management in modern frameworks

Developers utilize these annotations so that frameworks and tools can interpret them and generate appropriate implementations or configurations automatically.