🤿 Mastering Exception Handling in Spring : @RestControllerAdvice

Exception handling, in the broader context of software development, refers to the systematic approach of managing and responding to unexpected events or errors that can occur during the execution of a computer program. These exceptions can range from runtime errors and network failures to input validation issues. The primary goal of exception handling is to prevent application crashes and provide a graceful response to users when errors occur, enhancing the reliability and resilience of the software.

In this guide, we will delve into the specific techniques and practices for implementing effective Exception Handling in Spring, with a particular emphasis on the versatile @RestControllerAdvice annotation.

We’ll explore best practices, practical examples, and key insights to empower your application’s resilience.

📕 Fundamentals of Exception Handling in Java

Before delving into advanced concepts, let’s establish a foundation in Java’s exception handling. The try-catch mechanism stands as the fundamental approach. Place your code within a try block, and any exceptions thrown by the code are intercepted by one or more catch blocks.

This method effectively captures various types of Java exceptions, making it a straightforward and essential approach for managing errors.

try {
  // code which can throw exceptions
} catch (final Exception ex) {
  // Exception handling
  System.out.printf("Error with message: %s", ex.getMessage());
}

Important Note: A tryblock cannot stand alone. It must be directly followed by either a catchor a finallyblock.”

Targeted Exception Handling in Java

In Java, you have the flexibility to capture specific exceptions, enabling you to craft dedicated code for handling particular errors. For instance, in the context of REST API errors, some are recoverable while others are not. This approach allows you to distinguish between these scenarios.

To achieve this, you can extend a tryblock with multiple catchblocks, each specifying a distinct exception type. When an exception occurs, Java executes the first catchblock that matches the exception class or one of its superclasses. Therefore, it’s important to prioritize the catchblocks with the most specific exception classes.

try {
  // code which can throw exceptions
} catch (NumberException ex) {
  // exception handler for NumberException
  System.out.printf("Error with message: %s", ex.getMessage());
} catch (NumberFormatException ex) {
  // Exception handler for NumberFormatException
  System.out.printf("Error handling number format: %s", ex.getMessage());
  
}

When an exception is triggered within the tryblock, it is directed to the initial catchblock. If the exception isn’t handled there, it proceeds to the subsequent catchstatement. This process repeats until the exception is either intercepted or exhausts all available catchblocks.

The Importance of the finally Block

A finally block is where you place code that must execute regardless of whether an exception occurs. In simple terms, the finally block guarantees execution under all circumstances. For instance, if you have an open connection to a database or file, the finally block is ideal for closing the connection, ensuring it happens even if the try block encounters a Java exception.

try {
  // code which can throw exceptions
} catch (NumberException ex) {
  // exception handler for NumberException
  System.out.printf("Error with message: %s", ex.getMessage());
} catch (NumberFormatException ex) {
  // Exception handler for NumberFormatException
  System.out.printf("Error handling number format: %s", ex.getMessage());
  
} finally {
  // finally block always executes
}

🎓Introduction to @RestControllerAdvice

The @RestControllerAdvice annotation is a specialized form of the @Componentannotation, which enables automatic detection through classpath scanning. It serves as an interceptor that envelops the operations within our Controllers, allowing us to apply common logic to them.

The methods within @RestControllerAdvice (marked with @ExceptionHandler) are accessible globally to multiple @Controllercomponents, and their purpose is to catch exceptions and transform them into HTTP responses. The @ExceptionHandlerannotation specifies the type of Exception that should be managed. The method will receive the exception instance and the request as method arguments.

By combining these two annotations, we achieve the following:

1. Control over the response content and status code.
2. The ability to handle multiple exceptions within a single method.

🤔 @RestControllerAdvice or @ControllerAdvice?

In the Spring Framework’s landscape of exception handling, two key annotations, @RestControllerAdvice and @ControllerAdvice, play distinct roles. Understanding their differences is crucial for effective application development.

@ControllerAdvice: This annotation is well-suited for applications that primarily generate traditional HTML views. When your application is focused on rendering web pages, @ControllerAdvice is the appropriate choice. It excels at handling exceptions within the context of web views and provides a means to customize error responses in HTML format.

@RestControllerAdvice: In contrast, @RestControllerAdvice finds its niche in applications that predominantly serve data in JSON, XML, or other structured formats. This is especially common in RESTful web services, where the primary task is delivering data to clients. @RestControllerAdviceis designed to manage exceptions and tailor error responses specifically for these data-centric scenarios.

However, @ControllerAdvicecan also be used for REST services, but the following must be taken into account:

• @RestControllerAdvice is a composed annotation that is annotated with both @ControllerAdvice and @ResponseBody, which essentially means @ExceptionHandler methods are rendered to the response body through message conversion (versus view resolution or template rendering), so @ControllerAdvice can be used even for REST web services as well, but you need to additionally use @ResponseBody.

