Support Content Negotiation with @ExceptionHandler

Prior to this commit, `@ExceptionHandler` annotated controller methods
could be mapped using the exception type declaration as an annotation
attribute, or as a method parameter.
While such methods support a wide variety of method arguments and return
types, it was not possible to declare the same exception type on
different methods (in the same controller/controller advice).

This commit adds a new `produces` attribute on `@ExceptionHandler`; with
that, applications can vary the HTTP response depending on the exception
type and the requested content-type by the client:

```
@ExceptionHandler(produces = "application/json")
public ResponseEntity<ErrorMessage> handleJson(IllegalArgumentException exc) {
	return ResponseEntity.badRequest().body(new ErrorMessage(exc.getMessage(), 42));
}

@ExceptionHandler(produces = "text/html")
public String handle(IllegalArgumentException exc, Model model) {
	model.addAttribute("error", new ErrorMessage(exc.getMessage(), 42));
	return "errorView";
}
```

This commit implements support in both Spring MVC and Spring WebFlux.

Closes gh-31936

Author: bclozel

framework-docs/modules/ROOT/pages/web/webflux/controller/ann-exceptions.adoc

@@ -7,43 +7,8 @@
 `@ExceptionHandler` methods to handle exceptions from controller methods. The following
 example includes such a handler method:
 
