Add Javadoc for main interfaces/classes

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.
+ *
+ * <li>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.
+ *
+ * <li>It can use any {@link HandlerAdapter}; this allows for using any handler interface.
+ * HandlerAdapter objects can be added as beans in the application context.
+ *
+ * <li>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 {
 

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.
+	 * <p>A typical implementation:
+	 * <p>{@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;
 
 }

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 {

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<Void>}.
+	 *
+	 * @return A {@code Publisher<Void>} 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<Void> handleResult(ServerHttpRequest request, ServerHttpResponse response, HandlerResult result);
 
 }

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<Void>}.
+	 *
+	 * @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<Void>} 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<Void> handle(ServerHttpRequest request, ServerHttpResponse response);
 
 }

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<ByteBuffer> getBody();
 
 }

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<Void>} 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<Void> writeWith(Publisher<ByteBuffer> contentPublisher);
 
 }