Migrate HttpStatus to HttpStatusCode in Spring Boot 3

1. Overview

In this article, we’ll look at how to use HttpStatusCode in Spring Boot applications, focusing on the most recent enhancements introduced in version 3.3.3. With these enhancements, HttpStatusCode has been incorporated into the HttpStatus implementation, simplifying how we work with HTTP status codes.

The main purpose of these improvements is to provide a more flexible and reliable method for handling both standard and custom HTTP status codes, giving us higher flexibility and extensibility when working with HTTP responses while maintaining backward compatibility.

2. HttpStatus Enumerator

Prior to Spring 3.3.3, HTTP status codes were represented as enums in HttpStatus. This limited the use of custom or non-standard HTTP status codes as enums are a fixed set of predefined values.

Even though the HttpStatus class hasn’t been deprecated, some enums and methods that return raw integer status codes, such as getRawStatusCode() and rawStatusCode(), are now deprecated. Still, using the @ResponseStatus annotation to improve code readability remains the recommended approach.

We may also use HttpStatus in conjunction with HttpStatusCode for more flexible HTTP response management:

@GetMapping("/exception")
public ResponseEntity<String> resourceNotFound() {
    HttpStatus statusCode = HttpStatus.NOT_FOUND;
    if (statusCode.is4xxClientError()) {
        return new ResponseEntity<>("Resource not found", HttpStatusCode.valueOf(404));
    }
    return new ResponseEntity<>("Resource found", HttpStatusCode.valueOf(200));
}

3. HttpStatusCode Interface

The HttpStatusCode interface is designed to support custom status codes beyond the predefined ones in HttpStatus. It has 8 instance methods:

• is1xxInformational()
• is2xxSuccessful()
• is3xxRedirection()
• is4xxClientError()
• is5xxServerError()
• isError()
• isSameCodeAs(HttpStatusCode other)
• value()

These methods not only increase the flexibility of dealing with different HTTP statuses but also streamline the process of checking response categories, which improves the clarity and efficiency of status code management.

Let’s look at an example of how we may use them in practice:

@GetMapping("/resource")
public ResponseEntity successStatusCode() {
    HttpStatusCode statusCode = HttpStatusCode.valueOf(200);
    if (statusCode.is2xxSuccessful()) {
        return new ResponseEntity("Success", statusCode);
    }

    return new ResponseEntity("Moved Permanently", HttpStatusCode.valueOf(301));
}

3.1. Static Method valueOf(int)

This method returns an HttpStatusCode object for the given int value. The input parameter must be a 3-digit positive number, or else we get an IllegalArgumentException.

valueOf() maps a status code to a corresponding enum value within HttpStatus. If no existing entry matches the provided status code, the method defaults to returning an instance of DefaultHttpStatusCode.

The DefaultHttpStatusCode class implements the HttpStatusCode and offers a straightforward implementation of the value() method, which returns the original integer value used to initialize it. This approach ensures that all HTTP status codes, whether custom or non-standard, remain easy to work with:

@GetMapping("/custom-exception")
public ResponseEntity<String> goneStatusCode() {
    throw new ResourceGoneException("Resource Gone", HttpStatusCode.valueOf(410));
}

4. Using HttpStatusCode in Custom Exceptions

Next, let’s look at how to use a custom exception with HttpStatusCode within an ExceptionHandler. We’ll use the @ControllerAdvice annotation to handle exceptions globally across all controllers, and the @ExceptionHandler annotation to manage instances of the custom exception.

This approach centralizes error handling in Spring MVC applications, making the code cleaner and more maintainable.

4.1. @ControllerAdvice and @ExceptionHandler

@ControllerAdvice handles exceptions globally, while @ExceptionHandler manages custom exception instances to return consistent HTTP responses with the exception message and status code.

Let’s look at how we can use both annotations in practice:

@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(CustomException.class)
    public ResponseEntity<String> handleGoneException(CustomException e) {
        return new ResponseEntity<>(e.getMessage(), e.getStatusCode());
    }
}

4.2. Custom Exceptions

Next, let’s define a CustomException class that extends RuntimeException and includes an HttpStatusCode field, enabling custom messages and HTTP status codes for more precise error handling:

public class CustomException extends RuntimeException {

    private final HttpStatusCode statusCode;

    public CustomException(String message, HttpStatusCode statusCode) {
        super(message);
        this.statusCode = statusCode;
    }

    public HttpStatusCode getStatusCode() {
        return statusCode;
    }
}

5. Conclusion

The HttpStatus enum contains a limited set of standard HTTP status codes, which in older versions of Spring worked well for most use cases. However, they lacked flexibility in defining custom status codes.

Spring Boot 3.3.3 introduces HttpStatusCode, addressing this limitation by allowing us to define custom status codes. This provides a more flexible way to handle HTTP status codes, with instance methods for commonly used status codes such as is2xxSuccessful() and is3xxRedirection(), ultimately allowing for more granular control over response handling.

As usual, the complete code with all the examples presented in this article are available over on GitHub.