Java Annotations and Reflection: Complete Guide for Backend Engineers

1. Annotation Fundamentals: @interface, ElementType and RetentionPolicy

Annotations are a form of syntactic metadata added to Java source code. They do not change program semantics by themselves — they are markers that tools, frameworks, and the runtime can inspect to drive behavior. Declared with the @interface keyword, annotation types look like interfaces but carry special meaning to the compiler and the JVM.

@interface Syntax

An annotation type is declared with @interface. Elements (analogous to methods in a regular interface) define the attributes an annotation can carry. Every element can have a default value, making it optional at the use site.

// Minimal annotation type
public @interface Validated {
}

// Annotation with elements
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE, ElementType.METHOD})
public @interface Validated {
    String[] groups() default {};
    Class<?> payload() default Void.class;
    String message() default "Validation failed";
}

ElementType Values

The @Target meta-annotation restricts where an annotation can be applied. The full set of ElementType values as of Java 17+ is:

• TYPE — class, interface, enum, record, annotation type
• FIELD — instance variable or enum constant
• METHOD — method declaration
• PARAMETER — formal parameter of a method or constructor
• CONSTRUCTOR — constructor declaration
• LOCAL_VARIABLE — local variable (SOURCE retention only; not available at runtime)
• ANNOTATION_TYPE — annotation type declaration (meta-annotations)
• PACKAGE — package declaration in package-info.java
• TYPE_PARAMETER — type parameter of a generic class/method
• TYPE_USE — any use of a type (most powerful; used for nullability annotations)
• MODULE — module declaration in module-info.java
• RECORD_COMPONENT — component of a record class (Java 16+)

RetentionPolicy

The @Retention meta-annotation controls the annotation lifecycle:

• RetentionPolicy.SOURCE — discarded by javac before generating bytecode. Used purely for documentation or compile-time checks (e.g., @Override, @SuppressWarnings). Not in .class files.
• RetentionPolicy.CLASS — present in .class files but not loaded into the JVM at runtime. This is the default when @Retention is omitted. Useful for bytecode-manipulation tools (ASM, Byte Buddy) that read raw bytecode.
• RetentionPolicy.RUNTIME — present in bytecode AND loaded into the JVM. Accessible via the Reflection API (getAnnotation(), getAnnotations()). Required for runtime frameworks like Spring, Hibernate, JUnit.

import java.lang.annotation.*;

@Documented                          // include in Javadoc
@Inherited                           // subclasses inherit this annotation
@Retention(RetentionPolicy.RUNTIME)  // visible to reflection
@Target({ElementType.TYPE, ElementType.METHOD})
public @interface Validated {
    String[] groups() default {};
    String message() default "Validation failed";
}

Meta-annotations

Meta-annotations annotate other annotation types:

• @Retention — lifecycle policy (see above)
• @Target — where it can be applied
• @Documented — include the annotation in generated Javadoc
• @Inherited — if the annotated class is subclassed, the subclass inherits the annotation (TYPE target only)
• @Repeatable — allows the annotation to be applied more than once to the same element (requires a container annotation)

Valid Element Types

Annotation elements must be one of the following types: byte, short, int, long, float, double, boolean, char, String, Class<?>, an enum, another annotation type, or a one-dimensional array of any of the above. Boxed types are not allowed.

2. Built-in Annotations: @Override, @SuppressWarnings, @FunctionalInterface

The Java standard library ships with a handful of annotations that every Java developer encounters daily. Understanding their retention and semantics avoids common pitfalls.

@Override

RetentionPolicy.SOURCE. Tells the compiler that the annotated method is intended to override or implement a method from a supertype. If no such method exists, a compile error is raised — catching typos like equal vs equals. Always use @Override — it is zero-cost at runtime and prevents silent bugs.

public class MyService extends BaseService {
    @Override
    public void process() { // compiler error if BaseService has no process()
        super.process();
        // ...
    }
}

@Deprecated

