root
/
spring-framework
mirror of https://github.com/spring-projects/spring-framework.git
1
0
Fork 0
Code Issues Actions 8 Packages Projects Releases Wiki Activity

[doc] Update Spring MVC exception handling content 

Issue: SPR-16394
This commit is contained in:
Rossen Stoyanchev 2018-01-31 23:03:10 -05:00
parent d9a93f44ae
commit 0ded239453
3 changed files with 243 additions and 276 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

86
spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/support/DefaultHandlerExceptionResolver.java
View File

@ -1,5 +1,5 @@
/*
* Copyright 2002-2016 the original author or authors.
* Copyright 2002-2018 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@ -60,22 +60,84 @@ import org.springframework.web.servlet.handler.AbstractHandlerExceptionResolver;
* <p>This exception resolver is enabled by default in the common Spring
* {@link org.springframework.web.servlet.DispatcherServlet}.
*
* <p>
* <table>
* <caption>Supported Exceptions</caption>
* <thead>
* <tr>
* <th class="colFirst">Exception</th>
* <th class="colLast">HTTP Status Code</th>
* </tr>
* </thead>
* <tbody>
* <tr class="altColor">
* <td><p>HttpRequestMethodNotSupportedException</p></td>
* <td><p>405 (SC_METHOD_NOT_ALLOWED)</p></td>
* </tr>
* <tr class="rowColor">
* <td><p>HttpMediaTypeNotSupportedException</p></td>
* <td><p>415 (SC_UNSUPPORTED_MEDIA_TYPE)</p></td>
* </tr>
* <tr class="altColor">
* <td><p>HttpMediaTypeNotAcceptableException</p></td>
* <td><p>406 (SC_NOT_ACCEPTABLE)</p></td>
* </tr>
* <tr class="rowColor">
* <td><p>MissingPathVariableException</p></td>
* <td><p>500 (SC_INTERNAL_SERVER_ERROR)</p></td>
* </tr>
* <tr class="altColor">
* <td><p>MissingServletRequestParameterException</p></td>
* <td><p>500 (SC_INTERNAL_SERVER_ERROR)</p></td>
* </tr>
* <tr class="rowColor">
* <td><p>ServletRequestBindingException</p></td>
* <td><p>400 (SC_BAD_REQUEST)</p></td>
* </tr>
* <tr class="altColor">
* <td><p>ConversionNotSupportedException</p></td>
* <td><p>500 (SC_INTERNAL_SERVER_ERROR)</p></td>
* </tr>
* <tr class="rowColor">
* <td><p>TypeMismatchException</p></td>
* <td><p>400 (SC_BAD_REQUEST)</p></td>
* </tr>
* <tr class="altColor">
* <td><p>HttpMessageNotReadableException</p></td>
* <td><p>400 (SC_BAD_REQUEST)</p></td>
* </tr>
* <tr class="rowColor">
* <td><p>HttpMessageNotWritableException</p></td>
* <td><p>500 (SC_INTERNAL_SERVER_ERROR)</p></td>
* </tr>
* <tr class="altColor">
* <td><p>MethodArgumentNotValidException</p></td>
* <td><p>400 (SC_BAD_REQUEST)</p></td>
* </tr>
* <tr class="rowColor">
* <td><p>MissingServletRequestPartException</p></td>
* <td><p>400 (SC_BAD_REQUEST)</p></td>
* </tr>
* <tr class="altColor">
* <td><p>BindException</p></td>
* <td><p>400 (SC_BAD_REQUEST)</p></td>
* </tr>
* <tr class="rowColor">
* <td><p>NoHandlerFoundException</p></td>
* <td><p>400 (SC_NOT_FOUND)</p></td>
* </tr>
* <tr class="altColor">
* <td><p>AsyncRequestTimeoutException</p></td>
* <td><p>503 (SC_SERVICE_UNAVAILABLE)</p></td>
* </tr>
* </tbody>
* </table>
*
* @author Arjen Poutsma
* @author Rossen Stoyanchev
* @author Juergen Hoeller
* @since 3.0
* @see org.springframework.web.servlet.mvc.method.annotation.ResponseEntityExceptionHandler
* @see #handleHttpRequestMethodNotSupported
* @see #handleHttpMediaTypeNotSupported
* @see #handleMissingServletRequestParameter
* @see #handleServletRequestBindingException
* @see #handleTypeMismatch
* @see #handleHttpMessageNotReadable
* @see #handleHttpMessageNotWritable
* @see #handleMethodArgumentNotValidException
* @see #handleMissingServletRequestParameter
* @see #handleMissingServletRequestPartException
* @see #handleBindException
*/
public class DefaultHandlerExceptionResolver extends AbstractHandlerExceptionResolver {

4
spring-webmvc/src/main/java/org/springframework/web/servlet/tags/form/FormTag.java
View File

@ -59,7 +59,7 @@ import org.springframework.web.util.UriUtils;
* <td><p>acceptCharset</p></td>
* <td><p>false</p></td>
* <td><p>true</p></td>
* <td><p><p>Specifies the list of character encodings for input data that is accepted
* <td><p>Specifies the list of character encodings for input data that is accepted
* by the server processing this form. The value is a space- and/or comma-delimited
* list of charset values. The client must interpret this list as an exclusive-or
* list, i.e., the server is able to accept any single character encoding per
@ -69,7 +69,7 @@ import org.springframework.web.util.UriUtils;
* <td><p>action</p></td>
* <td><p>false</p></td>
* <td><p>true</p></td>
* <td><p><p>HTML Required Attribute</p></td>
* <td><p>HTML Required Attribute</p></td>
* </tr>
* <tr class="altColor">
* <td><p>cssClass</p></td>

429
src/docs/asciidoc/web/webmvc.adoc
View File

@ -506,6 +506,109 @@ declare it as an <<mvc-ann-controller-advice>> bean or configure it directly on
[[mvc-exceptionhandlers]]
=== Exception Resolution
If an exception occurs during the mapping or the invocation of a request handler (e.g. an
`@Controller`), the `DispatcherServlet` delegates to a chain of `HandlerExceptionResolver`
beans to try and resolve the exception and to provide alternative handling for it, which
typically means preparing an error response whether an HTML error page, an error status,
or both.
The table below lists the available `HandlerExceptionResolver` implementations:
[cols="1,2", options="header"]
.HandlerExceptionResolver implementations
|===
| HandlerExceptionResolver| Description
| `SimpleMappingExceptionResolver`
| A mapping between exception class names and error view names. Useful for rendering
error pages in a browser application.
| {api-spring-framework}/web/servlet/mvc/support/DefaultHandlerExceptionResolver.html[DefaultHandlerExceptionResolver]
| Resolves exceptions raised by Spring MVC and maps them to HTTP status codes.
Also see alternative `ResponseEntityExceptionHandler` and <<mvc-ann-rest-exceptions>>.
| `ResponseStatusExceptionResolver`
| Resolves exceptions with the `@ResponseStatus` annotation and maps them to HTTP status
codes based on the value in the annotation.
| `ExceptionHandlerExceptionResolver`
| Resolves exceptions by invoking an `@ExceptionHandler` method in an `@Controller` or an
`@ControllerAdvice` class. See <<mvc-ann-exceptionhandler>>.
|===
[[mvc-excetionhandlers-handling]]
==== Handling
You chain exception resolvers by declaring more than one exception resolver beans and,
if necessary, setting the `order` property to specify ordering. Remember, the higher the
order property, the later the exception resolver is positioned in the chain.
The contract of `HandlerExceptionResolver` specifies that it __can__ return:
* `ModelAndView` that points to an error view.
* Empty `ModelAndView` if the exception was handled within the resolver.
* `null` if the exception remains unresolved, for subsequent resolvers to try; if the
exception remains unresolved by any resolver, it is re-thrown and left to propagate to
the Servlet container.
To configure exception handling is as simple as adding `HandlerExceptionResolver` beans
to your Spring configuration. The <<mvc-config>> automatically declares built-in
resolvers for default Spring MVC exceptions, for `@ResponseStatus` annotated exceptions,
and for support of `@ExceptionHandler` methods. You can customize that list or replace it.
[[mvc-ann-customer-servlet-container-error-page]]
==== Container error page
If an exception remains unresolved by any `HandlerExceptionResolver` and is therefore
left to propagate, or if the response status is set to an error status (i.e. 4xx, 5xx),
Servlet containers may render a default error page in HTML. To customize the default
error page of the container, you can declare an error page mapping in `web.xml`:
[source,xml,indent=0]
[subs="verbatim,quotes"]
----
<error-page>
<location>/error</location>
</error-page>
----
Given the above, when an exception bubbles up, or the response has an error status, the
Servlet container makes an ERROR dispatch within the container to the configured URL
(e.g. "/error"). This is then processed by the `DispatcherServlet`, possibly mapping it
to an `@Controller` which could be implemented to return an error view name with a model
or to render a JSON response as shown below:
[source,java,indent=0]
[subs="verbatim,quotes"]
----
@RestController
public class ErrorController {
@RequestMapping(path = "/error")
public Map<String, Object> handle(HttpServletRequest request) {
Map<String, Object> map = new HashMap<String, Object>();
map.put("status", request.getAttribute("javax.servlet.error.status_code"));
map.put("reason", request.getAttribute("javax.servlet.error.message"));
return map;
}
}
----
[TIP]
====
The Servlet API does not provide a way to create error page mappings in Java. You can
however use both an `WebApplicationInitializer` and a minimal `web.xml`.
====
[[mvc-viewresolver]]
=== View Resolution
[.small]#<<web-reactive.adoc#webflux-viewresolution,Same in Spring WebFlux>>#
@ -515,7 +618,7 @@ models in a browser without tying you to a specific view technology. `ViewResolv
provides a mapping between view names and actual views. `View` addresses the preparation
of data before handing over to a specific view technology.
This table below provides more details on the `ViewResolver` hierarchy:
The table below provides more details on the `ViewResolver` hierarchy:
[[mvc-view-resolvers-tbl]]
.ViewResolver implementations
@ -575,9 +678,9 @@ The contract of a `ViewResolver` specifies that it __can__ return null to indica
view could not be found. However in the case of JSPs, and `InternalResourceViewResolver`,
the only way to figure out if a JSP exists is to perform a dispatch through
`RequestDispatcher`. Therefore an `InternalResourceViewResolver` must always be configured
to be last in the overal order of view resolvers.
to be last in the overall order of view resolvers.
To configure view resolution is as simple as adding a `ViewResolver` beans to your Spring
To configure view resolution is as simple as adding `ViewResolver` beans to your Spring
configuration. The <<mvc-config>> provides provides a dedicated configuration API for
<<mvc-config-view-resolvers>> and also for adding logic-less
<<mvc-config-view-controller,View Controllers>> which are useful for HTML template
@ -2666,6 +2769,67 @@ controller-specific ``Formatter``'s:
[[mvc-ann-exceptionhandler]]
=== Exception Methods
`@ExceptionHandler` methods in an `@Controller` can be used to handle exceptions during
request handling from the same controller. An `@ExceptionHandler` can also be declared
in an <<mvc-ann-controller-advice,@ControllerAdvice class>> to apply across controllers.
Support for `@ExceptionHandler` methods in Spring MVC is provided through the
<<mvc-exceptionhandlers,HandlerExceptionResolver>> mechanism.
Below is an example:
[source,java,indent=0]
[subs="verbatim,quotes"]
----
@Controller
public class SimpleController {
// ...
@ExceptionHandler(IOException.class)
public ResponseEntity<String> handle(IOException ex) {
// ...
}
}
----
The value of the `@ExceptionHandler` annotation can be set to an array of Exception types
to match to. Or if the annotation value is not set, then the exception type declared in
the method signature is used instead. `@ExceptionHandler` methods can declare other
arguments too, e.g. the `HttpServletRequest`. The return value type can be a `String`,
which is interpreted as a view name, a `ModelAndView` object, a `ResponseEntity`, or you
can also add the `@ResponseBody` annotation.
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!
[[mvc-ann-rest-exceptions]]
==== REST API exceptions
A common requirement for REST services is to include error details in the body of the
response. The Spring Framework does not automatically do this because the representation
of error details in the response body is application specific. However a
`@RestController` may use `@ExceptionHandler` methods with a `ResponseEntity` return
value to set the status and the body of the response. Such methods may also be declared
in `@ControllerAdvice` classes to apply them globally.
Applications that implement global exception handling with error details in the response
body should consider extending
{api-spring-framework}/web/servlet/mvc/method/annotation/ResponseEntityExceptionHandler.html[ResponseEntityExceptionHandler]
which provides handling for exceptions that Spring MVC raises along with hooks to
customize the response body. To make use of this, create a sub-class of
`ResponseEntityExceptionHandler`, annotate with `@ControllerAdvice`, override the
necessary methods, and declare it as a Spring bean.
[[mvc-ann-controller-advice]]
=== Controller Advice
[.small]#<<web-reactive.adoc#webflux-ann-controller-advice,Same in Spring WebFlux>>#
@ -2929,265 +3093,6 @@ in order to use a specific instance of `MvcUriComponentsBuilder` with a custom b
[[mvc-exceptionhandlers]]
== Exception Handling
[[mvc-exceptionhandlers-overview]]
=== Overview
Spring `HandlerExceptionResolver` implementations deal with unexpected exceptions that
occur during controller execution. A `HandlerExceptionResolver` somewhat resembles the
exception mappings you can define in the web application descriptor `web.xml`. However,
they provide a more flexible way to do so. For example they provide information about
which handler was executing when the exception was thrown. Furthermore, a programmatic
way of handling exceptions gives you more options for responding appropriately before
the request is forwarded to another URL (the same end result as when you use the Servlet
specific exception mappings).
Besides implementing the `HandlerExceptionResolver` interface, which is only a matter of
implementing the `resolveException(Exception, Handler)` method and returning a
`ModelAndView`, you may also use the provided `SimpleMappingExceptionResolver` or create
`@ExceptionHandler` methods. The `SimpleMappingExceptionResolver` enables you to take
the class name of any exception that might be thrown and map it to a view name. This is
functionally equivalent to the exception mapping feature from the Servlet API, but it is
also possible to implement more finely grained mappings of exceptions from different
handlers. The `@ExceptionHandler` annotation on the other hand can be used on methods
that should be invoked to handle an exception. Such methods may be defined locally
within an `@Controller` or may apply to many `@Controller` classes when defined within an
`@ControllerAdvice` class. The following sections explain this in more detail.
[[mvc-ann-exceptionhandler]]
=== @ExceptionHandler
The `HandlerExceptionResolver` interface and the `SimpleMappingExceptionResolver`
implementations allow you to map Exceptions to specific views declaratively along with
some optional Java logic before forwarding to those views. However, in some cases,
especially when relying on `@ResponseBody` methods rather than on view resolution, it
may be more convenient to directly set the status of the response and optionally write
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 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:
[source,java,indent=0]
[subs="verbatim,quotes"]
----
@Controller
public class SimpleController {
// @RequestMapping methods omitted ...
@ExceptionHandler(IOException.class)
public ResponseEntity<String> handleIOException(IOException ex) {
// prepare responseEntity
return responseEntity;
}
}
----
The `@ExceptionHandler` value can be set to an array of Exception types. If an exception
is thrown that matches one of the types in the list, then the method annotated with the
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
type can be a `String`, which is interpreted as a view name, a `ModelAndView` object,
a `ResponseEntity`, or you can also add the `@ResponseBody` to have the method return
value converted with message converters and written to the response stream.
[[mvc-ann-rest-spring-mvc-exceptions]]
=== Framework exceptions
Spring MVC may raise a number of exceptions while processing a request. The
`SimpleMappingExceptionResolver` can easily map any exception to a default error view as
needed. However, when working with clients that interpret responses in an automated way
you will want to set specific status code on the response. Depending on the exception
raised the status code may indicate a client error (4xx) or a server error (5xx).
The `DefaultHandlerExceptionResolver` translates Spring MVC exceptions to specific error
status codes. It is registered by default with the MVC namespace, the MVC Java config,
and also by the `DispatcherServlet` (i.e. when not using the MVC namespace or Java
config). Listed below are some of the exceptions handled by this resolver and the
corresponding status codes:
|===
| Exception| HTTP Status Code
| `BindException`
| 400 (Bad Request)
| `ConversionNotSupportedException`
| 500 (Internal Server Error)
| `HttpMediaTypeNotAcceptableException`
| 406 (Not Acceptable)
| `HttpMediaTypeNotSupportedException`
| 415 (Unsupported Media Type)
| `HttpMessageNotReadableException`
| 400 (Bad Request)
| `HttpMessageNotWritableException`
| 500 (Internal Server Error)
| `HttpRequestMethodNotSupportedException`
| 405 (Method Not Allowed)
| `MethodArgumentNotValidException`
| 400 (Bad Request)
| `MissingPathVariableException`
| 500 (Internal Server Error)
| `MissingServletRequestParameterException`
| 400 (Bad Request)
| `MissingServletRequestPartException`
| 400 (Bad Request)
| `NoHandlerFoundException`
| 404 (Not Found)
| `NoSuchRequestHandlingMethodException`
| 404 (Not Found)
| `TypeMismatchException`
| 400 (Bad Request)
|===
The `DefaultHandlerExceptionResolver` works transparently by setting the status of the
response. However, it stops short of writing any error content to the body of the
response while your application may need to add developer-friendly content to every
error response for example when providing a REST API. You can prepare a `ModelAndView`
and render error content through view resolution -- i.e. by configuring a
`ContentNegotiatingViewResolver`, `MappingJackson2JsonView`, and so on. However, you may
prefer to use `@ExceptionHandler` methods instead.
If you prefer to write error content via `@ExceptionHandler` methods you can extend
`ResponseEntityExceptionHandler` instead. This is a convenient base for
`@ControllerAdvice` classes providing an `@ExceptionHandler` method to handle standard
Spring MVC exceptions and return `ResponseEntity`. That allows you to customize the
response and write error content with message converters. See the
`ResponseEntityExceptionHandler` javadocs for more details.
[[mvc-ann-rest-exceptions]]
=== REST API exceptions
An `@RestController` may use `@ExceptionHandler` methods that return a
`ResponseEntity` to provide both a response status and error details in the body
of the response. Such methods may also be added to `@ControllerAdvice`
classes for exception handling across a subset or all controllers.
A common requirement is to include error details in the body of the response.
Spring does not automatically do this (although Spring Boot does) because the
representation of error details in the response body is application specific.
Applications that wish to implement a global exception handling strategy with
error details in the response body should consider extending the abstract base
class `ResponseEntityExceptionHandler` which provides handling for the exceptions
that Spring MVC raises and provides hooks to customize the response body as
well as to handle other exceptions. Simply declare the extension class as a
Spring bean and annotate it with `@ControllerAdvice`. For more details see
See `ResponseEntityExceptionHandler`.
[[mvc-ann-annotated-exceptions]]
=== Annotated Exception
A business exception can be annotated with `@ResponseStatus`. When the exception is
raised, the `ResponseStatusExceptionResolver` handles it by setting the status of the
response accordingly. By default the `DispatcherServlet` registers the
`ResponseStatusExceptionResolver` and it is available for use.
[[mvc-ann-customer-servlet-container-error-page]]
=== Container error page
When the status of the response is set to an error status code and the body of the
response is empty, Servlet containers commonly render an HTML formatted error page. To
customize the default error page of the container, you can declare an `<error-page>`
element in `web.xml`. Up until Servlet 3, that element had to be mapped to a specific
status code or exception type. Starting with Servlet 3 an error page does not need to be
mapped, which effectively means the specified location customizes the default Servlet
container error page.
[source,xml,indent=0]
[subs="verbatim,quotes"]
----
<error-page>
<location>/error</location>
</error-page>
----
Note that the actual location for the error page can be a JSP page or some other URL
within the container including one handled through an `@Controller` method:
When writing error information, the status code and the error message set on the
`HttpServletResponse` can be accessed through request attributes in a controller:
[source,java,indent=0]
[subs="verbatim,quotes"]
----
@Controller
public class ErrorController {
@RequestMapping(path = "/error", produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
@ResponseBody
public Map<String, Object> handle(HttpServletRequest request) {
Map<String, Object> map = new HashMap<String, Object>();
map.put("status", request.getAttribute("javax.servlet.error.status_code"));
map.put("reason", request.getAttribute("javax.servlet.error.message"));
return map;
}
}
----
or in a JSP:
[source,xml,indent=0]
[subs="verbatim,quotes"]
----
<%@ page contentType="application/json" pageEncoding="UTF-8"%>
{
status:<%=request.getAttribute("javax.servlet.error.status_code") %>,
reason:<%=request.getAttribute("javax.servlet.error.message") %>
}
----
[[mvc-ann-async]]
== Async Requests
[.small]#<<mvc-ann-async-vs-webflux,Compared to WebFlux>>#