Polish standard Spring MVC exception handling

Rename ExceptionHandlerSupport to ResponseEntityExceptionHandler and
emphasize the contrast to DefaultHandlerExceptionResovler -- i.e.
one returns a ResponseEntity and relies on message converters while
the other returns a ModelAndView and relies on view resolution.

Issue: SPR-9290

spring-web/src/main/java/org/springframework/web/HttpRequestMethodNotSupportedException.java

@@ -17,8 +17,13 @@
 package org.springframework.web;
 
 import java.util.Collection;
+import java.util.HashSet;
+import java.util.Set;
+
 import javax.servlet.ServletException;
 
+import org.springframework.http.HttpMethod;
+
 /**
  * Exception thrown when a request handler does not support a
  * specific request method.
@@ -95,4 +100,15 @@ public class HttpRequestMethodNotSupportedException extends ServletException {
 		return this.supportedMethods;
 	}
 
+	/**
+	 * Return the actually supported HTTP methods, if known, as {@link HttpMethod} instances.
+	 */
+	public Set<HttpMethod> getSupportedHttpMethods() {
+		Set<HttpMethod> supportedMethods = new HashSet<HttpMethod>();
+		for (String value : this.supportedMethods) {
+			supportedMethods.add(HttpMethod.valueOf(value));
+		}
+		return supportedMethods;
+	}
+
 }

spring-web/src/main/java/org/springframework/web/bind/annotation/ControllerAdvice.java

@@ -32,7 +32,7 @@ import org.springframework.stereotype.Component;
  *
  * <p>It is typically used to define {@link ExceptionHandler @ExceptionHandler},
  * {@link InitBinder @InitBinder}, and {@link ModelAttribute @ModelAttribute}
- * methods that apply across controller class hierarchies.
+ * methods that apply to all {@link RequestMapping @RequestMapping} methods.
  *
  * @author Rossen Stoyanchev
  * @since 3.2

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

@@ -60,7 +60,7 @@ import org.springframework.web.servlet.mvc.multiaction.NoSuchRequestHandlingMeth
  * @author Rossen Stoyanchev
  * @since 3.0
  *
- * @see org.springframework.web.servlet.mvc.method.annotation.ExceptionHandlerSupport
+ * @see org.springframework.web.servlet.mvc.method.annotation.ResponseEntityExceptionHandler
  * @see #handleNoSuchRequestHandlingMethod
  * @see #handleHttpRequestMethodNotSupported
  * @see #handleHttpMediaTypeNotSupported

spring-webmvc/src/test/java/org/springframework/web/servlet/mvc/method/annotation/ExceptionHandlerSupportTests.java → spring-webmvc/src/test/java/org/springframework/web/servlet/mvc/method/annotation/ResponseEntityExceptionHandlerTests.java

@@ -18,7 +18,6 @@ package org.springframework.web.servlet.mvc.method.annotation;
 import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.assertTrue;
 
-import java.io.UnsupportedEncodingException;
 import java.lang.reflect.Method;
 import java.util.Arrays;
 import java.util.EnumSet;
@@ -56,13 +55,13 @@ import org.springframework.web.servlet.mvc.multiaction.NoSuchRequestHandlingMeth
 import org.springframework.web.servlet.mvc.support.DefaultHandlerExceptionResolver;
 
 /**
- * Test fixture for {@link ExceptionHandlerSupport}.
+ * Test fixture for {@link ResponseEntityExceptionHandler}.
  *
  * @author Rossen Stoyanchev
  */