RetentionPolicy.RUNTIME. Marks an API element as deprecated. Since Java 9, the @Deprecated annotation gained since and forRemoval attributes. Always document the replacement in Javadoc using @deprecated (lowercase).

/**
 * Use {@link #connectWithPool()} instead.
 * @deprecated since 2.0, will be removed in 3.0
 */
@Deprecated(since = "2.0", forRemoval = true)
public void connect() {
    // legacy implementation
}

@SuppressWarnings

RetentionPolicy.SOURCE. Silences specific compiler warnings. Common values: "unchecked", "rawtypes", "deprecation", "serial". Always apply at the narrowest possible scope — a single variable or statement rather than the whole class — so you don't mask unrelated warnings.

public <T> List<T> unsafeList(Object raw) {
    @SuppressWarnings("unchecked")
    List<T> list = (List<T>) raw; // narrow scope — only this cast
    return list;
}

@FunctionalInterface

RetentionPolicy.RUNTIME. Documents intent: the annotated interface has exactly one abstract method and is therefore a valid lambda target. The compiler enforces the single-abstract-method constraint, preventing accidental additions that would break callers.

@FunctionalInterface
public interface EventHandler<T> {
    void handle(T event);
    // Adding a second abstract method here causes a compile error
    default String describe() { return "EventHandler"; }
}

@SafeVarargs

RetentionPolicy.RUNTIME. Applied to a final, static, or private method (or constructor) with a generic varargs parameter. It promises callers that the method body does not cause heap pollution by performing unsafe operations on the varargs array. Suppresses the unchecked warning at call sites.

@Serial (Java 14+)

Marks serialization-related members like serialVersionUID, readObject(), writeObject(). The compiler verifies that the annotated member is appropriate for serialization, catching mistakes such as wrong signatures.

public class Order implements Serializable {
    @Serial
    private static final long serialVersionUID = 1L;

    @Serial
    private void readObject(ObjectInputStream in) throws IOException, ClassNotFoundException {
        in.defaultReadObject();
    }
}

3. Creating Custom Annotations: Design Patterns

Custom annotations fall into three broad patterns: marker annotations (no elements), single-value annotations, and multi-element annotations. The right choice depends on how much configuration the annotation needs to carry.

Pattern 1 — Database Column Mapping

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.FIELD)
public @interface DatabaseColumn {
    String name();
    boolean nullable() default true;
    int length() default 255;
}

Pattern 2 — Bean Validation

