Update docs for ControllerAdvice

In 5.3 it became possible to handle exceptions from any handler through
ExceptionHandler's in a ControllerAdvice class, but this is not
mentioned in the docs

See gh-22619, gh-27338
This commit is contained in:
Rossen Stoyanchev 2021-09-24 15:57:15 +01:00
parent e29cfa3501
commit 93f8706dd3
1 changed files with 16 additions and 18 deletions

View File

@ -4021,27 +4021,25 @@ necessary methods, and declare it as a Spring bean.
=== Controller Advice === Controller Advice
[.small]#<<web-reactive.adoc#webflux-ann-controller-advice, WebFlux>># [.small]#<<web-reactive.adoc#webflux-ann-controller-advice, WebFlux>>#
Typically `@ExceptionHandler`, `@InitBinder`, and `@ModelAttribute` methods apply within `@ExceptionHandler`, `@InitBinder`, and `@ModelAttribute` methods apply only to the
the `@Controller` class (or class hierarchy) in which they are declared. If you want such `@Controller` class, or class hierarchy, in which they are declared. If, instead, they
methods to apply more globally (across controllers), you can declare them in a class are declared in an `@ControllerAdvice` or `@RestControllerAdvice` class, then they apply
annotated with `@ControllerAdvice` or `@RestControllerAdvice`. to any controller. Moreover, as of 5.3, `@ExceptionHandler` methods in `@ControllerAdvice`
can be used to handle exceptions from any `@Controller` or any other handler.
`@ControllerAdvice` is annotated with `@Component`, which means such classes can be `@ControllerAdvice` is meta-annotated with `@Component` and therefore can be registered as
registered as Spring beans through <<core.adoc#beans-java-instantiating-container-scan, a Spring bean through <<core.adoc#beans-java-instantiating-container-scan,
component scanning>>. `@RestControllerAdvice` is a composed annotation that is annotated component scanning>>. `@RestControllerAdvice` is meta-annotated with `@ControllerAdvice`
with both `@ControllerAdvice` and `@ResponseBody`, which essentially means and `@ResponseBody`, and that means `@ExceptionHandler` methods will have their return
`@ExceptionHandler` methods are rendered to the response body through message conversion value rendered via response body message conversion, rather than via HTML views.
(versus view resolution or template rendering).
On startup, the infrastructure classes for `@RequestMapping` and `@ExceptionHandler` On startup, `RequestMappingHandlerMapping` and `ExceptionHandlerExceptionResolver` detect
methods detect Spring beans annotated with `@ControllerAdvice` and then apply their controller advice beans and apply them at runtime. Global `@ExceptionHandler` methods,
methods at runtime. Global `@ExceptionHandler` methods (from a `@ControllerAdvice`) are from an `@ControllerAdvice`, are applied _after_ local ones, from the `@Controller`.
applied _after_ local ones (from the `@Controller`). By contrast, global `@ModelAttribute` By contrast, global `@ModelAttribute` and `@InitBinder` methods are applied _before_ local ones.
and `@InitBinder` methods are applied _before_ local ones.
By default, `@ControllerAdvice` methods apply to every request (that is, all controllers), The `@ControllerAdvice` annotation has attributes that let you narrow the set of controllers
but you can narrow that down to a subset of controllers by using attributes on the and handlers that they apply to. For example:
annotation, as the following example shows:
[source,java,indent=0,subs="verbatim,quotes",role="primary"] [source,java,indent=0,subs="verbatim,quotes",role="primary"]
.Java .Java