Polishing

See gh-22991

Author: rstoyanchev

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}.
  *
+ * <p>Supported by {@link DispatcherHandler} when used in the following ways:
+ * <ul>
+ * <li>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.
+ * <li>Implemented by a {@link HandlerAdapter} in order to handle exceptions that
+ * occur before a request is mapped to a handler.
+ * </ul>
+ *
  * @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<HandlerResult> handleError(ServerWebExchange exchange, Throwable ex);
 

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.
  *
- * <p>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.
+ * <p>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.
-	 * <p>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.
-	 * <p>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)}.
+	 * <p>Implementations should consider the following for exception handling:
+	 * <ul>
+	 * <li>Handle invocation exceptions within this method.
+	 * <li>{@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.
+	 * <li>Implement {@link DispatchExceptionHandler} to extend exception
+	 * handling to exceptions that occur before a handler is selected.
+	 * </ul>
 	 * @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<HandlerResult> handle(ServerWebExchange exchange, Object handler);
 

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)}

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