@Documented
@Constraint(validatedBy = PhoneNumberValidator.class)
@Target({ElementType.FIELD, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
public @interface PhoneNumber {
    String message() default "Invalid phone number format";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
    String region() default "US";
}

public class PhoneNumberValidator implements ConstraintValidator<PhoneNumber, String> {
    private String region;

    @Override
    public void initialize(PhoneNumber annotation) {
        this.region = annotation.region();
    }

    @Override
    public boolean isValid(String value, ConstraintValidatorContext context) {
        if (value == null) return true;
        return value.matches("\\+?[1-9]\\d{7,14}");
    }
}

Pattern 3 — @RateLimit with AOP Interceptor

This is the most common production pattern: declare a RUNTIME annotation, read it in an AOP aspect, and execute cross-cutting logic without polluting business code.

// Annotation declaration
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface RateLimit {
    int requestsPerSecond() default 100;
    String key() default "";         // SpEL expression for dynamic key
    String message() default "Rate limit exceeded";
}

// AOP Aspect that reads it
@Aspect
@Component
public class RateLimitAspect {

    private final Map<String, RateLimiter> limiters = new ConcurrentHashMap<>();

    @Around("@annotation(rateLimit)")
    public Object limit(ProceedingJoinPoint pjp, RateLimit rateLimit) throws Throwable {
        String key = resolveKey(pjp, rateLimit.key());
        RateLimiter limiter = limiters.computeIfAbsent(
            key,
            k -> RateLimiter.create(rateLimit.requestsPerSecond())
        );
        if (!limiter.tryAcquire()) {
            throw new RateLimitExceededException(rateLimit.message());
        }
        return pjp.proceed();
    }

    private String resolveKey(ProceedingJoinPoint pjp, String keyExpr) {
        if (keyExpr.isEmpty()) return pjp.getSignature().toShortString();
        // SpEL evaluation omitted for brevity
        return keyExpr;
    }
}

// Usage
@RestController
public class ProductController {

    @GetMapping("/products")
    @RateLimit(requestsPerSecond = 50, key = "'products'")
    public List<Product> list() {
        return productService.findAll();
    }
}

Best Practices for Custom Annotations

• Provide default values for all optional elements to minimise boilerplate at use sites.
• Document exactly what the annotation does and who processes it (tool, framework, APT).
• Prefer composition over mega-annotations: a small focused annotation is easier to reason about than one with 15 elements.
• Use @Documented so that the annotation appears in Javadoc for public APIs.
• Choose the most restrictive @Target to prevent misuse.
• Choose the correct retention: RUNTIME only when frameworks need it at runtime; SOURCE for compile-time checks.

4. Annotation Processors (APT): Compile-Time Code Generation

Annotation Processing Tool (APT) is the mechanism that allows javac to invoke user-defined processors during compilation. Processors can generate new source files, validate code, or produce resources — all without touching the original source. Major libraries that rely on APT include Lombok, MapStruct, Dagger, and Google AutoValue.

How the Process Works

1. javac parses source files and discovers annotation processors from the classpath (via META-INF/services/javax.annotation.processing.Processor).
2. Each processor declares which annotations it handles via @SupportedAnnotationTypes.
3. javac invokes each processor's process() method with the annotated elements found in that compilation round.
4. If the processor generates new source files, javac starts a new round, processing the newly generated files.
5. Processing continues until no new source files are generated.

Writing a Simple @ToString Processor

// Marker annotation (SOURCE retention — only needed at compile time)
@Retention(RetentionPolicy.SOURCE)
@Target(ElementType.TYPE)
public @interface GenerateToString {}

// The processor
@SupportedAnnotationTypes("com.example.GenerateToString")
@SupportedSourceVersion(SourceVersion.RELEASE_21)
public class ToStringProcessor extends AbstractProcessor {

    @Override
    public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment env) {
        for (Element element : env.getElementsAnnotatedWith(GenerateToString.class)) {
            if (element.getKind() != ElementKind.CLASS) continue;
            TypeElement typeElement = (TypeElement) element;
            generateToString(typeElement);
        }
        return true; // claim the annotation
    }

    private void generateToString(TypeElement type) {
        String className = type.getSimpleName() + "ToString";
        String packageName = processingEnv.getElementUtils()
                .getPackageOf(type).getQualifiedName().toString();

        List<String> fields = type.getEnclosedElements().stream()
            .filter(e -> e.getKind() == ElementKind.FIELD)
            .map(e -> e.getSimpleName().toString())
            .toList();

        String body = fields.stream()
            .map(f -> "\"" + f + "=\" + obj." + f)
            .collect(Collectors.joining(" + \", \" + "));

        try {
            JavaFileObject file = processingEnv.getFiler()
                .createSourceFile(packageName + "." + className);
            try (PrintWriter pw = new PrintWriter(file.openWriter())) {
                pw.println("package " + packageName + ";");
                pw.println("public class " + className + " {");
                pw.println("  public static String toString(" + type.getQualifiedName() + " obj) {");
                pw.println("    return \"" + type.getSimpleName() + "{\" + " + body + " + \"}\";");
                pw.println("  }");
                pw.println("}");
            }
        } catch (IOException e) {
            processingEnv.getMessager().printMessage(Diagnostic.Kind.ERROR, e.getMessage(), type);
        }
    }
}

Key Limitation: APT Cannot Modify Existing Sources

The standard APT API (javax.annotation.processing) only allows generating new files. It cannot modify existing ones. Lombok works around this limitation by accessing internal compiler APIs (com.sun.tools.javac.tree) to directly mutate the Abstract Syntax Tree — a fragile but powerful technique that requires --add-opens in newer JDKs.

Notable APT-Based Frameworks

• Lombok — @Getter, @Builder, @Data: eliminates boilerplate by AST mutation
• MapStruct — @Mapper: generates type-safe mapper implementations at compile time
• Dagger 2 — @Component: generates DI wiring code, zero-reflection injection
• Google AutoValue — generates immutable value classes
• Micronaut — replaces Spring's runtime reflection with compile-time APT-generated metadata

5. Reflection API: Inspecting Classes, Methods and Fields at Runtime

The Java Reflection API (in java.lang.reflect) allows a program to examine or modify its own structure at runtime: discover classes, instantiate objects, invoke methods, read and write fields — all without knowing the types at compile time.

Obtaining a Class Object

// Three ways to get a Class object
Class<?> c1 = String.class;                         // compile-time literal
Class<?> c2 = "hello".getClass();                   // from an instance
Class<?> c3 = Class.forName("java.util.ArrayList"); // dynamic, by name

getDeclaredMethods() vs getMethods()

• getDeclaredMethods() — returns all methods declared directly in the class (private, protected, public, package-private) but excludes inherited methods.
• getMethods() — returns all public methods of the class, including those inherited from superclasses and implemented interfaces.

Accessing Private Fields with setAccessible

Field field = MyClass.class.getDeclaredField("privateValue");
field.setAccessible(true);   // bypasses Java access control
Object value = field.get(myInstance);
field.set(myInstance, newValue);

Method Invocation and Constructor Instantiation

// Invoke a method reflectively
Method method = MyService.class.getDeclaredMethod("process", String.class);
method.setAccessible(true);
Object result = method.invoke(serviceInstance, "payload");

// Instantiate via constructor
Constructor<MyService> ctor = MyService.class.getDeclaredConstructor(String.class);
ctor.setAccessible(true);
MyService instance = ctor.newInstance("arg");

Reading Annotations at Runtime

// getAnnotations() includes inherited; getDeclaredAnnotations() does not
Annotation[] all = MyClass.class.getAnnotations();
Transactional tx = method.getAnnotation(Transactional.class);
if (tx != null) {
    System.out.println("Timeout: " + tx.timeout());
}

Practical Example: Minimal DI Container

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.FIELD)
public @interface Inject {}

