DEV Community: Aquib Javed

Mastering Custom Validation Annotations in Spring Boot 3: Beyond @NotNull

Aquib Javed — Sat, 20 Dec 2025 13:43:58 +0000

Beyond @NotNull: Creating Custom Validation Annotations in Spring Boot 3

TL;DR: Standard Jakarta Bean Validation annotations often fail to capture complex, multi-field business rules. This guide explains how to implement the ConstraintValidator interface to create reusable, class-level custom annotations in Spring Boot. Anyone who wants to learn how to create their own custom annotation and handle business specific-logic, must go through the blog.

Audience: Java developers familiar with Spring Boot and basic REST API development.

Scope: This guide covers the creation of a class-level validation annotation (@OfficialInviteCode). It does not cover simple field-level regex validation or frontend integration.

The Limitations of Standard Annotations

Imagine you have these business rules for a VIP event:

Invite Code: Must start with "VIP-".
Age: Guests must be older than 35.
Email: Must end with a .com domain.
Name: Must be uppercase (business requirement).

Standard annotations like @Email or @Min handle these rules individually, but they often struggle with interdependent logic or specific business formats.

The Imperative Approach (Anti-Pattern)

Developers often mix validation logic directly into the service or controller layer:

// Avoid this approach
if (!dto.getInviteCode().startsWith("VIP-")) {
    throw new ValidationException("Invalid Code");
}

This approach creates code duplication and makes unit testing difficult.
The Declarative Approach (Best Practice)
A better solution uses a custom annotation to centralize logic and separate concerns:

@OfficialInviteCode
private String inviteCode;

This guide demonstrates how to implement this declaratively using class-level validation.
Implementation Guide
Follow this order of operations to implement custom validation:
Define the DTO.
Define the custom annotation interface.
Implement the ConstraintValidator.
Apply the annotation to the DTO.
Create the Controller.
Add a Global Exception Handler.

Create the DTO Class Define the data structure and apply standard constraints where applicable.

public class GuestRegistrationDto {
    @NotNull
    private String name;

    @Min(value = 35, message = "Guest must be above 35")
    private int age;

    @Email
    @NotBlank
    private String email;

    private String inviteCode;

    // Getters and Setters
    public String getName() { return name; }
    public String getEmail() { return email; }
    public String getInviteCode() { return inviteCode; }
    public int getAge() { return age; }
}

Define the Custom Annotation Create the @OfficialInviteCode interface. This interface acts as the contract for your validation logic.

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = OfficialInviteCodeValidator.class)
public @interface OfficialInviteCode {

    String message() default "Invalid invite code";
    Class<?>[] groups() default {};
    Class<? extends jakarta.validation.Payload>[] payload() default {};
}

Key Concepts:
@Target(ElementType.TYPE): Indicates that you apply this annotation to the class level, allowing access to all fields within the class.
@Retention(RetentionPolicy.RUNTIME): Ensures the annotation remains available to the JVM during execution for Spring's reflection mechanisms.
@Constraint(validatedBy = ...): Links this annotation to the OfficialInviteCodeValidator class, which contains the logic.
The Jakarta API Contract:
The API mandates three attributes for every validation annotation:
message(): The default error text.
groups(): Enables validation groups (e.g., validate only on "Update" operations).
payload(): Attaches custom metadata, such as severity levels.
3.Implement the ConstraintValidator
Override the isValid method to implement your specific business rules.

public class OfficialInviteCodeValidator implements ConstraintValidator<OfficialInviteCode, GuestRegistrationDto> {

    @Override
    public boolean isValid(GuestRegistrationDto dto, ConstraintValidatorContext constraintValidatorContext) {
        if (dto == null) return true;

        String name = dto.getName();
        String email = dto.getEmail();
        String code = dto.getInviteCode();
        int age = dto.getAge();

        // Business Logic Validation
        if (name != null && !name.equals(name.toUpperCase())) {
            return false; 
        }
        if (email != null && !email.endsWith(".com")) {
            return false;
        }
        if (code != null && !code.startsWith("VIP-")) {
            return false;
        }
        if (age >= 35) {
            return true;         
        }
        return false;
    }
}

Annotate the DTO Apply your new annotation to the class definition. The DTO now expresses both built-in constraints and your custom logic.

@OfficialInviteCode
public class GuestRegistrationDto {
    // fields...
}

Now the DTO expresses all rules: built-in constraints + your custom constraint in one place.

Create the REST Controller Use the @valid annotation to trigger the validation logic before the method executes.

@RestController
public class GuestController {

    @PostMapping("/invite")
    public ResponseEntity<?> registerGuest(@Valid @RequestBody GuestRegistrationDto dto) {
        return ResponseEntity.ok("registered");
    }
}

Handle Exceptions Globally Create a @RestControllerAdvice class to catch MethodArgumentNotValidException and return a clean JSON response.

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(MethodArgumentNotValidException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public Map<String, String> handleValidationException(MethodArgumentNotValidException ex) {
        String message = ex.getBindingResult()
                .getFieldErrors()
                .stream()
                .findFirst()
                .map(DefaultMessageSourceResolvable::getDefaultMessage)
                .orElse("Invalid request");

        Map<String, String> body = new HashMap<>();
        body.put("error", message);
        return body;
    }
}

Architecture & Best Practices
To master custom validation, understand how Spring manages the lifecycle of validator classes.
Leverage Dependency Injection
Spring manages your ConstraintValidator implementation as a Bean. This allows you to inject services or repositories directly into the validator.
Use Case: Verify data existence in the database (e.g., checking if a coupon code is valid) rather than just checking format.

