@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 @Order
semantics 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 such as annotations()
,
basePackageClasses()
, and basePackages()
(or its alias
value()
) to define a more narrow subset of targeted controllers.
If multiple selectors are declared, 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.
Modifier and Type | Optional Element and Description |
---|---|
Class<? extends Annotation>[] |
annotations
Array of annotations.
|
Class<?>[] |
assignableTypes
Array of classes.
|
Class<?>[] |
basePackageClasses
Type-safe alternative to
value() for specifying the packages
to select Controllers to be assisted 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 e.g.:
@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, 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 Class<?>[] basePackageClasses
value()
for specifying the packages
to select Controllers to be assisted 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 assisted by the @ControllerAdvice
annotated class.
public abstract Class<? extends Annotation>[] annotations
Controllers that are annotated with this/one of those annotation(s)
will be assisted by the @ControllerAdvice
annotated class.
Consider creating a special annotation or use a predefined one,
like @RestController
.