ControllerAdvice class

Marks a class as a controller advice within the JetLeaf framework, enabling centralized handling of cross-cutting web concerns such as:

Exception handling
Response modification
Pre/post-processing around controller method execution

A ControllerAdvice can apply globally to all controllers or be scoped to specific controllers, packages, or annotations.

Overview

JetLeaf scans all registered @ControllerAdvice declarations at runtime and associates them with eligible controllers based on their scoping attributes. Advice methods within these classes can intercept controller invocations to provide reusable, declarative behavior.

Example: Global Advice

@ControllerAdvice()
class GlobalExceptionHandler {
  void handleException(ServerHttpRequest request, ServerHttpResponse response, Exception ex) {
    // Handle exceptions for all controllers
    response.setStatus(HttpStatus.INTERNAL_SERVER_ERROR);
    response.getBody().write('A server error occurred');
  }
}

Example: Targeted Advice

@ControllerAdvice(assignableTypes: [UserController, ClassType<CityController>()])
class UserCityExceptionHandler {
  void handleException(ServerHttpRequest request, ServerHttpResponse response, Exception ex) {
    // Handle only for UserController or CityController
  }
}

This advice applies only to UserController and CityController.

Scoping Attributes

Field	Description	Default
`assignableTypes`	Restricts advice to specific controller types or subtypes.	`[]` (global)
`basePackages`	Restricts advice to controllers within the given package names.	`[]`
`annotations`	Restricts advice to controllers annotated with one of the listed annotations.	`[]`

Design Notes

Inherits from Controller for consistency with JetLeaf’s annotation model.
Extends ReflectableAnnotation to support runtime reflection.
Implements EqualsAndHashCode for structural comparison and deduplication.
Internally resolved by ControllerAdviser during controller dispatch.

RestControllerAdvice → REST-specific advice for API controllers.
Controller → Marks classes eligible for web request mapping.

Inheritance

Object
Controller
ControllerAdvice

Implementers

RestControllerAdvice

Annotations

@Target.new({TargetKind.classType})

Constructors

ControllerAdvice({List<Object> assignableTypes = const [], List<String> basePackages = const [], List<Object> annotations = const []}): Marks a class as a controller advice within the JetLeaf framework, enabling centralized handling of cross-cutting web concerns such as:
const

Properties

annotations → List<Object>: Controller annotations that this advice applies to. Only controllers annotated with one of these will match.
final
annotationType → Type: Returns the annotation _type of this annotation.
no setteroverride
assignableTypes → List<Object>: Specific controller types this advice applies to. An empty list indicates global applicability.
final
basePackages → List<String>: Base packages that this advice applies to. Controllers outside these packages are ignored.
final
hashCode → int: The hash code for this object.
no setterinherited
ignoreContextPath → bool: Whether to not include the context path from environment (if available) when accessing this controller.
finalinherited
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
value → String?: Base path for all endpoints in this controller
finalinherited

Methods

equalizedProperties() → List<Object?>: Mixin-style contract for value-based equality, hashCode, and toString.
override
equals(Object other) → bool: Checks whether the given object is logically equivalent to this annotation.
inherited
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
toString() → String: Returns a string representation of this annotation.
override

Operators

operator ==(Object other) → bool: The equality operator.
inherited