public class SimpleContainer {
    private final Map<Class<?>, Object> registry = new HashMap<>();

    public void register(Class<?> type, Object instance) {
        registry.put(type, instance);
    }

    public <T> T get(Class<T> type) throws Exception {
        T instance = type.getDeclaredConstructor().newInstance();
        for (Field field : type.getDeclaredFields()) {
            if (field.isAnnotationPresent(Inject.class)) {
                Object dep = registry.get(field.getType());
                if (dep == null) throw new RuntimeException("No bean for " + field.getType());
                field.setAccessible(true);
                field.set(instance, dep);
            }
        }
        return instance;
    }
}

// Usage
SimpleContainer container = new SimpleContainer();
container.register(UserRepository.class, new UserRepositoryImpl());
UserService service = container.get(UserService.class); // @Inject fields populated

6. Reflection Performance: The Cost and How to Mitigate It

Reflection is not free. Every call to getDeclaredMethod() performs security checks, access checks, and name lookups. Even Method.invoke() has overhead compared to a direct method call. In a hot path — e.g., processing every incoming HTTP request — reflection can add measurable latency.

Why Reflection is Slow

• Method/field lookup involves security manager checks (Java <17) and module access checks (Java 9+).
• Arguments must be boxed/unboxed (primitives become Object[]).
• The JIT compiler cannot inline reflective calls as aggressively as direct calls.
• First invocation inflates the method accessor with JNI overhead; after ~15 invocations the JDK switches to bytecode-generated accessors (the "inflation" mechanism).

Key Mitigation: Cache Method and Field Objects