-[tabs]
-======
-Java::
-+
-[source,java,indent=0,subs="verbatim,quotes",role="primary"]
-----
-	@Controller
-	public class SimpleController {
-
-		// ...
-
-		@ExceptionHandler // <1>
-		public ResponseEntity<String> handle(IOException ex) {
-			// ...
-		}
-	}
-----
-<1> Declaring an `@ExceptionHandler`.
-
-Kotlin::
-+
-[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
-----
-	@Controller
-	class SimpleController {
-
-		// ...
-
-		@ExceptionHandler // <1>
-		fun handle(ex: IOException): ResponseEntity<String> {
-			// ...
-		}
-	}
-----
-<1> Declaring an `@ExceptionHandler`.
-======
 
+include-code::./SimpleController[indent=0]
 
 
 The exception can match against a top-level exception being propagated (that is, a direct
@@ -65,6 +30,22 @@ Support for `@ExceptionHandler` methods in Spring WebFlux is provided by the
 `HandlerAdapter` for `@RequestMapping` methods. See xref:web/webflux/dispatcher-handler.adoc[`DispatcherHandler`]
 for more detail.
 
+[[webflux-ann-exceptionhandler-media]]
+== Media Type Mapping
+[.small]#xref:web/webmvc/mvc-controller/ann-exceptionhandler.adoc#mvc-ann-exceptionhandler-media[See equivalent in the Servlet stack]#
+
+In addition to exception types, `@ExceptionHandler` methods can also declare producible media types.
+This allows to refine error responses depending on the media types requested by HTTP clients, typically in the "Accept" HTTP request header.
+
+Applications can declare producible media types directly on annotations, for the same exception type:
+
+
+include-code::./MediaTypeController[tag=mediatype,indent=0]
+
+Here, methods handle the same exception type but will not be rejected as duplicates.
+Instead, API clients requesting "application/json" will receive a JSON error, and browsers will get an HTML error view.
+Each `@ExceptionHandler` annotation can declare several producible media types,
+the content negotiation during the error handling phase will decide which content type will be used.
 
 
 [[webflux-ann-exceptionhandler-args]]

framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-exceptionhandler.adoc

@@ -6,40 +6,12 @@
 `@Controller` and xref:web/webmvc/mvc-controller/ann-advice.adoc[@ControllerAdvice] classes can have
 `@ExceptionHandler` methods to handle exceptions from controller methods, as the following example shows:
 
-[tabs]
-======
-Java::
-+
-[source,java,indent=0,subs="verbatim,quotes",role="primary"]
-----
-	@Controller
-	public class SimpleController {
-
-		// ...
-
-		@ExceptionHandler
-		public ResponseEntity<String> handle(IOException ex) {
-			// ...
-		}
-	}
-----
-
-Kotlin::
-+
-[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
-----
-	@Controller
-	class SimpleController {
-
-		// ...
-
-		@ExceptionHandler
-		fun handle(ex: IOException): ResponseEntity<String> {
-			// ...
-		}
-	}
-----
-======
+
+include-code::./SimpleController[indent=0]
+
+
+[[mvc-ann-exceptionhandler-exc]]
+== Exception Mapping
 
 The exception may match against a top-level exception being propagated (e.g. a direct
 `IOException` being thrown) or against a nested cause within a wrapper exception (e.g.
@@ -54,54 +26,13 @@ is used to sort exceptions based on their depth from the thrown exception type.
 Alternatively, the annotation declaration may narrow the exception types to match,
 as the following example shows:
 
-[tabs]
-======
-Java::
-+
-[source,java,indent=0,subs="verbatim,quotes",role="primary"]
-----
-	@ExceptionHandler({FileSystemException.class, RemoteException.class})
-	public ResponseEntity<String> handle(IOException ex) {
-		// ...
-	}
-----
-
-Kotlin::
-+
-[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
-----
-	@ExceptionHandler(FileSystemException::class, RemoteException::class)
-	fun handle(ex: IOException): ResponseEntity<String> {
-		// ...
-	}
-----
-======
+include-code::./ExceptionController[tag=narrow,indent=0]
 
 You can even use a list of specific exception types with a very generic argument signature,
 as the following example shows:
 
-[tabs]
-======
-Java::
-+
-[source,java,indent=0,subs="verbatim,quotes",role="primary"]
-----
-	@ExceptionHandler({FileSystemException.class, RemoteException.class})
-	public ResponseEntity<String> handle(Exception ex) {
-		// ...
-	}
-----
-
-Kotlin::
-+
-[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
-----
-	@ExceptionHandler(FileSystemException::class, RemoteException::class)
-	fun handle(ex: Exception): ResponseEntity<String> {
-		// ...
-	}
-----
-======
+include-code::./ExceptionController[tag=general,indent=0]
+
 
 [NOTE]
 ====
@@ -143,6 +74,25 @@ Support for `@ExceptionHandler` methods in Spring MVC is built on the `Dispatche
 level, xref:web/webmvc/mvc-servlet/exceptionhandlers.adoc[HandlerExceptionResolver] mechanism.
 
 
+
+[[mvc-ann-exceptionhandler-media]]
+== Media Type Mapping
+[.small]#xref:web/webflux/controller/ann-exceptions.adoc#webflux-ann-exceptionhandler-media[See equivalent in the Reactive stack]#
+
+In addition to exception types, `@ExceptionHandler` methods can also declare producible media types.
+This allows to refine error responses depending on the media types requested by HTTP clients, typically in the "Accept" HTTP request header.
+
+Applications can declare producible media types directly on annotations, for the same exception type:
+
+
+include-code::./MediaTypeController[tag=mediatype,indent=0]
+
+Here, methods handle the same exception type but will not be rejected as duplicates.
+Instead, API clients requesting "application/json" will receive a JSON error, and browsers will get an HTML error view.
+Each `@ExceptionHandler` annotation can declare several producible media types,
+the content negotiation during the error handling phase will decide which content type will be used.
+
+
 [[mvc-ann-exceptionhandler-args]]
 == Method Arguments
 [.small]#xref:web/webflux/controller/ann-exceptions.adoc#webflux-ann-exceptionhandler-args[See equivalent in the Reactive stack]#

framework-docs/src/main/java/org/springframework/docs/web/webflux/controller/webfluxanncontrollerexceptions/SimpleController.java

@@ -0,0 +1,33 @@
+/*
+ * Copyright 2002-2024 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.docs.web.webflux.controller.webfluxanncontrollerexceptions;
+
+import java.io.IOException;
+
+import org.springframework.http.ResponseEntity;
+import org.springframework.stereotype.Controller;
+import org.springframework.web.bind.annotation.ExceptionHandler;
+
+@Controller
+public class SimpleController {
+
+	@ExceptionHandler(IOException.class)
+	public ResponseEntity<String> handle() {
+		return ResponseEntity.internalServerError().body("Could not read file storage");
+	}
+
+}

framework-docs/src/main/java/org/springframework/docs/web/webflux/controller/webfluxannexceptionhandlermedia/MediaTypeController.java

@@ -0,0 +1,43 @@
+/*
+ * Copyright 2002-2024 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.docs.web.webflux.controller.webfluxannexceptionhandlermedia;
+
+import org.springframework.http.ResponseEntity;
+import org.springframework.stereotype.Controller;
+import org.springframework.ui.Model;
+import org.springframework.web.bind.annotation.ExceptionHandler;
+
+@Controller
+public class MediaTypeController {
+
+	// tag::mediatype[]
+	@ExceptionHandler(produces = "application/json")
+	public ResponseEntity<ErrorMessage> handleJson(IllegalArgumentException exc) {
+		return ResponseEntity.badRequest().body(new ErrorMessage(exc.getMessage(), 42));
+	}
+
+	@ExceptionHandler(produces = "text/html")
+	public String handle(IllegalArgumentException exc, Model model) {
+		model.addAttribute("error", new ErrorMessage(exc.getMessage(), 42));
+		return "errorView";
+	}
+	// end::mediatype[]
+
+	static record ErrorMessage(String message, int code) {
+
+	}
+}

framework-docs/src/main/java/org/springframework/docs/web/webmvc/mvccontroller/mvcannexceptionhandler/SimpleController.java

@@ -0,0 +1,33 @@
+/*
+ * Copyright 2002-2024 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.docs.web.webmvc.mvccontroller.mvcannexceptionhandler;
+
+import java.io.IOException;
+
+import org.springframework.http.ResponseEntity;
+import org.springframework.stereotype.Controller;
+import org.springframework.web.bind.annotation.ExceptionHandler;
+
+@Controller
+public class SimpleController {
+
+	@ExceptionHandler(IOException.class)
+	public ResponseEntity<String> handle() {
+		return ResponseEntity.internalServerError().body("Could not read file storage");
+	}
+
+}

framework-docs/src/main/java/org/springframework/docs/web/webmvc/mvccontroller/mvcannexceptionhandlerexc/ExceptionController.java

@@ -0,0 +1,45 @@
+/*
+ * Copyright 2002-2024 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.docs.web.webmvc.mvccontroller.mvcannexceptionhandlerexc;
+
+import java.io.IOException;
+import java.nio.file.FileSystemException;
+import java.rmi.RemoteException;
+
+import org.springframework.http.ResponseEntity;
+import org.springframework.stereotype.Controller;
+import org.springframework.web.bind.annotation.ExceptionHandler;
+
+@Controller
+public class ExceptionController {
+
+	// tag::narrow[]
+	@ExceptionHandler({FileSystemException.class, RemoteException.class})
+	public ResponseEntity<String> handleIoException(IOException ex) {
+		return ResponseEntity.internalServerError().body(ex.getMessage());
+	}
+	// end::narrow[]
+
+
+	// tag::general[]
+	@ExceptionHandler({FileSystemException.class, RemoteException.class})
+	public ResponseEntity<String> handleExceptions(Exception ex) {
+		return ResponseEntity.internalServerError().body(ex.getMessage());
+	}
+	// end::general[]
+
+}