From fb22044c103741b2ffd391397e5ac7477cb89495 Mon Sep 17 00:00:00 2001 From: rstoyanchev Date: Wed, 9 Nov 2022 11:34:21 +0000 Subject: [PATCH] Polishing See gh-22991 --- .../reactive/DispatchExceptionHandler.java | 18 +++++-- .../web/reactive/HandlerAdapter.java | 47 +++++++++++-------- .../web/reactive/HandlerResult.java | 14 +++--- .../web/reactive/HandlerResultHandler.java | 2 +- 4 files changed, 49 insertions(+), 32 deletions(-) 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: + *

+ * * @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: + *

* @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