-public class ExceptionHandlerSupportTests {
+public class ResponseEntityExceptionHandlerTests {
 
-	private ExceptionHandlerSupport exceptionHandlerSupport;
+	private ResponseEntityExceptionHandler exceptionHandlerSupport;
 
 	private DefaultHandlerExceptionResolver defaultExceptionResolver;
 
@@ -86,7 +85,7 @@ public class ExceptionHandlerSupportTests {
 	@Test
 	public void supportsAllDefaultHandlerExceptionResolverExceptionTypes() throws Exception {
 
-		Method annotMethod = ExceptionHandlerSupport.class.getMethod("handleException", Exception.class, WebRequest.class);
+		Method annotMethod = ResponseEntityExceptionHandler.class.getMethod("handleException", Exception.class, WebRequest.class);
 		ExceptionHandler annot = annotMethod.getAnnotation(ExceptionHandler.class);
 		List<Class<? extends Throwable>> supportedTypes = Arrays.asList(annot.value());
 
@@ -217,14 +216,14 @@ public class ExceptionHandlerSupportTests {
 	}
 
 	@ControllerAdvice
-	private static class ApplicationExceptionHandler extends ExceptionHandlerSupport {
+	private static class ApplicationExceptionHandler extends ResponseEntityExceptionHandler {
 
 		@Override
-		protected Object handleServletRequestBindingException(ServletRequestBindingException ex,
+		protected ResponseEntity<Object> handleServletRequestBindingException(ServletRequestBindingException ex,
 				HttpHeaders headers, HttpStatus status, WebRequest request) {
 
 			headers.set("someHeader", "someHeaderValue");
-			return "error content";
+			return handleExceptionInternal(ex, "error content", headers, status, request);
 		}
 
 

src/reference/docbook/mvc.xml

@@ -3843,15 +3843,23 @@ public class SimpleController {
         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.</para>
-
-        <para>To achieve this extend <classname>ExceptionHandlerSupport</classname>,
-        a convenient base class with an <interfacename>@ExceptionHandler</interfacename>
-        method that handles standard Spring MVC exceptions just as the
-        <classname>DefaultHandlerExceptionResolver</classname> does but also
-        allowing you to prepare error content for the body of the response.
-        See the Javadoc of <classname>ExceptionHandlerSupport</classname>
-        for more details.</para>
+        response for example when providing a REST API. You can prepare a
+        <classname>ModelAndView</classname> and
+        render error content through view resolution -- i.e. by configuring a
+        <classname>ContentNeogitatingViewResolver</classname>,
+        <classname>MappingJacksonJsonView</classname>, and so on. However, you
+        may prefer to use <interfacename>@ExceptionHandler</interfacename>
+        methods instead.</para>
+
+        <para>If you prefer to write error content via
+        <interfacename>@ExceptionHandler</interfacename> methods you can extend
+        <classname>ResponseEntityExceptionHandler</classname> instead.
+        This is a convenient base for <interfacename>@ControllerAdvice</interfacename>
+        classes providing an <interfacename>@ExceptionHandler</interfacename>
+        method to handle standard Spring MVC exceptions and return
+        <classname>ResponseEntity</classname>. That allows you to customize the response
+        and write error content with message converters. See the Javadoc of
+        <classname>ResponseEntityExceptionHandler</classname> for more details.</para>
     </section>
 
     <section id="mvc-ann-annotated-exceptions">

src/reference/docbook/new-in-3.2.xml

@@ -66,7 +66,7 @@
     </section>
 
     <section id="new-in-3.2-webmvc-controller-advice">
-      <title><interfacename>@ControllerAdvice</interfacename> annotation</title>
+      <title>New <interfacename>@ControllerAdvice</interfacename> annotation</title>
       
       <para>Classes annotated with <interfacename>@ControllerAdvice</interfacename>
       can contain <interfacename>@ExceptionHandler</interfacename>,
@@ -81,13 +81,18 @@
     </section>
 
     <section id="new-in-3.2-webmvc-exception-handler-support">
-      <title><classname>ExceptionHandlerSupport</classname> class</title>
+      <title>New <classname>ResponseEntityExceptionHandler</classname> class</title>
 
       <para>A convenient base class with an
       <interfacename>@ExceptionHandler</interfacename>
-      method that handles standard Spring MVC exceptions, just as the
-      <classname>DefaultHandlerExceptionResolver</classname> does, but also
-      allowing you to prepare error content for the body of the response.</para>
+      method that handles standard Spring MVC exceptions and returns a
+      <classname>ResponseEntity</classname> that allowing customizing and writing
+      the response with HTTP message converters. This servers as an alternative
+      to the <classname>DefaultHandlerExceptionResolver</classname>, which does
+      the same but returns a <classname>ModelAndView</classname> instead.</para>
+
+      <para>See the revised <xref linkend="mvc-exceptionhandlers"/>
+      including information on customizing the default Servlet container error page.</para>
 
     </section>