diff --git a/spring-web-reactive/src/main/java/org/springframework/reactive/web/dispatch/DispatcherHandler.java b/spring-web-reactive/src/main/java/org/springframework/reactive/web/dispatch/DispatcherHandler.java index de38f689aa..a7bc0904ef 100644 --- a/spring-web-reactive/src/main/java/org/springframework/reactive/web/dispatch/DispatcherHandler.java +++ b/spring-web-reactive/src/main/java/org/springframework/reactive/web/dispatch/DispatcherHandler.java @@ -35,7 +35,22 @@ import org.springframework.reactive.web.http.ServerHttpRequest; import org.springframework.reactive.web.http.ServerHttpResponse; /** + * Central dispatcher for HTTP request handlers/controllers. Dispatches to registered + * handlers for processing a web request, providing convenient mapping facilities. + * + *
  • It can use any {@link HandlerMapping} implementation to control the routing of + * requests to handler objects. HandlerMapping objects can be defined as beans in + * the application context. + * + *
  • It can use any {@link HandlerAdapter}; this allows for using any handler interface. + * HandlerAdapter objects can be added as beans in the application context. + * + *
  • It can use any {@link HandlerResultHandler}; this allows to process the result of + * the request handling. HandlerResultHandler objects can be added as beans in the + * application context. + * * @author Rossen Stoyanchev + * @author Sebastien Deleuze */ public class DispatcherHandler implements HttpHandler, ApplicationContextAware { diff --git a/spring-web-reactive/src/main/java/org/springframework/reactive/web/dispatch/HandlerAdapter.java b/spring-web-reactive/src/main/java/org/springframework/reactive/web/dispatch/HandlerAdapter.java index 94e8355e47..01fc9a9f0e 100644 --- a/spring-web-reactive/src/main/java/org/springframework/reactive/web/dispatch/HandlerAdapter.java +++ b/spring-web-reactive/src/main/java/org/springframework/reactive/web/dispatch/HandlerAdapter.java @@ -19,12 +19,39 @@ import org.springframework.reactive.web.http.ServerHttpRequest; import org.springframework.reactive.web.http.ServerHttpResponse; /** + * Interface that must be implemented for each handler type to handle an HTTP request. + * This interface is used to allow the {@link DispatcherHandler} to be indefinitely + * extensible. The {@code DispatcherHandler} accesses all installed handlers through + * this interface, meaning that it does not contain code specific to any handler type. + * * @author Rossen Stoyanchev + * @author Sebastien Deleuze */ public interface HandlerAdapter { + /** + * Given a handler instance, return whether or not this {@code HandlerAdapter} + * can support it. Typical HandlerAdapters will base the decision on the handler + * type. HandlerAdapters will usually only support one handler type each. + *

    A typical implementation: + *

    {@code + * return (handler instanceof MyHandler); + * } + * @param handler handler object to check + * @return whether or not this object can use the given handler + */ boolean supports(Object handler); + /** + * Use the given handler to handle this request. + * @param request current HTTP request + * @param response current HTTP response + * @param handler handler to use. This object must have previously been passed + * to the {@code supports} method of this interface, which must have + * returned {@code true}. + * @throws Exception in case of errors + * @return An {@link HandlerResult} instance + */ HandlerResult handle(ServerHttpRequest request, ServerHttpResponse response, Object handler) throws Exception; } diff --git a/spring-web-reactive/src/main/java/org/springframework/reactive/web/dispatch/HandlerResult.java b/spring-web-reactive/src/main/java/org/springframework/reactive/web/dispatch/HandlerResult.java index 4a6ec2dc3f..2b3c912071 100644 --- a/spring-web-reactive/src/main/java/org/springframework/reactive/web/dispatch/HandlerResult.java +++ b/spring-web-reactive/src/main/java/org/springframework/reactive/web/dispatch/HandlerResult.java @@ -17,6 +17,8 @@ package org.springframework.reactive.web.dispatch; /** + * Represent the result of the invocation of an handler. + * * @author Rossen Stoyanchev */ public class HandlerResult { diff --git a/spring-web-reactive/src/main/java/org/springframework/reactive/web/dispatch/HandlerResultHandler.java b/spring-web-reactive/src/main/java/org/springframework/reactive/web/dispatch/HandlerResultHandler.java index 46257e3ec4..7a4a9cb23b 100644 --- a/spring-web-reactive/src/main/java/org/springframework/reactive/web/dispatch/HandlerResultHandler.java +++ b/spring-web-reactive/src/main/java/org/springframework/reactive/web/dispatch/HandlerResultHandler.java @@ -21,12 +21,32 @@ import org.springframework.reactive.web.http.ServerHttpRequest; import org.springframework.reactive.web.http.ServerHttpResponse; /** + * Process the {@link HandlerResult}, usually returned by an {@link HandlerAdapter}. + * * @author Rossen Stoyanchev + * @author Sebastien Deleuze */ public interface HandlerResultHandler { + /** + * Given a handler instance, return whether or not this {@code HandlerResultHandler} + * can support it. + * + * @param result result object to check + * @return whether or not this object can use the given result + */ boolean supports(HandlerResult result); + /** + * Process the given result in an asynchronous non blocking way, by eventually modifying + * response headers, or writing some data stream into the response. + * Implementations should not throw exceptions but signal them via the returned + * {@code Publisher}. + * + * @return A {@code Publisher} used to signal the demand, and receive a notification + * when the handling is complete (success or error) including the flush of the data on the + * network. + */ Publisher handleResult(ServerHttpRequest request, ServerHttpResponse response, HandlerResult result); } \ No newline at end of file diff --git a/spring-web-reactive/src/main/java/org/springframework/reactive/web/http/HttpHandler.java b/spring-web-reactive/src/main/java/org/springframework/reactive/web/http/HttpHandler.java index 77897de4e7..4158526da8 100644 --- a/spring-web-reactive/src/main/java/org/springframework/reactive/web/http/HttpHandler.java +++ b/spring-web-reactive/src/main/java/org/springframework/reactive/web/http/HttpHandler.java @@ -20,11 +20,30 @@ import org.reactivestreams.Publisher; /** + * Interface for handlers that process HTTP requests and generate an HTTP response. + * This handler is designed to be called when the HTTP headers have been received, making + * the HTTP request body available as stream. The HTTP response body can also be written + * as a stream. + * * @author Arjen Poutsma * @author Rossen Stoyanchev + * @author Sebastien Deleuze + * @see ServerHttpRequest#getBody() + * @see ServerHttpResponse#writeWith(Publisher) */ public interface HttpHandler { + /** + * Process the given request, generating a response in an asynchronous non blocking way. + * Implementations should not throw exceptions but signal them via the returned + * {@code Publisher}. + * + * @param request current HTTP request, the body can be processed as a data stream. + * @param response current HTTP response, the body can be provided as a data stream. + * @return A {@code Publisher} used to signal the demand, and receive a notification + * when the handling is complete (success or error) including the flush of the data on the + * network. + */ Publisher handle(ServerHttpRequest request, ServerHttpResponse response); } diff --git a/spring-web-reactive/src/main/java/org/springframework/reactive/web/http/ServerHttpRequest.java b/spring-web-reactive/src/main/java/org/springframework/reactive/web/http/ServerHttpRequest.java index bfbf9771ef..dca48dee1c 100644 --- a/spring-web-reactive/src/main/java/org/springframework/reactive/web/http/ServerHttpRequest.java +++ b/spring-web-reactive/src/main/java/org/springframework/reactive/web/http/ServerHttpRequest.java @@ -20,11 +20,15 @@ import java.nio.ByteBuffer; import org.reactivestreams.Publisher; /** + * Represent a server-side HTTP request. * * @author Rossen Stoyanchev */ public interface ServerHttpRequest extends HttpRequest { + /** + * Return the body of the message as a reactive stream. + */ Publisher getBody(); } diff --git a/spring-web-reactive/src/main/java/org/springframework/reactive/web/http/ServerHttpResponse.java b/spring-web-reactive/src/main/java/org/springframework/reactive/web/http/ServerHttpResponse.java index 3063aa2b2f..ba7cc6f5db 100644 --- a/spring-web-reactive/src/main/java/org/springframework/reactive/web/http/ServerHttpResponse.java +++ b/spring-web-reactive/src/main/java/org/springframework/reactive/web/http/ServerHttpResponse.java @@ -22,12 +22,22 @@ import org.reactivestreams.Publisher; import org.springframework.http.HttpStatus; /** + * Represent a server-side HTTP response. + * * @author Rossen Stoyanchev */ public interface ServerHttpResponse extends HttpMessage { void setStatusCode(HttpStatus status); + /** + * Write the provided reactive stream of bytes to the response body. Most servers + * support multiple {@code writeWith} calls. + * @param contentPublisher the stream to write in the response body. + * @return A {@code Publisher} used to signal the demand, and receive a notification + * when the handling is complete (success or error) including the flush of the data on the + * network. + */ Publisher writeWith(Publisher contentPublisher); }