✨Advantages of Using @RestControllerAdvice

Discover the benefits of @RestControllerAdvice and its role in Exception Handling in Spring for data-centric applications:

1. Streamlined Error Responses: @RestControllerAdvice empowers developers to craft consistent and structured error responses in formats like JSON or XML. This standardization enhances communication between the application and its clients, making it easier to interpret and handle errors programmatically.

2. Precision in RESTful Environments: RESTful services often require pinpoint precision in “exception handling in Spring.” With @RestControllerAdvice, you can tailor error messages to meet the specific needs of your RESTful API clients, ensuring that they receive informative and contextually relevant responses.

3. Enhanced Data Validation: Data validation is paramount in RESTful services. @RestControllerAdvice makes it simpler to validate incoming data and promptly respond with clear validation error messages, helping to maintain data integrity and reduce the risk of erroneous data entry.

4. Simplified Exception Handling: Exception handling becomes more straightforward with @RestControllerAdvice. By consolidating error-handling logic in one place, it simplifies code maintenance and reduces redundancy, resulting in cleaner and more maintainable codebases.

5. Focused Approach: @RestControllerAdvice is well-suited to applications where the primary focus is delivering data. This specialization allows developers to address exceptions and errors in a way that's tailored to the data-driven nature of their applications.

These advantages underscore the importance of @RestControllerAdvice in the context of RESTful services and data-centric applications. By leveraging its capabilities, developers can ensure that their applications not only handle errors gracefully but also provide a seamless and reliable experience to their users and clients.

In the subsequent sections, we’ll explore practical examples and delve deeper into best practices for harnessing the full potential of @RestControllerAdvice in your Spring-based projects.

💣Practical Implementation:

To test the functionality of @RestControllerAdvice and its different use cases, we are going to define two small use cases where we will create a new client and search for it using its identifier. To do this I bring you a custom error handling approach that I personally find to be a pretty clean and robust solution:

Starting Point:

@RestController
@RequiredArgsConstructor
public class ClientController {

    private final ClientService clientService;

    @PostMapping("api/v1/clients")
    public ClientDTO create(@RequestBody ClientDTO clientDTO) {
        try {
            return this.clientService.create(clientDTO);
        } catch (ClientAlreadyExistsException ex) {
            System.out.println("Client already exists");
            throw new CustomException1(ex.getMessage());

        } catch (EmailBadFormatException ex) {
            System.out.println("Email has bad format");
            throw new CustomException2(ex.getMessage());
        }
    }

    @GetMapping("api/v1/clients/{id}")
    public ClientDTO find(@PathVariable Long id) {
        try {
            return this.clientService.find(id);
        } catch (ClientNotFoundException ex) {
            System.out.println("Client already exists");
            throw new CustomException3(ex.getMessage());

        }
    }
}

As you can see, this is a very basic example of exception handling, but you can see how the complexity of the controller grows as the number of conditions in our application grows, so the readability of our code is affected.

To improve this we are going to create our @RestControllerAdvice that will be our central point of handling exceptions, cleaning this way the rest of the application of this arduous task.

Initially we are going to define our “abstract” exception that must inherit from RuntimeExceptionand where we are going to define the fields that we want to collect in our exceptions. This class will be the parent of the rest of exceptions that we define in our application:

@Getter
@Setter
@AllArgsConstructor
public class AbstractException extends RuntimeException {

    private String message;

    private Map<String, String> details;

}

In our case we only want to collect a custom message and a detail map where we can give more detailed information of the exception that has occurred (the definition of the fields is on demand, needs of the application or imagination of each developer).

Next we are going to create 2 custom exceptions: one for the calls to our API Rest invalid and another one for when a certain entity is found inside the application.

public class EntityNotFoundException extends AbstractException {
    
    public EntityNotFoundException(String message, Map<String, String> details) {
        super(message, details);
    }
}

public class InvalidCallException extends AbstractException {

    public InvalidCallException(String message, Map<String, String> details) {
        super(message, details);
    }
}

As you can see, they simply call the constructor of theAbstractException that we have created previously. At this point, this is customizable, for example we could also define a static message for each type of exceptions and that inside detailswe have more concrete information of our exception.

Finally we define our global exception handler together with the error DTO that we want to send to the client (frontend) to be painted on the screen or handle it in the way it deems most appropriate :

@Data
@Builder
public class ErrorMessageDTO implements Serializable {


    private String message;

    private Instant date;

    private Map<String, String> details;

}

@RestControllerAdvice
public class GlobalExceptionResponseHandler {
    
    @ExceptionHandler(value = {InvalidCallException.class})
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public ErrorMessageDTO mapInvalidCallException(InvalidCallException ex, WebRequest request) {

        return ErrorMessageDTO.builder()
                .message(ex.getMessage())
                .date(Instant.now())
                .details(ex.getDetails())
                .build();
    }

