Java Annotations Explained — How They Work, Why They Exist, and When to Write Your Own

import java.lang.annotation.*;
import java.lang.reflect.Method;

// Step 1: Declare a custom annotation using @interface
// @Retention tells Java HOW LONG to keep this annotation around
// RetentionPolicy.RUNTIME means it survives compilation and is readable at runtime
@Retention(RetentionPolicy.RUNTIME)
// @Target restricts WHERE this annotation can be placed
// ElementType.METHOD means only on methods, not classes or fields
@Target(ElementType.METHOD)
public @interface AnnotationBasics {

    // This is the annotation declaration — we'll use it below
    @Retention(RetentionPolicy.RUNTIME)
    @Target(ElementType.METHOD)
    @interface LogExecutionTime {
        // Annotation elements look like method declarations
        // Default values make elements optional
        String label() default "unnamed-operation";
        boolean enabled() default true;
    }

    // A simple service class whose methods we want to annotate
    class ReportService {

        // Annotating this method with our custom annotation
        // We're providing a value for 'label'; 'enabled' uses its default
        @LogExecutionTime(label = "generate-monthly-report")
        public void generateMonthlyReport() throws InterruptedException {
            System.out.println("Generating report...");
            Thread.sleep(100); // Simulate work taking time
        }

        // This method is annotated but disabled — the processor should skip it
        @LogExecutionTime(label = "send-email", enabled = false)
        public void sendEmailNotification() {
            System.out.println("Sending email...");
        }

        // This method has NO annotation — processor ignores it entirely
        public void helperMethod() {
            System.out.println("Helper running...");
        }
    }

    // Simulated annotation processor using reflection
    // In real frameworks like Spring AOP, this is done automatically
    static void runWithAnnotationProcessing(ReportService service) throws Exception {
        // Get all declared methods on the class
        Method[] methods = ReportService.class.getDeclaredMethods();

        for (Method method : methods) {
            // Check if THIS method carries our annotation
            if (method.isAnnotationPresent(LogExecutionTime.class)) {
                LogExecutionTime annotation = method.getAnnotation(LogExecutionTime.class);

                // Read the 'enabled' element from the annotation
                if (!annotation.enabled()) {
                    System.out.println("[SKIPPED] " + annotation.label() + " is disabled");
                    continue; // Skip this method entirely
                }

                // Start timing BEFORE the method runs
                long startTime = System.currentTimeMillis();
                method.invoke(service); // Actually call the method via reflection
                long elapsed = System.currentTimeMillis() - startTime;

                // Log the result using the label from the annotation
                System.out.println("[TIMED] '" + annotation.label() + "' took " + elapsed + "ms");
            } else {
                // No annotation present — run it normally without timing
                method.invoke(service);
            }
        }
    }

    static void main(String[] args) throws Exception {
        ReportService service = new ReportService();
        runWithAnnotationProcessing(service);
    }
}

import java.lang.annotation.*;

public class MetaAnnotationShowcase {

    // ── EXAMPLE 1: @Repeatable ──────────────────────────────────────────────
    // To make an annotation repeatable, you need a 'container' annotation
    // The container holds an array of the repeatable annotation
    @Retention(RetentionPolicy.RUNTIME)
    @Target(ElementType.METHOD)
    @interface SecurityRoles {              // This is the CONTAINER annotation
        RequiresRole[] value();            // Must have a value() returning an array
    }

    @Retention(RetentionPolicy.RUNTIME)
    @Target(ElementType.METHOD)
    @Repeatable(SecurityRoles.class)       // Links to its container
    @interface RequiresRole {
        String value();
    }

    // ── EXAMPLE 2: @Inherited ───────────────────────────────────────────────
    @Retention(RetentionPolicy.RUNTIME)
    @Target(ElementType.TYPE)             // TYPE means class/interface/enum
    @Inherited                             // Subclasses will inherit this annotation
    @interface ServiceLayer {
        String team() default "platform";
    }

    // ── Demo classes using these annotations ────────────────────────────────

    @ServiceLayer(team = "payments")       // Placed on parent class
    static class PaymentService {

        // Using @RequiresRole TWICE on the same method — only possible with @Repeatable
        @RequiresRole("ADMIN")
        @RequiresRole("FINANCE_MANAGER")
        public void approveRefund() {
            System.out.println("Refund approved.");
        }
    }

