diff --git a/spring-webflux/src/main/java/org/springframework/web/reactive/DispatchExceptionHandler.java b/spring-webflux/src/main/java/org/springframework/web/reactive/DispatchExceptionHandler.java
index 017e8bfda042..4486a38bfd36 100644
--- a/spring-webflux/src/main/java/org/springframework/web/reactive/DispatchExceptionHandler.java
+++ b/spring-webflux/src/main/java/org/springframework/web/reactive/DispatchExceptionHandler.java
@@ -23,17 +23,29 @@
/**
* Contract to map a {@link Throwable} to a {@link HandlerResult}.
*
+ *
Supported by {@link DispatcherHandler} when used in the following ways:
+ *
+ * - Set on a {@link HandlerResult#setExceptionHandler HandlerResult}, allowing
+ * a {@link HandlerAdapter} to apply its exception handling to deferred exceptions
+ * from asynchronous return values, and to response rendering.
+ *
- Implemented by a {@link HandlerAdapter} in order to handle exceptions that
+ * occur before a request is mapped to a handler.
+ *
+ *
* @author Rossen Stoyanchev
* @since 6.0
+ * @see HandlerAdapter
+ * @see HandlerResult#setExceptionHandler(DispatchExceptionHandler)
*/
public interface DispatchExceptionHandler {
/**
- * Handler the given exception and resolve it to {@link HandlerResult} that
- * can be used for rendering an HTTP response.
+ * Handle the given exception, mapping it to a {@link HandlerResult} that can
+ * then be used to render an HTTP response.
* @param exchange the current exchange
* @param ex the exception to handle
- * @return a {@code Mono} that emits a {@code HandlerResult} or the original exception
+ * @return a {@code Mono} that emits a {@code HandlerResult} or an error
+ * signal with the original exception if it remains not handled
*/
Mono handleError(ServerWebExchange exchange, Throwable ex);
diff --git a/spring-webflux/src/main/java/org/springframework/web/reactive/HandlerAdapter.java b/spring-webflux/src/main/java/org/springframework/web/reactive/HandlerAdapter.java
index 0a4f8b458e7e..4a7172dff1d2 100644
--- a/spring-webflux/src/main/java/org/springframework/web/reactive/HandlerAdapter.java
+++ b/spring-webflux/src/main/java/org/springframework/web/reactive/HandlerAdapter.java
@@ -21,16 +21,16 @@
import org.springframework.web.server.ServerWebExchange;
/**
- * Contract that decouples the {@link DispatcherHandler} from the details of
- * invoking a handler and makes it possible to support any handler type.
+ * Contract to abstract the details of invoking a handler of a given type.
*
- * A {@code HandlerAdapter} can implement {@link DispatchExceptionHandler}
- * if it wants to handle an exception that occurred before the request is mapped
- * to a handler. This allows the {@code HandlerAdapter} to expose a consistent
- * exception handling mechanism for any request handling error.
- * In Reactive Streams terms, {@link #handle} processes the onNext, while
- * {@link DispatchExceptionHandler#handleError} processes the onError signal
- * from the upstream.
+ *
An implementation can also choose to be an instance of
+ * {@link DispatchExceptionHandler} if it wants to handle exceptions that occur
+ * before the request is successfully mapped to a handler. This allows a
+ * {@code HandlerAdapter} to expose the same exception handling both for handler
+ * invocation errors and for errors before a handler is selected.
+ * In Reactive Streams terms, {@link #handle} handles the onNext signal, while
+ * {@link DispatchExceptionHandler#handleError} handles the onError signal
+ * from the dispatch processing chain.
*
* @author Rossen Stoyanchev
* @author Sebastien Deleuze
@@ -46,20 +46,27 @@ public interface HandlerAdapter {
boolean supports(Object handler);
/**
- * Handle the request with the given handler.
- *
Implementations are encouraged to handle exceptions resulting from the
- * invocation of a handler in order and if necessary to return an alternate
- * result that represents an error response.
- *
Furthermore since an async {@code HandlerResult} may produce an error
- * later during result handling implementations are also encouraged to
- * {@link HandlerResult#setExceptionHandler(DispatchExceptionHandler) set
- * an exception handler} on the {@code HandlerResult} so that may also be
- * applied later after result handling.
+ * Handle the request with the given handler, previously checked via
+ * {@link #supports(Object)}.
+ *
Implementations should consider the following for exception handling:
+ *
+ * - Handle invocation exceptions within this method.
+ *
- {@link HandlerResult#setExceptionHandler(DispatchExceptionHandler)
+ * Set an exception handler} on the returned {@code HandlerResult} to handle
+ * deferred exceptions from asynchronous return values, and to handle
+ * exceptions from response rendering.
+ *
- Implement {@link DispatchExceptionHandler} to extend exception
+ * handling to exceptions that occur before a handler is selected.
+ *
* @param exchange current server exchange
* @param handler the selected handler which must have been previously
* checked via {@link #supports(Object)}
- * @return {@link Mono} that emits a single {@code HandlerResult} or none if
- * the request has been fully handled and doesn't require further handling.
+ * @return {@link Mono} that emits a {@code HandlerResult}, or completes
+ * empty if the request is fully handled; any error signal would not be
+ * handled within the {@link DispatcherHandler}, and would instead be
+ * processed by the chain of registered
+ * {@link org.springframework.web.server.WebExceptionHandler}s at the end
+ * of the {@link org.springframework.web.server.WebFilter} chain
*/
Mono handle(ServerWebExchange exchange, Object handler);
diff --git a/spring-webflux/src/main/java/org/springframework/web/reactive/HandlerResult.java b/spring-webflux/src/main/java/org/springframework/web/reactive/HandlerResult.java
index 0e03511708e7..9844e59f57c8 100644
--- a/spring-webflux/src/main/java/org/springframework/web/reactive/HandlerResult.java
+++ b/spring-webflux/src/main/java/org/springframework/web/reactive/HandlerResult.java
@@ -128,11 +128,9 @@ public Model getModel() {
}
/**
- * A {@link HandlerAdapter} may use this to provide an exception handler
- * to use to map exceptions from handling this result into an alternative
- * one. Especially when the return value is asynchronous, an exception is
- * not be produced at the point of handler invocation, but rather later when
- * result handling causes the actual value or an exception to be produced.
+ * {@link HandlerAdapter} classes can set this to have their exception
+ * handling mechanism applied to response rendering and to deferred
+ * exceptions when invoking a handler with an asynchronous return value.
* @param exceptionHandler the exception handler to use
* @since 6.0
*/
@@ -152,9 +150,9 @@ public DispatchExceptionHandler getExceptionHandler() {
}
/**
- * Configure an exception handler that may be used to produce an alternative
- * result when result handling fails. Especially for an async return value
- * errors may occur after the invocation of the handler.
+ * {@link HandlerAdapter} classes can set this to have their exception
+ * handling mechanism applied to response rendering and to deferred
+ * exceptions when invoking a handler with an asynchronous return value.
* @param function the error handler
* @return the current instance
* @deprecated in favor of {@link #setExceptionHandler(DispatchExceptionHandler)}
diff --git a/spring-webflux/src/main/java/org/springframework/web/reactive/HandlerResultHandler.java b/spring-webflux/src/main/java/org/springframework/web/reactive/HandlerResultHandler.java
index 6badfaa68479..192d9ee872ef 100644
--- a/spring-webflux/src/main/java/org/springframework/web/reactive/HandlerResultHandler.java
+++ b/spring-webflux/src/main/java/org/springframework/web/reactive/HandlerResultHandler.java
@@ -21,7 +21,7 @@
import org.springframework.web.server.ServerWebExchange;
/**
- * Process the {@link HandlerResult}, usually returned by an {@link HandlerAdapter}.
+ * Process the {@link HandlerResult}, usually returned by a {@link HandlerAdapter}.
*
* @author Rossen Stoyanchev
* @author Sebastien Deleuze