@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 with @ControllerAdvice
can be declared explicitly as Spring
beans or auto-detected via classpath scanning. All such beans are sorted via
AnnotationAwareOrderComparator
, i.e. based on
@Order
and
Ordered
, and applied in that order
at runtime. For handling exceptions, an @ExceptionHandler
will be
picked on the first advice with a matching exception handler method. For
model attributes and InitBinder
initialization, @ModelAttribute
and @InitBinder
methods will also 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 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 and so adding many selectors may negatively impact
performance and add complexity.
Controller
,
RestControllerAdvice
Modifier and Type | Optional Element and Description |
---|---|
java.lang.Class<? extends java.lang.annotation.Annotation>[] |
annotations
Array of annotations.
|
java.lang.Class<?>[] |
assignableTypes
Array of classes.
|
java.lang.Class<?>[] |
basePackageClasses
Type-safe alternative to
basePackages() for specifying the packages
in which to select controllers to be advised by the @ControllerAdvice
annotated class. |
java.lang.String[] |
basePackages
Array of base packages.
|
java.lang.String[] |
value
Alias for the
basePackages() attribute. |
@AliasFor(value="basePackages") public abstract java.lang.String[] value
basePackages()
attribute.
Allows for more concise annotation declarations e.g.:
@ControllerAdvice("org.my.pkg")
is equivalent to
@ControllerAdvice(basePackages="org.my.pkg")
.
basePackages()
@AliasFor(value="value") public abstract java.lang.String[] basePackages
Controllers that belong to those base packages or sub-packages thereof
will be included, e.g.: @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 java.lang.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 java.lang.Class<?>[] assignableTypes
Controllers that are assignable to at least one of the given types
will be advised by the @ControllerAdvice
annotated class.
public abstract java.lang.Class<? extends java.lang.annotation.Annotation>[] annotations
Controllers that are annotated with at least one of the supplied annotations
will be advised by the @ControllerAdvice
annotated class.
Consider creating a custom composed annotation or use a predefined one,
like @RestController
.