// BAD — lookup on every call
public void invokeEveryTime(Object target) throws Exception {
    Method m = target.getClass().getDeclaredMethod("compute");
    m.invoke(target);
}

// GOOD — cache once, reuse
private static final Method COMPUTE;
static {
    try {
        COMPUTE = MyService.class.getDeclaredMethod("compute");
        COMPUTE.setAccessible(true);
    } catch (NoSuchMethodException e) {
        throw new ExceptionInInitializerError(e);
    }
}

public void invokeWithCache(MyService target) throws Exception {
    COMPUTE.invoke(target); // only the invoke overhead, no lookup
}

MethodHandles — Faster Alternative (Java 9+)

import java.lang.invoke.*;

MethodHandles.Lookup lookup = MethodHandles.privateLookupIn(MyService.class, MethodHandles.lookup());
MethodType type = MethodType.methodType(String.class); // return type, param types
MethodHandle handle = lookup.findVirtual(MyService.class, "getName", type);

// Invoke (no boxing for typed invokeExact)
String name = (String) handle.invokeExact(myServiceInstance);

MethodHandles are roughly 5× faster than Method.invoke for repeated calls because the JIT can treat them closer to direct dispatch. They also avoid the argument array boxing overhead when using invokeExact.

LambdaMetafactory — Maximum Performance

// Generate a synthetic lambda targeting a specific method
MethodHandles.Lookup lookup = MethodHandles.privateLookupIn(MyService.class, MethodHandles.lookup());
MethodHandle target = lookup.findVirtual(MyService.class, "getName",
    MethodType.methodType(String.class));

CallSite site = LambdaMetafactory.metafactory(
    lookup,
    "apply",
    MethodType.methodType(Function.class),
    MethodType.methodType(Object.class, Object.class), // erased signature
    target,
    MethodType.methodType(String.class, MyService.class) // specialised signature
);

@SuppressWarnings("unchecked")
Function<MyService, String> getter = (Function<MyService, String>) site.getTarget().invokeExact();
// Now getter.apply(instance) is as fast as a direct call — used by Hibernate field accessors

Performance Comparison Table

7. How Spring Uses Annotations Internally: Proxies vs Reflection

Spring is the most annotation-heavy framework in the Java ecosystem. Understanding exactly how it processes those annotations is essential for writing efficient applications and diagnosing subtle bugs.

@Component Scanning — ASM, Not Reflection

When Spring scans the classpath for @Component-annotated classes, it uses ClassPathScanningCandidateComponentProvider, which reads .class files using the ASM bytecode library — without loading the classes into the JVM. This is far cheaper than reflection because class loading triggers static initializers, allocates class objects, and requires the full classpath to be resolved.

// Conceptual view of Spring's component scan (simplified)
// Spring reads the .class file as a byte stream and uses ASM to
// extract annotation metadata without calling Class.forName()
SimpleMetadataReaderFactory factory = new SimpleMetadataReaderFactory();
MetadataReader reader = factory.getMetadataReader("com/example/UserService.class");
AnnotationMetadata metadata = reader.getAnnotationMetadata();
boolean isComponent = metadata.hasAnnotation("org.springframework.stereotype.Component");

Bean Creation — Reflection Instantiation

Once Spring has determined which classes are beans, it instantiates them via Constructor.newInstance() (or factory methods). Constructor and field injection uses setAccessible(true) to inject private fields. This is the one-time startup cost — not repeated per request.

@Transactional — CGLIB Proxy, Not Reflection

For AOP-based annotations like @Transactional and @Cacheable, Spring does not use Method.invoke at runtime. Instead, Spring's ProxyFactory uses CGLIB to generate a dynamic subclass proxy. Method interception in the proxy is a direct virtual method call to the generated subclass — JIT-inlinable and fast, with no reflection overhead per invocation.