    @ExceptionHandler(value = {EntityNotFoundException.class})
    @ResponseStatus(HttpStatus.NOT_FOUND)
    public ErrorMessageDTO mapNotFoundException(EntityNotFoundException ex, WebRequest request) {

        return ErrorMessageDTO.builder()
                .message(ex.getMessage())
                .date(Instant.now())
                .details(ex.getDetails())
                .build();
    }



}

The operation of our global exception handler is quite simple, we simply annotate the class with @RestControllerAdviceand define a method for each type of exception depending on the HTTP Status we want to send to the client. In each method, we need to define in @ExceptionHandler the exception to be handled in that method + @ResponseStatus indicating the HTTP status to be sent to the client.

At this point, each method handles the exception that is indicated and is built in response DTO based on the fields of our AbstractException (it is the parent exception that defines the fields used by InvalidadCallException and EntityNotFoundException).

All this architecture is customizable, for example we could also define an ExceptionMessagesEnum where we define the messages that we want to send to the client and then reuse this enum when sending exceptions of the type that we consider. For example :

@Getter
@AllArgsConstructor
public enum ExceptionMessagesEnum {
    
    CLIENT_NOT_FOUND("Client not found"),
    
    EMAIL_BAD_FORMAT("Email has bad format"),
    
    CLIENT_ALREADY_EXISTS("Client already exists");
    
    private final String description;

}

In our service :

public ClientDTO find(Long id) {
    return this.clientRepository.findById(id)
            .map(this.mapper::asDto)
            .orElseThrow(() -> new EntityNotFoundException(CLIENT_NOT_FOUND.getDescription(), Map.of("ID", String.valueOf(id))));


}

Results 🎉:

We can even add an improvement: if our application has Internationalization, we can redefine our exception enum descriptionfield to indicate the key of our messages.propertiesfiles. So that in our global exception handler we inject the MessageSourcebean to obtain the internationalized message based on this new field.

https://www.baeldung.com/spring-boot-internationalization

🥇Best Practices

In the realm of “Exception Handling in Spring,” following best practices is paramount to ensure the resilience and reliability of your applications. Here are some key recommendations to consider:

• Precise Exception Selection: Exception handling begins with the selection of the right exception type. Choose exceptions that accurately reflect the error scenario to provide meaningful responses.
• Custom Error Messages: Tailor error messages to convey relevant information to users and developers. Include error codes, descriptions, and guidance for resolution.
• Logging and Monitoring: Implement robust logging to capture error details. Additionally, set up monitoring to proactively identify and address recurring issues.
• Global Exception Handling: Consider using a global exception handler to centralize common exception handling logic. This enhances code maintainability and reduces redundancy.
• Testing and Validation: Rigorously test your exception handling logic to ensure it functions as intended. Validate data inputs to preemptively catch errors.
• Documentation: Document your exception handling strategies and the responses provided. This documentation serves as a valuable resource for your development team and API consumers.
• Regular Updates: Review and update your exception handling mechanisms as your application evolves. Ensure they remain aligned with your application’s evolving requirements.
• Security Considerations: When handling exceptions, be mindful of potential security vulnerabilities. Avoid exposing sensitive information in error messages.

By adhering to these best practices, you can create a robust and reliable Exception Handling in Spring that not only enhances user experience but also streamlines development and troubleshooting efforts.

🏁 Conclusions and Additional Resources

In conclusion, this guide has provided a comprehensive understanding of Exception Handling in Spring with a particular focus on the versatile @RestControllerAdvice annotation. We've explored the fundamentals of Exception Handling in Spring, highlighting the critical role it plays in building robust and reliable applications.

As you embark on your journey to enhance your application’s resilience, remember to follow best practices, customize error messages, and maintain precision in error responses. Continuously update and test your exception handling mechanisms to align with evolving application requirements.

To further expand your knowledge and proficiency in Spring Framework and Exception Handling, consider exploring the following additional resources:

1. Spring Framework Documentation: The official Spring Framework documentation offers in-depth insights, tutorials, and reference materials to help you master Spring’s various components and features.
2. Online Communities: Engage with online communities, forums, and discussion boards related to Spring Framework. Platforms like Stack Overflow and the Spring Community Forum provide a space for developers to seek help and share knowledge.
3. Advanced Spring Courses: Consider enrolling in advanced Spring courses or certifications to deepen your expertise in Spring Framework and its advanced features.
4. Books: Explore books dedicated to Spring Framework and Exception Handling to gain in-depth knowledge and practical insights from experienced authors.

By continuing to learn and apply best practices, you’ll be well-equipped to handle exceptions effectively and build resilient applications in the dynamic world of Spring Framework. Exception Handling in Spring is a critical aspect of application development, and your expertise in this area will set the foundation for reliable and user-friendly software.

HAPPY CODING! 🎯