Custom Annotations: @Retention, @Target, and Runtime Processing

Advanced16 min read•Updated: 2025-01-15

🏷️ Custom Annotations: @Retention, @Target, and Runtime Processing

Introduction

Annotations are metadata tags affixed to classes, methods, fields, and parameters. While annotations do not directly change compiled bytecode execution semantics, they can be discovered and processed at runtime using Reflection.

This is the exact mechanism behind @Autowired, @Test, @Entity, and @Transactional.

🏛️ The Meta-Annotations

When defining a custom annotation using @interface, Java requires meta-annotations:

1
@Retention: Defines how long the annotation is retained:

RetentionPolicy.SOURCE: Discarded by the compiler (e.g. @Override).
RetentionPolicy.CLASS: Stored in .class file but ignored by JVM at runtime.
RetentionPolicy.RUNTIME: Retained in JVM memory and readable via Reflection!

1
@Target: Restricts where the annotation can be attached:

ElementType.TYPE: Classes, interfaces, enums, records.
ElementType.METHOD: Methods.
ElementType.FIELD: Fields.
ElementType.PARAMETER: Method parameters.

🛠️ Step 1: Declaring Custom Annotations

1package com.mskinstitute.annotations;
2 
3import java.lang.annotation.*;
4 
5@Retention(RetentionPolicy.RUNTIME)
6@Target(ElementType.METHOD)
7public @interface TestCase {
8    String description() default "No description provided";
9    int timeoutMs() default 1000;
10}

🛠️ Step 2: Annotating Business Code

1public class CalculatorTestSuite {
2 
  @TestCase(description = "Verify addition logic", timeoutMs = 500)
  public void testAddition() {
      if (2 + 2 != 4) throw new AssertionError("Math broke!");
      System.out.println("  [PASS] testAddition");
  }
8 
  @TestCase(description = "Verify division by zero handling")
  public void testDivisionByZero() {
      System.out.println("  [PASS] testDivisionByZero");
  }
13 
  public void unannotatedHelperMethod() {
      // Will not be executed by test runner
  }
17}

🛠️ Step 3: Building a Runtime Annotation Processor (Mini JUnit Runner)

1public class MiniJUnitRunner {
  public static void main(String[] args) throws Exception {
      Class<?> suiteClass = CalculatorTestSuite.class;
      Object suiteInstance = suiteClass.getDeclaredConstructor().newInstance();
5 
      int passed = 0;
      int failed = 0;
8 
      for (Method method : suiteClass.getDeclaredMethods()) {
          // Check if method is tagged with @TestCase
          if (method.isAnnotationPresent(TestCase.class)) {
              TestCase testCase = method.getAnnotation(TestCase.class);
              System.out.printf("Executing: %s (Desc: '%s')%n", 
                  method.getName(), testCase.description());
15 
              try {
                  method.invoke(suiteInstance);
                  passed++;
              } catch (Exception ex) {
                  System.err.println("  [FAIL]: " + ex.getCause().getMessage());
                  failed++;
              }
          }
      }
25 
      System.out.printf("Test Results: %d Passed, %d Failed.%n", passed, failed);
  }
28}

Next Lesson

Capstone 1: Multithreaded Web Downloader & File Processor with ExecutorService

Continue learning with hands-on practice, examples, and exercises in the upcoming topic.

Related Lessons

Previous Lesson	Next Lesson
Invoking Methods and Accessing Private Fields via Reflection	Capstone 1: Multithreaded Web Downloader & File Processor with ExecutorService

Practice Quiz

Test your understanding of this lesson with 1 questions. Each question has one correct answer.

Previous Next

PreviousPrevNext

MSK Institute • Shikohabad

Loading Page Content...

Preparing courses, live labs, and learning resources.सामग्री लोड हो रही है, कृपया प्रतीक्षा करें...

Connecting serverPlease wait...

💻 Practical Labs🚀 Free Demo📜 Verified Certificates

Introduction

This is the exact mechanism behind @Autowired, @Test, @Entity, and @Transactional.

🏛️ The Meta-Annotations

When defining a custom annotation using @interface, Java requires meta-annotations:

@Retention: Defines how long the annotation is retained:

RetentionPolicy.SOURCE: Discarded by the compiler (e.g. @Override).

RetentionPolicy.CLASS: Stored in .class file but ignored by JVM at runtime.

RetentionPolicy.RUNTIME: Retained in JVM memory and readable via Reflection!

@Target: Restricts where the annotation can be attached:

ElementType.TYPE: Classes, interfaces, enums, records.

ElementType.METHOD: Methods.

ElementType.FIELD: Fields.

ElementType.PARAMETER: Method parameters.

🛠️ Step 2: Annotating Business Code

1public class CalculatorTestSuite {
2 
  @TestCase(description = "Verify addition logic", timeoutMs = 500)
  public void testAddition() {
      if (2 + 2 != 4) throw new AssertionError("Math broke!");
      System.out.println("  [PASS] testAddition");
  }
8 
  @TestCase(description = "Verify division by zero handling")
  public void testDivisionByZero() {
      System.out.println("  [PASS] testDivisionByZero");
  }
13 
  public void unannotatedHelperMethod() {
      // Will not be executed by test runner
  }
17}

🛠️ Step 3: Building a Runtime Annotation Processor (Mini JUnit Runner)

1public class MiniJUnitRunner {
  public static void main(String[] args) throws Exception {
      Class<?> suiteClass = CalculatorTestSuite.class;
      Object suiteInstance = suiteClass.getDeclaredConstructor().newInstance();
5 
      int passed = 0;
      int failed = 0;
8 
      for (Method method : suiteClass.getDeclaredMethods()) {
          // Check if method is tagged with @TestCase
          if (method.isAnnotationPresent(TestCase.class)) {
              TestCase testCase = method.getAnnotation(TestCase.class);
              System.out.printf("Executing: %s (Desc: '%s')%n", 
                  method.getName(), testCase.description());
15 
              try {
                  method.invoke(suiteInstance);
                  passed++;
              } catch (Exception ex) {
                  System.err.println("  [FAIL]: " + ex.getCause().getMessage());
                  failed++;
              }
          }
      }
25 
      System.out.printf("Test Results: %d Passed, %d Failed.%n", passed, failed);
  }
28}

Previous Lesson

Next Lesson

Invoking Methods and Accessing Private Fields via Reflection

Capstone 1: Multithreaded Web Downloader & File Processor with ExecutorService