ControllerExceptionHandler class

A centralized exception handler for JetLeaf web controllers, responsible for transforming framework-level and domain-specific exceptions into structured, framework-consistent View responses.

The ControllerExceptionHandler provides a declarative mechanism for handling HTTP and server-side exceptions via annotated methods using the `@ExceptionHandler` meta-annotation.
Each handler method corresponds to a specific subclass of HttpException or JetLeafException, ensuring graceful degradation and consistent error presentation at the controller layer.

Purpose

This class decouples exception handling logic from application controllers by providing prebuilt responses for the most common HTTP error conditions (e.g. 400 Bad Request, 403 Forbidden, 404 Not Found, 500 Internal Server Error), as well as JetLeaf-specific runtime exceptions.

It leverages ErrorPageUtils to render standardized error pages or JSON responses, preserving request metadata such as:

• the failing request path,
• contextual error identifiers (errorId),
• request attributes or diagnostic details, and
• retry and content negotiation hints (for Retry-After, etc.).

Integration

The handler is automatically discovered and registered by the JetLeaf web context during the controller dispatch phase. When a controller method throws a supported exception, the framework routes control to the matching @ExceptionHandler-annotated method.

Example

@RestController()
class UserController {
  final UserService service;

  UserController(this.service);

  @Get('/users/:id')
  Future<User> getUser(@PathVariable('id') String id) async {
    final user = await service.findById(id);
    if (user == null) {
      throw NotFoundException('User not found for ID: $id');
    }
    return user;
  }
}

When the above controller throws a NotFoundException, ControllerExceptionHandler.handleNotFoundException automatically generates a 404 response view using ErrorPageUtils.notFound.

Supported Exception Types

• BadRequestException
• UnauthorizedException
• ForbiddenException
• MethodNotAllowedException
• ConflictException
• PayloadTooLargeException
• UnsupportedMediaTypeException
• TooManyRequestsException
• RequestTimeoutException
• ServiceUnavailableException
• GatewayTimeoutException
• BadGatewayException
• NotFoundException
• HttpException (fallback handler)

Each exception handler ensures HTTP semantics compliance while allowing customization of error messages, retry delays, and diagnostic payloads.