    // Subclass does NOT redeclare @ServiceLayer — it inherits it via @Inherited
    static class InternationalPaymentService extends PaymentService {
        public void processForexTransaction() {
            System.out.println("Forex transaction processed.");
        }
    }

    public static void main(String[] args) throws Exception {
        // ── Check @Inherited behavior ────────────────────────────────────────
        // Even though InternationalPaymentService never declared @ServiceLayer,
        // it inherits it from PaymentService because of @Inherited
        boolean hasServiceLayer = InternationalPaymentService.class
                .isAnnotationPresent(ServiceLayer.class);
        ServiceLayer serviceAnnotation = InternationalPaymentService.class
                .getAnnotation(ServiceLayer.class);

        System.out.println("InternationalPaymentService has @ServiceLayer: " + hasServiceLayer);
        System.out.println("Inherited team value: " + serviceAnnotation.team());

        // ── Check @Repeatable behavior ───────────────────────────────────────
        var approveMethod = PaymentService.class.getMethod("approveRefund");

        // getAnnotationsByType handles the unwrapping of the container automatically
        RequiresRole[] roles = approveMethod.getAnnotationsByType(RequiresRole.class);
        System.out.println("\napproveRefund requires " + roles.length + " role(s):");
        for (RequiresRole role : roles) {
            System.out.println("  -> " + role.value());
        }
    }
}

import java.lang.annotation.*;

public class RetentionPolicyDemo {

    // SOURCE: Compiler reads this, then throws it away.
    // Useful for IDE hints, compile-time checks, Lombok-style processors.
    @Retention(RetentionPolicy.SOURCE)
    @Target(ElementType.METHOD)
    @interface TodoReminder {
        String ticket();  // e.g. "JIRA-1234"
    }

    // CLASS: Stored in .class file, but stripped on JVM load.
    // Default if you forget @Retention — this is the trap.
    @Retention(RetentionPolicy.CLASS)
    @Target(ElementType.METHOD)
    @interface InternalOnly {
        // Bytecode tools like ASM can read this, but runtime reflection can't
    }

    // RUNTIME: Survives into the running JVM. Readable via reflection.
    // This is what Spring, Hibernate, JUnit etc. use.
    @Retention(RetentionPolicy.RUNTIME)
    @Target(ElementType.METHOD)
    @interface Auditable {
        String action();
    }

    static class UserService {

        @TodoReminder(ticket = "JIRA-999")    // SOURCE — erased after compilation
        @InternalOnly                          // CLASS  — in .class file, not in JVM memory
        @Auditable(action = "DELETE_USER")    // RUNTIME — fully visible at runtime
        public void deleteUser(String userId) {
            System.out.println("Deleting user: " + userId);
        }
    }

    public static void main(String[] args) throws Exception {
        var deleteMethod = UserService.class.getMethod("deleteUser", String.class);

        // Check which annotations are actually visible at runtime via reflection
        System.out.println("--- Runtime Reflection Results ---");

        // @TodoReminder: SOURCE — completely gone, annotation class doesn't even exist at runtime
        // (We can't even reference it here without a compile trick, so we show the count)
        Annotation[] allVisible = deleteMethod.getAnnotations();
        System.out.println("Total annotations visible at runtime: " + allVisible.length);
        // Only 1 annotation survives — @Auditable with RUNTIME retention

        // @InternalOnly: CLASS — NOT visible. isAnnotationPresent returns false.
        boolean internalVisible = deleteMethod.isAnnotationPresent(InternalOnly.class);
        System.out.println("@InternalOnly visible at runtime: " + internalVisible);

        // @Auditable: RUNTIME — fully visible. We can read its elements.
        boolean auditableVisible = deleteMethod.isAnnotationPresent(Auditable.class);
        System.out.println("@Auditable visible at runtime: " + auditableVisible);

        if (auditableVisible) {
            Auditable auditInfo = deleteMethod.getAnnotation(Auditable.class);
            System.out.println("Audit action recorded: '" + auditInfo.action() + "'");
        }

        // Simulate an audit processor acting on the annotation
        UserService service = new UserService();
        System.out.println("\n--- Processing deleteUser Call ---");
        if (auditableVisible) {
            Auditable audit = deleteMethod.getAnnotation(Auditable.class);
            System.out.println("[AUDIT LOG] Action '" + audit.action() + "' initiated");
        }
        deleteMethod.invoke(service, "user-42");
        System.out.println("[AUDIT LOG] Action completed successfully");
    }
}

