@Target(value=TYPE) @Retention(value=RUNTIME) @Documented @Component public @interface ControllerAdvice
@Component
for classes that declare
@ExceptionHandler
, @InitBinder
, or
@ModelAttribute
methods to be shared across
multiple @Controller
classes.
Classes annotated with @ControllerAdvice
can be declared explicitly
as Spring beans or auto-detected via classpath scanning. All such beans are
sorted based on Ordered
semantics or
@Order
/
@Priority
declarations, with Ordered
semantics taking precedence over @Order
/ @Priority
declarations.
@ControllerAdvice
beans are then applied in that order at runtime.
Note, however, that @ControllerAdvice
beans that implement
PriorityOrdered
are not
given priority over @ControllerAdvice
beans that implement Ordered
.
In addition, Ordered
is not honored for scoped @ControllerAdvice
beans — for example if such a bean has been configured as a request-scoped
or session-scoped bean. For handling exceptions, an @ExceptionHandler
will be picked on the first advice with a matching exception handler method. For
model attributes and data binding initialization, @ModelAttribute
and
@InitBinder
methods will follow @ControllerAdvice
order.
Note: For @ExceptionHandler
methods, a root exception match will be
preferred to just matching a cause of the current exception, among the handler
methods of a particular advice bean. However, a cause match on a higher-priority
advice will still be preferred over any match (whether root or cause level)
on a lower-priority advice bean. As a consequence, please declare your primary
root exception mappings on a prioritized advice bean with a corresponding order.
By default, the methods in an @ControllerAdvice
apply globally to
all controllers. Use selectors such as annotations()
,
basePackageClasses()
, and basePackages()
(or its alias
value()
) to define a more narrow subset of targeted controllers.
If multiple selectors are declared, boolean OR
logic is applied, meaning
selected controllers should match at least one selector. Note that selector checks
are performed at runtime, so adding many selectors may negatively impact
performance and add complexity.
Controller
,
RestControllerAdvice
Modifier and Type | Optional Element and Description |
---|---|
Class<? extends Annotation>[] |
annotations
Array of annotation types.
|
Class<?>[] |
assignableTypes
Array of classes.
|
Class<?>[] |
basePackageClasses
Type-safe alternative to
basePackages() for specifying the packages
in which to select controllers to be advised by the @ControllerAdvice
annotated class. |
String[] |
basePackages
Array of base packages.
|
String[] |
value
Alias for the
basePackages() attribute. |
@AliasFor(value="basePackages") public abstract String[] value
basePackages()
attribute.
Allows for more concise annotation declarations — for example,
@ControllerAdvice("org.my.pkg")
is equivalent to
@ControllerAdvice(basePackages = "org.my.pkg")
.
basePackages()
@AliasFor(value="value") public abstract String[] basePackages
Controllers that belong to those base packages or sub-packages thereof
will be included — for example,
@ControllerAdvice(basePackages = "org.my.pkg")
or
@ControllerAdvice(basePackages = {"org.my.pkg", "org.my.other.pkg"})
.
value()
is an alias for this attribute, simply allowing for
more concise use of the annotation.
Also consider using basePackageClasses()
as a type-safe
alternative to String-based package names.
public abstract Class<?>[] basePackageClasses
basePackages()
for specifying the packages
in which to select controllers to be advised by the @ControllerAdvice
annotated class.
Consider creating a special no-op marker class or interface in each package that serves no purpose other than being referenced by this attribute.
public abstract Class<?>[] assignableTypes
Controllers that are assignable to at least one of the given types
will be advised by the @ControllerAdvice
annotated class.
public abstract Class<? extends Annotation>[] annotations
Controllers that are annotated with at least one of the supplied annotation
types will be advised by the @ControllerAdvice
annotated class.
Consider creating a custom composed annotation or use a predefined one,
like @RestController
.