// What Spring generates at startup (conceptual CGLIB subclass):
public class UserService$$SpringCGLIB$$0 extends UserService {
    @Override
    public void createUser(User user) {
        // TransactionInterceptor logic: begin tx, invoke super, commit/rollback
        TransactionStatus tx = txManager.getTransaction(txDef);
        try {
            super.createUser(user); // direct call — NOT reflection
            txManager.commit(tx);
        } catch (RuntimeException e) {
            txManager.rollback(tx);
            throw e;
        }
    }
}

@Value and @Autowired — AnnotationUtils Hierarchy Walk

Spring's AnnotationUtils.findAnnotation() walks up the class hierarchy (superclasses, interfaces) to find an annotation, supporting Spring's "annotation inheritance" semantics that go beyond Java's built-in @Inherited. This is relevant when using composed annotations (meta-annotations on other annotations).

Java 17+ Module System Impact on Spring

Spring 6+ (Boot 3+) targets Java 17 as the baseline. Strong encapsulation in the module system means setAccessible(true) on module-private members throws InaccessibleObjectException unless the module explicitly opens packages. Spring's best practice is to use public constructors and avoid private field injection — prefer constructor injection, which works without setAccessible.

8. Security Risks of Reflection and module-info.java in Java 9+

The power of reflection is also its danger. setAccessible(true) bypasses Java's access control model entirely, which can be exploited in multi-tenant environments or when processing untrusted input.

Key Security Risks

• Access to private fields — attacker can read/write secrets stored in private fields (e.g., credentials, cryptographic keys).
• Bypassing encapsulation — violating invariants maintained by private setters.
• Arbitrary code execution — Class.forName(userInput).newInstance() with unsanitized input can instantiate any class on the classpath.
• Deserialization attacks — Java deserialization uses reflection internally; gadget chains exploit this.

Java 9 Module System: Strong Encapsulation

The Java Platform Module System (JPMS) introduced in Java 9 closes the biggest reflection loopholes. Packages in a named module are not accessible via reflection unless the module explicitly opens them.

// module-info.java — controlling reflective access
module com.example.myapp {
    requires spring.context;

    // Open entire package for reflective access (Spring injection)
    opens com.example.myapp.service to spring.core;

    // Open to all modules (avoid in production — use targeted opens)
    // opens com.example.myapp.model;

    exports com.example.myapp.api;   // public API, no reflection needed
}

--add-opens vs opens in module-info

When you cannot modify a module's module-info.java (e.g., JDK internals), the JVM flag --add-opens java.base/java.lang=ALL-UNNAMED grants reflective access. This is a bypass mechanism — use it sparingly and document why it is needed. Avoid using it in production if possible.

Security Manager (Deprecated/Removed)

The SecurityManager was the traditional guard against dangerous reflection operations. It was deprecated in Java 17 and removed in Java 24. Modern alternatives are the module system (static encapsulation) and explicit API design.

Safe Reflection Practices

// DANGEROUS — arbitrary class loading from user input
String className = request.getParameter("class");
Class<?> clazz = Class.forName(className); // NEVER DO THIS

// SAFE — allowlist of permitted class names
private static final Set<String> ALLOWED_PROCESSORS = Set.of(
    "com.example.processors.JsonProcessor",
    "com.example.processors.XmlProcessor"
);

public Processor loadProcessor(String className) throws Exception {
    if (!ALLOWED_PROCESSORS.contains(className)) {
        throw new SecurityException("Class not in allowlist: " + className);
    }
    return (Processor) Class.forName(className).getDeclaredConstructor().newInstance();
}

• Always validate class names loaded from external input against an allowlist.
• Avoid setAccessible(true) in security-sensitive code paths.
• Use module-info.java with targeted opens rather than broad --add-opens.
• Prefer constructor injection over field injection to reduce the need for setAccessible.

9. Annotations in Testing: JUnit 5, Mockito and Spring Test

Testing frameworks rely heavily on annotations to declaratively configure test lifecycle, inject dependencies, and control application context loading. Understanding how these annotations work helps write cleaner, faster tests.

JUnit 5 Core Annotations

