Package io.github.og4dev.exception

Class GlobalExceptionHandler

java.lang.Object
io.github.og4dev.exception.GlobalExceptionHandler
@ConditionalOnProperty(prefix="api-response", name="enabled", havingValue="true", matchIfMissing=true) @RestControllerAdvice public class GlobalExceptionHandler extends Object
Global exception handler for Spring Boot REST APIs with comprehensive error coverage.

This class provides production-ready centralized exception handling using Spring's RestControllerAdvice mechanism. It automatically converts various exceptions into RFC 9457 ProblemDetail responses (the latest standard, superseding RFC 7807) with trace IDs for debugging and request correlation.

Supported Exception Types (10 handlers):

  1. General Exceptions - Catches all unhandled exceptions (HTTP 500)
  2. Validation Errors - @Valid annotation failures (HTTP 400)
  3. Type Mismatches - Method argument type conversion errors (HTTP 400)
  4. Malformed JSON - Invalid request body format (HTTP 400)
  5. Missing Parameters - Required @RequestParam missing (HTTP 400)
  6. 404 Not Found - Missing endpoints or resources (HTTP 404)
  7. Method Not Allowed - Unsupported HTTP methods (HTTP 405)
  8. Unsupported Media Type - Invalid Content-Type headers (HTTP 415)
  9. Null Pointer Exceptions - NullPointerException handling (HTTP 500)
  10. Custom API Exceptions - Domain-specific business logic errors (custom status)

Error Response Format (RFC 9457 ProblemDetail):

  • type - URI reference identifying the problem type (defaults to "about:blank")
  • title - Short, human-readable summary of the problem
  • status - HTTP status code
  • detail - Human-readable explanation specific to this occurrence
  • traceId - Unique UUID for request correlation and debugging
  • timestamp - RFC 3339 UTC timestamp
  • errors - Validation field errors (for validation failures only)

Trace ID Management: All exception handlers ensure consistent trace IDs between logs and error responses. If no trace ID exists in MDC, one is automatically generated to ensure every error has a correlatable identifier.

Disabling the Handler: This handler can be disabled by setting the application property api-response.enabled=false.

Logging: All exceptions are automatically logged with appropriate severity levels:

  • ERROR - General exceptions, null pointer exceptions
  • WARN - Validation errors, type mismatches, business logic exceptions, 400/404/405/415 errors
Since:
1.0.0
Version:
1.4.0
Author:
Pasindu OG
See Also:

  • Constructor Details

    • GlobalExceptionHandler

      public GlobalExceptionHandler()
      Default constructor for Spring bean instantiation.

  • Method Details

    • handleAllExceptions

      @ExceptionHandler(java.lang.Exception.class) public org.springframework.http.ProblemDetail handleAllExceptions(Exception ex)
      Handles all unhandled exceptions.
      Parameters:
      ex - the exception
      Returns:
      ProblemDetail response with 500 status

    • handleValidationExceptions

      @ExceptionHandler(org.springframework.web.bind.MethodArgumentNotValidException.class) public org.springframework.http.ProblemDetail handleValidationExceptions(org.springframework.web.bind.MethodArgumentNotValidException ex)
      Handles validation exceptions from @Valid annotations.
      Parameters:
      ex - the validation exception
      Returns:
      ProblemDetail response with 400 status and field errors

    • handleMethodArgumentTypeMismatchException

      @ExceptionHandler(org.springframework.web.method.annotation.MethodArgumentTypeMismatchException.class) public org.springframework.http.ProblemDetail handleMethodArgumentTypeMismatchException(org.springframework.web.method.annotation.MethodArgumentTypeMismatchException ex)
      Handles method argument type mismatch exceptions.
      Parameters:
      ex - the type mismatch exception
      Returns:
      ProblemDetail response with 400 status

    • handleHttpMessageNotReadableException

      @ExceptionHandler(org.springframework.http.converter.HttpMessageNotReadableException.class) public org.springframework.http.ProblemDetail handleHttpMessageNotReadableException(org.springframework.http.converter.HttpMessageNotReadableException ex)
      Handles malformed JSON request exceptions.
      Parameters:
      ex - the HTTP message not readable exception
      Returns:
      ProblemDetail response with 400 status

    • handleMissingServletRequestParameterException

      @ExceptionHandler(org.springframework.web.bind.MissingServletRequestParameterException.class) public org.springframework.http.ProblemDetail handleMissingServletRequestParameterException(org.springframework.web.bind.MissingServletRequestParameterException ex)
      Handles missing required request parameter exceptions.
      Parameters:
      ex - the missing parameter exception
      Returns:
      ProblemDetail response with 400 status

    • handleNoResourceFoundException

      @ExceptionHandler(org.springframework.web.servlet.resource.NoResourceFoundException.class) public org.springframework.http.ProblemDetail handleNoResourceFoundException(org.springframework.web.servlet.resource.NoResourceFoundException ex)
      Handles 404 Not Found exceptions.
      Parameters:
      ex - the no resource found exception
      Returns:
      ProblemDetail response with 404 status

    • handleHttpRequestMethodNotSupportedException

      @ExceptionHandler(org.springframework.web.HttpRequestMethodNotSupportedException.class) public org.springframework.http.ProblemDetail handleHttpRequestMethodNotSupportedException(org.springframework.web.HttpRequestMethodNotSupportedException ex)
      Handles HTTP method not supported exceptions.
      Parameters:
      ex - the method not supported exception
      Returns:
      ProblemDetail response with 405 status

    • handleHttpMediaTypeNotSupportedException

      @ExceptionHandler(org.springframework.web.HttpMediaTypeNotSupportedException.class) public org.springframework.http.ProblemDetail handleHttpMediaTypeNotSupportedException(org.springframework.web.HttpMediaTypeNotSupportedException ex)
      Handles unsupported media type exceptions.
      Parameters:
      ex - the media type not supported exception
      Returns:
      ProblemDetail response with 415 status

    • handleNullPointerExceptions

      @ExceptionHandler(java.lang.NullPointerException.class) public org.springframework.http.ProblemDetail handleNullPointerExceptions(NullPointerException ex)
      Handles null pointer exceptions.
      Parameters:
      ex - the null pointer exception
      Returns:
      ProblemDetail response with 500 status

    • handleApiException

      @ExceptionHandler(ApiException.class) public org.springframework.http.ProblemDetail handleApiException(ApiException ex)
      Handles custom API exceptions.
      Parameters:
      ex - the API exception
      Returns:
      ProblemDetail response with the exception's status code