public class CouponValidator implements ConstraintValidator<ValidCoupon, String> {

    @Autowired
    private CouponRepository couponRepository; // Spring injects this dependency

    @Override
    public boolean isValid(String code, ConstraintValidatorContext context) {
        return couponRepository.existsByCode(code);
    }
}

Ensure Thread Safety
Spring treats Validator classes as Singletons. The container creates one instance and reuses it for every request.
The Risk: Storing request-specific data in instance variables causes race conditions.
The Solution: Keep validators stateless. Perform all logic using only the local variables passed into the isValid() method.

Conclusion
Spring Boot’s validation framework extends well beyond simple null checks. By using ConstraintValidator, you create robust, reusable, and centralized business rules that keep your controllers and services clean.

How to Handle HttpClientErrorException in Spring RestTemplate: A Complete Guide

Aquib Javed — Sun, 30 Nov 2025 12:18:35 +0000

The Problem

RestTemplate restTemplate = new RestTemplate();
// If this URL returns 404, the app crashes!
String response = restTemplate.getForObject("https://api.example.com/users/999", String.class);

While working on a company project one evening, I encountered an HttpClientErrorException from an API response. This error was new to me. After debugging, I solved it and learned how to handle it properly.

In this post, I'll explain what this error is and how you can handle it in your code.

Understanding RestTemplate Exceptions

RestTemplate throws RestClientResponseException and its subtypes when API calls fail. The most common subtypes are HttpClientErrorException and HttpServerErrorException.

Here is the exception hierarchy:

RestClientException → base class
RestClientResponseException extends RestClientException
HttpStatusCodeException extends RestClientResponseException
HttpClientErrorException extends HttpStatusCodeException
HttpServerErrorException extends HttpStatusCodeException

RestClientResponseException is the base class that contains the actual HTTP response data.

How RestTemplate Handles HTTP Status Codes

RestTemplate returns ResponseEntity only for successful 2xx responses.

For 4xx errors, it throws HttpClientErrorException.

For 5xx errors, it throws HttpServerErrorException.

How to Catch HttpClientErrorException

You will frequently encounter HttpClientErrorException when calling external APIs using RestTemplate. This exception indicates that the remote service returned a 4xx HTTP error. The request failed due to a client-side issue.

If you do not handle this exception, your application may terminate unexpectedly.

Wrap the API call inside a try-catch block. By catching the exception, you can gracefully handle the error. You can log it, return a meaningful response, or trigger fallback logic. This prevents your system from crashing.

This ensures your application remains stable, resilient, and production-safe even when the external API returns invalid or unexpected responses.

Solution: Use Try-Catch

The easiest way to handle these exceptions is to wrap the call in a try-catch block:

try {
    ResponseEntity<String> response =
            restTemplate.getForEntity("https://example.com/api/data", String.class);

    System.out.println("Success: " + response.getBody());
}
catch (HttpClientErrorException e) {
    // Handles 4xx errors
    System.out.println("Client Error: " + e.getStatusCode());
    System.out.println("Error Body: " + e.getResponseBodyAsString());
}

This approach keeps your application running and gives you visibility into what went wrong.

Enterprise-Level Error Handling with GlobalExceptionHandler

The Challenge with Try-Catch Blocks

As the number of API calls increases in your application, handling everything with try-catch blocks becomes difficult. Managing exceptions manually in every method leads to code duplication and maintenance issues.

To handle errors at an enterprise level, you should implement a Global Exception Handler.

What is a GlobalExceptionHandler?

A GlobalExceptionHandler is a centralized error-handling mechanism. Instead of scattering try-catch blocks throughout your codebase, you define error-handling logic in one place. Spring automatically applies this logic to every controller in your application.

How to Implement GlobalExceptionHandler

Here is the cleanest and simplest way to handle HttpClientErrorException using a GlobalExceptionHandler:

Step 1: Create a Separate Class for Global Error Handling

Large-scale systems must centralize all error handling in one place. This keeps your code clean and maintainable.

Step 2: Annotate with @ControllerAdvice

The @ControllerAdvice annotation tells Spring to scan this class automatically and apply your error-handling logic to every controller in your project.

Step 3: Create a Method to Handle HttpClientErrorException

Your global handler will catch the exception before it crashes the system and return a custom error response.

Step 4: Use @ExceptionHandler

The @ExceptionHandler annotation tells Spring exactly which exception this method should catch and handle.

Implementation Example

@ControllerAdvice
public class GlobalExceptionHandler {

    // Step 2: Handle RestTemplate 4xx errors (HttpClientErrorException)
    @ExceptionHandler(HttpClientErrorException.class)
    public ResponseEntity<Object> handleHttpClientError(HttpClientErrorException ex) {

        // Step 3: Create a simple JSON error response body
        Map<String, Object> body = new LinkedHashMap<>();
        body.put("timestamp", LocalDateTime.now());
        body.put("status", ex.getStatusCode().value());
        body.put("error", ex.getStatusCode());
        body.put("message", ex.getMessage());

        // Step 4: Return the response with correct HTTP status
        return new ResponseEntity<>(body, ex.getStatusCode());
    }
}

How It Works

This code tells Spring: whenever RestTemplate throws a 4xx error, handle it here instead of crashing.

With this setup, you no longer need try-catch blocks around every API call. Spring automatically routes all HttpClientErrorException instances to your global handler. This approach is clean, scalable, and production-ready.

Pro Tip: Always log the error body (ex.getResponseBodyAsString()) inside your exception handler. APIs often return helpful validation messages (like 'Email already exists') inside the 400 Bad Request body, which you don't want to lose.