import java.lang.annotation.*;
import java.lang.reflect.Field;
import java.util.ArrayList;
import java.util.List;

public class CustomValidationFramework {

    // ── Annotation 1: Validate that a number is within a range ───────────────
    @Retention(RetentionPolicy.RUNTIME)      // Must be RUNTIME so we can read it via reflection
    @Target(ElementType.FIELD)               // Only valid on fields, not methods or classes
    @interface ValidRange {
        int min() default 0;
        int max() default Integer.MAX_VALUE;
        String message() default "Value is out of the allowed range";  // Custom error message
    }

    // ── Annotation 2: Mark a String field as required (non-null, non-empty) ──
    @Retention(RetentionPolicy.RUNTIME)
    @Target(ElementType.FIELD)
    @interface Required {
        String message() default "Field is required and cannot be blank";
    }

    // ── A real domain object using our annotations ───────────────────────────
    static class ProductListing {

        @Required(message = "Product name must be provided")
        private String productName;

        @ValidRange(min = 1, max = 10000, message = "Price must be between $1 and $10,000")
        private int priceInCents;

        @ValidRange(min = 0, max = 500, message = "Stock cannot exceed warehouse capacity of 500")
        private int stockQuantity;

        // A field with NO annotation — the validator should leave it alone
        private String internalSku;

        public ProductListing(String productName, int priceInCents, int stockQuantity, String internalSku) {
            this.productName = productName;
            this.priceInCents = priceInCents;
            this.stockQuantity = stockQuantity;
            this.internalSku = internalSku;
        }
    }

    // ── The Validator Engine ─────────────────────────────────────────────────
    static class ObjectValidator {

        // Returns a list of validation failure messages.
        // An empty list means the object is valid.
        public static List<String> validate(Object target) throws IllegalAccessException {
            List<String> violations = new ArrayList<>();
            Class<?> clazz = target.getClass();

            // Walk through every declared field in the class
            for (Field field : clazz.getDeclaredFields()) {
                field.setAccessible(true);  // Allow reading private fields
                Object fieldValue = field.get(target);

                // ── Check @Required ──────────────────────────────────────────
                if (field.isAnnotationPresent(Required.class)) {
                    Required requiredAnnotation = field.getAnnotation(Required.class);
                    // A field fails @Required if it's null OR an empty/blank string
                    if (fieldValue == null || (fieldValue instanceof String str && str.isBlank())) {
                        violations.add("[" + field.getName() + "] " + requiredAnnotation.message());
                    }
                }

                // ── Check @ValidRange ────────────────────────────────────────
                if (field.isAnnotationPresent(ValidRange.class)) {
                    ValidRange rangeAnnotation = field.getAnnotation(ValidRange.class);
                    // Only validate numeric types — skip gracefully for others
                    if (fieldValue instanceof Integer intValue) {
                        if (intValue < rangeAnnotation.min() || intValue > rangeAnnotation.max()) {
                            // Include the actual value in the error so developers know what was rejected
                            violations.add("[" + field.getName() + "] " + rangeAnnotation.message()
                                    + " (actual: " + intValue + ")");
                        }
                    }
                }
            }
            return violations;
        }
    }

    public static void main(String[] args) throws Exception {
        System.out.println("=== Test 1: Valid product listing ===");
        ProductListing validProduct = new ProductListing("Wireless Keyboard", 4999, 50, "SKU-001");
        List<String> violations = ObjectValidator.validate(validProduct);
        if (violations.isEmpty()) {
            System.out.println("Product is valid. Ready to publish.");
        }

        System.out.println("\n=== Test 2: Invalid product listing ===");
        // Blank name, price too low (0), stock way over limit
        ProductListing invalidProduct = new ProductListing("", 0, 750, "SKU-002");
        List<String> errors = ObjectValidator.validate(invalidProduct);
        if (!errors.isEmpty()) {
            System.out.println("Validation failed with " + errors.size() + " error(s):");
            errors.forEach(error -> System.out.println("  ✗ " + error));
        }
    }
}