diff --git a/spring-web/src/main/java/org/springframework/web/bind/annotation/ControllerAdvice.java b/spring-web/src/main/java/org/springframework/web/bind/annotation/ControllerAdvice.java index 8ec24a65ea..b88fb5ccae 100644 --- a/spring-web/src/main/java/org/springframework/web/bind/annotation/ControllerAdvice.java +++ b/spring-web/src/main/java/org/springframework/web/bind/annotation/ControllerAdvice.java @@ -26,7 +26,6 @@ import java.lang.annotation.Target; import org.springframework.core.annotation.AliasFor; import org.springframework.stereotype.Component; - /** * Specialization of {@link Component @Component} for classes that declare * {@link ExceptionHandler @ExceptionHandler}, {@link InitBinder @InitBinder}, or @@ -39,10 +38,17 @@ import org.springframework.stereotype.Component; * AnnotationAwareOrderComparator}, i.e. based on * {@link org.springframework.core.annotation.Order @Order} and * {@link org.springframework.core.Ordered Ordered}, and applied in that order - * at runtime. For handling exceptions the first {@code @ExceptionHandler} to - * match the exception is used. For model attributes and {@code InitBinder} - * initialization, {@code @ModelAttribute} and {@code @InitBinder} methods will - * also follow {@code @ControllerAdvice} order. + * at runtime. For handling exceptions, an {@code @ExceptionHandler} will be + * picked on the first advice with a matching exception handler method. For + * model attributes and {@code InitBinder} initialization, {@code @ModelAttribute} + * and {@code @InitBinder} methods will also follow {@code @ControllerAdvice} order. + * + *

Note: For {@code @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 to a 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 {@code @ControllerAdvice} apply globally to * all Controllers. Use selectors {@link #annotations()}, diff --git a/src/docs/asciidoc/web/webmvc.adoc b/src/docs/asciidoc/web/webmvc.adoc index b799d95bbf..28afae6805 100644 --- a/src/docs/asciidoc/web/webmvc.adoc +++ b/src/docs/asciidoc/web/webmvc.adoc @@ -209,7 +209,6 @@ If an application context hierarchy is not required, applications may configure - [[mvc-servlet-special-bean-types]] === Special Bean Types [.small]#<># @@ -575,7 +574,7 @@ view technologies. ==== Redirect The special `redirect:` prefix in a view name allows you to perform a redirect. The -`UrlBasedViewResolver` (and sub-classes) will recognize this as a special indication that a +`UrlBasedViewResolver` (and subclasses) will recognize this as a special indication that a redirect is needed. The rest of the view name will be treated as the redirect URL. The net effect is the same as if the controller had returned a `RedirectView`, but now @@ -592,7 +591,7 @@ value takes precedence over the response status set by `RedirectView`. ==== Forward It is also possible to use a special `forward:` prefix for view names that are -ultimately resolved by `UrlBasedViewResolver` and sub-classes. This creates an +ultimately resolved by `UrlBasedViewResolver` and subclasses. This creates an `InternalResourceView` which does a `RequestDispatcher.forward()`. Therefore, this prefix is not useful with `InternalResourceViewResolver` and `InternalResourceView` (for JSPs) but it can be helpful if using another view @@ -1351,7 +1350,6 @@ default it is set to `true`. [TIP] ==== - The MVC Java config and the MVC namespace both provide options for enabling the use of matrix variables. @@ -2593,7 +2591,6 @@ for more details. [TIP] ==== - What happens when a model attribute name is not explicitly specified? In such cases a default name is assigned to the model attribute based on its type. For example if the method returns an object of type `Account`, the default name used is "account". You can @@ -2739,7 +2736,7 @@ You can also expand and encode using individual URI components: .encode(); ---- -In a Servlet environment the `ServletUriComponentsBuilder` sub-class provides static +In a Servlet environment the `ServletUriComponentsBuilder` subclass provides static factory methods to copy available URL information from a Servlet requests: [source,java,indent=0] @@ -2962,7 +2959,7 @@ error content to the body of the response. You can do that with `@ExceptionHandler` methods. When declared within a controller such methods apply to exceptions raised by `@RequestMapping` methods of that controller (or -any of its sub-classes). You can also declare an `@ExceptionHandler` method within an +any of its subclasses). You can also declare an `@ExceptionHandler` method within an `@ControllerAdvice` class in which case it handles exceptions from `@RequestMapping` methods from many controllers. Below is an example of a controller-local `@ExceptionHandler` method: @@ -2989,6 +2986,16 @@ is thrown that matches one of the types in the list, then the method annotated w matching `@ExceptionHandler` will be invoked. If the annotation value is not set then the exception types listed as method arguments are used. +[TIP] +==== +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 +controller or advice bean. However, a cause match on a higher-priority `@ControllerAdvice` +will still be preferred to a any match (whether root or cause level) on a lower-priority +advice bean. As a consequence, when using a multi-advice arrangement, please declare your +primary root exception mappings on a prioritized advice bean with a corresponding order! +==== + Much like standard controller methods annotated with a `@RequestMapping` annotation, the method arguments and return values of `@ExceptionHandler` methods can be flexible. For example, the `HttpServletRequest` can be accessed in Servlet environments. The return @@ -3341,7 +3348,7 @@ the response. [[mvc-ann-async-sse]] === Server-Sent Events -`SseEmitter` is a sub-class of `ResponseBodyEmitter` providing support for +`SseEmitter` is a subclass of `ResponseBodyEmitter` providing support for http://www.w3.org/TR/eventsource/[Server-Sent Events]. Server-sent events is a just another variation on the same "HTTP Streaming" technique except events pushed from the server are formatted according to @@ -3696,12 +3703,10 @@ then resolved into the `/WEB-INF/jsp/registration.jsp` view by the [TIP] ==== - You do not need to define a `DefaultRequestToViewNameTranslator` bean explicitly. If you like the default settings of the `DefaultRequestToViewNameTranslator`, you can rely on the Spring Web MVC `DispatcherServlet` to instantiate an instance of this class if one is not explicitly configured. - ==== Of course, if you need to change the default settings, then you do need to configure