• @Test — marks a test method; no value elements needed (unlike JUnit 4)
• @ParameterizedTest — runs the test with multiple data sets from @ValueSource, @CsvSource, @MethodSource, etc.
• @BeforeEach / @AfterEach — setup and teardown per test method
• @BeforeAll / @AfterAll — setup and teardown once per test class (method must be static unless @TestInstance(PER_CLASS))
• @ExtendWith — registers a JUnit 5 extension (replaces JUnit 4 runners)
• @Tag — categorises tests for selective execution (e.g., "integration", "slow")
• @Disabled — skips the test with an optional reason message
• @TestMethodOrder — controls execution order (OrderAnnotation, Random, MethodName)

Mockito Annotations Processed via Reflection

Mockito's MockitoExtension (registered with @ExtendWith(MockitoExtension.class)) uses reflection to scan the test class for Mockito annotations and inject generated mocks before each test.

• @Mock — creates a mock instance of the annotated type
• @InjectMocks — creates the subject under test and injects @Mock/@Spy fields by constructor, setter, or field injection
• @Captor — creates an ArgumentCaptor
• @Spy — wraps a real object, enabling partial mocking

Spring Test Slice Annotations

• @SpringBootTest — loads the full application context; use for integration tests
• @WebMvcTest(UserController.class) — loads only the web layer (controllers, filters, converters); no service beans unless added with @MockBean
• @DataJpaTest — loads only JPA repositories and an in-memory H2 database; transactions rolled back after each test by default
• @JsonTest — tests JSON serialization/deserialization in isolation

Full Example: Testing with Annotations

@ExtendWith(MockitoExtension.class)
@Tag("unit")
class OrderServiceTest {

    @Mock
    private OrderRepository orderRepository;

    @Mock
    private PaymentGateway paymentGateway;

    @InjectMocks
    private OrderService orderService; // Mockito injects mocks via reflection

    @Captor
    private ArgumentCaptor<Order> orderCaptor;

    @Test
    @DisplayName("createOrder should persist and charge payment")
    void createOrder_success() {
        // Arrange
        OrderRequest request = new OrderRequest("PROD-1", 2, BigDecimal.valueOf(49.99));
        when(paymentGateway.charge(any())).thenReturn(PaymentResult.SUCCESS);

        // Act
        orderService.createOrder(request);

        // Assert
        verify(orderRepository).save(orderCaptor.capture());
        Order saved = orderCaptor.getValue();
        assertThat(saved.getStatus()).isEqualTo(OrderStatus.CONFIRMED);
        assertThat(saved.getTotal()).isEqualByComparingTo(BigDecimal.valueOf(99.98));
    }

    @ParameterizedTest
    @ValueSource(ints = {0, -1, -100})
    @DisplayName("createOrder should reject invalid quantities")
    void createOrder_invalidQuantity(int qty) {
        OrderRequest request = new OrderRequest("PROD-1", qty, BigDecimal.ONE);
        assertThatThrownBy(() -> orderService.createOrder(request))
            .isInstanceOf(IllegalArgumentException.class)
            .hasMessageContaining("quantity");
    }
}

// Integration test slice
@WebMvcTest(OrderController.class)
@ActiveProfiles("test")
@TestPropertySource(properties = "feature.orders.enabled=true")
class OrderControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @MockBean
    private OrderService orderService;

    @Test
    void postOrder_returns201() throws Exception {
        when(orderService.createOrder(any())).thenReturn(new OrderResponse("ORD-123"));
        mockMvc.perform(post("/api/orders")
                .contentType(MediaType.APPLICATION_JSON)
                .content("{\"productId\":\"P1\",\"quantity\":1}"))
            .andExpect(status().isCreated())
            .andExpect(jsonPath("$.orderId").value("ORD-123"));
    }
}

10. Conclusion and Best Practices Summary

Java annotations and the Reflection API are foundational tools that power virtually every major Java framework. Mastering them — understanding their costs, their semantics, and how frameworks exploit them — separates a journeyman Java developer from a senior backend engineer.

Related Posts