You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@hc.apache.org by ol...@apache.org on 2018/08/21 15:01:42 UTC
[31/32] httpcomponents-core git commit: Javadocs for core HTTP APIs
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncPushConsumer.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncPushConsumer.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncPushConsumer.java
index 5099c75..beaf393 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncPushConsumer.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncPushConsumer.java
@@ -41,8 +41,24 @@ import org.apache.hc.core5.http.protocol.HttpContext;
*/
public interface AsyncPushConsumer extends AsyncDataConsumer {
- void consumePromise(HttpRequest promise, HttpResponse response, EntityDetails entityDetails, HttpContext context) throws HttpException, IOException;
+ /**
+ * Triggered to signal receipt of a request message head used as a promise
+ * and the corresponding pushed response.
+ *
+ * @param promise the request message head used as a promise.
+ * @param response the pushed response message.
+ * @param entityDetails the response entity details or {@code null} if the response
+ * does not enclose an entity.
+ * @param context the actual execution context.
+ */
+ void consumePromise(HttpRequest promise, HttpResponse response, EntityDetails entityDetails,
+ HttpContext context) throws HttpException, IOException;
+ /**
+ * Triggered to signal a failure in data processing.
+ *
+ * @param cause the cause of the failure.
+ */
void failed(Exception cause);
}
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncPushProducer.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncPushProducer.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncPushProducer.java
index 0aab472..b7e4fd5 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncPushProducer.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncPushProducer.java
@@ -38,8 +38,23 @@ import org.apache.hc.core5.http.protocol.HttpContext;
*/
public interface AsyncPushProducer extends AsyncDataProducer {
- void produceResponse(ResponseChannel channel, HttpContext httpContext) throws HttpException, IOException;
+ /**
+ * Triggered to signal the ability of the underlying response channel
+ * to accept response messages. The data producer can choose to send
+ * a final response message immediately inside the call or asynchronously
+ * at some later point. The final response can be preceded by a number
+ * of intermediate messages.
+ *
+ * @param channel the response channel capable to accepting response messages.
+ * @param context the actual execution context.
+ */
+ void produceResponse(ResponseChannel channel, HttpContext context) throws HttpException, IOException;
+ /**
+ * Triggered to signal a failure in data generation.
+ *
+ * @param cause the cause of the failure.
+ */
void failed(Exception cause);
}
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncRequestConsumer.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncRequestConsumer.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncRequestConsumer.java
index f1c8d39..c4220f4 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncRequestConsumer.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncRequestConsumer.java
@@ -37,15 +37,38 @@ import org.apache.hc.core5.http.protocol.HttpContext;
/**
* Abstract asynchronous request consumer.
*
- * @param <T> the future result type returned by a callback.
+ * @param <T> request representation.
+ *
* @since 5.0
*/
public interface AsyncRequestConsumer<T> extends AsyncDataConsumer {
- void consumeRequest(HttpRequest request, EntityDetails entityDetails, HttpContext httpContext, FutureCallback<T> resultCallback) throws HttpException, IOException;
+ /**
+ * Triggered to signal receipt of a request message head.
+ *
+ * @param request the request message head.
+ * @param entityDetails the request entity details or {@code null} if the request
+ * does not enclose an entity.
+ * @param context the actual execution context.
+ * @param resultCallback the result callback called when request processing
+ * has been completed successfully or unsuccessfully.
+ */
+ void consumeRequest(HttpRequest request, EntityDetails entityDetails, HttpContext context,
+ FutureCallback<T> resultCallback) throws HttpException, IOException;
+ /**
+ * Triggered to signal a failure in data processing.
+ *
+ * @param cause the cause of the failure.
+ */
void failed(Exception cause);
+ /**
+ * Returns the result of request processing when it becomes available or {@code null}
+ * if the request is still being received.
+ *
+ * @return the request processing result.
+ */
T getResult();
}
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncRequestProducer.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncRequestProducer.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncRequestProducer.java
index 29af31f..8839adc 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncRequestProducer.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncRequestProducer.java
@@ -31,7 +31,6 @@ import java.io.IOException;
import org.apache.hc.core5.http.HttpException;
import org.apache.hc.core5.http.protocol.HttpContext;
-
/**
* Abstract asynchronous request producer.
*
@@ -39,10 +38,28 @@ import org.apache.hc.core5.http.protocol.HttpContext;
*/
public interface AsyncRequestProducer extends AsyncDataProducer {
- void sendRequest(RequestChannel requestChannel, HttpContext httpContext) throws HttpException, IOException;
+ /**
+ * Triggered to signal the ability of the underlying request channel
+ * to accept a request messages. The data producer can choose to send
+ * a request message immediately inside the call or asynchronously
+ * at some later point.
+ *
+ * @param channel the request channel capable to accepting a request message.
+ * @param context the actual execution context.
+ */
+ void sendRequest(RequestChannel channel, HttpContext context) throws HttpException, IOException;
+ /**
+ * Determines whether the producer can consistently produce the same content
+ * after invocation of {@link ResourceHolder#releaseResources()}.
+ */
boolean isRepeatable();
+ /**
+ * Triggered to signal a failure in data generation.
+ *
+ * @param cause the cause of the failure.
+ */
void failed(Exception cause);
}
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncResponseConsumer.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncResponseConsumer.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncResponseConsumer.java
index 7863c12..9c14b3d 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncResponseConsumer.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncResponseConsumer.java
@@ -37,17 +37,46 @@ import org.apache.hc.core5.http.protocol.HttpContext;
/**
* Abstract asynchronous response consumer.
*
- * @param <T> the future result type returned by a callback.
+ * @param <T> response representation.
+ *
* @since 5.0
*/
public interface AsyncResponseConsumer<T> extends AsyncDataConsumer {
- void consumeResponse(HttpResponse response, EntityDetails entityDetails, HttpContext httpContext, FutureCallback<T> resultCallback) throws HttpException, IOException;
+ /**
+ * Triggered to signal receipt of a response message head.
+ *
+ * @param response the response message head.
+ * @param entityDetails the response entity details or {@code null} if the response
+ * does not enclose an entity.
+ * @param context the actual execution context.
+ * @param resultCallback the result callback called when response processing
+ * has been completed successfully or unsuccessfully.
+ */
+ void consumeResponse(HttpResponse response, EntityDetails entityDetails, HttpContext context,
+ FutureCallback<T> resultCallback) throws HttpException, IOException;
- void informationResponse(HttpResponse response, HttpContext httpContext) throws HttpException, IOException;
+ /**
+ * Triggered to signal receipt of an intermediate (1xx) HTTP response.
+ *
+ * @param response the intermediate (1xx) HTTP response.
+ * @param context the actual execution context.
+ */
+ void informationResponse(HttpResponse response, HttpContext context) throws HttpException, IOException;
+ /**
+ * Triggered to signal a failure in data processing.
+ *
+ * @param cause the cause of the failure.
+ */
void failed(Exception cause);
+ /**
+ * Returns the result of response processing when it becomes available or {@code null}
+ * if the response is still being received.
+ *
+ * @return the response processing result.
+ */
T getResult();
}
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncResponseProducer.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncResponseProducer.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncResponseProducer.java
index 80dc8f7..896f499 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncResponseProducer.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncResponseProducer.java
@@ -38,8 +38,22 @@ import org.apache.hc.core5.http.protocol.HttpContext;
*/
public interface AsyncResponseProducer extends AsyncDataProducer {
- void sendResponse(ResponseChannel channel, HttpContext httpContext) throws HttpException, IOException;
+ /**
+ * Triggered to signal the ability of the underlying response channel
+ * to accept response messagess. The data producer can choose to send
+ * response messages immediately inside the call or asynchronously
+ * at some later point.
+ *
+ * @param channel the response channel capable to accepting response messages.
+ * @param context the actual execution context.
+ */
+ void sendResponse(ResponseChannel channel, HttpContext context) throws HttpException, IOException;
+ /**
+ * Triggered to signal a failure in data generation.
+ *
+ * @param cause the cause of the failure.
+ */
void failed(Exception cause);
}
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncServerExchangeHandler.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncServerExchangeHandler.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncServerExchangeHandler.java
index 3c75820..6c738ad 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncServerExchangeHandler.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncServerExchangeHandler.java
@@ -41,6 +41,17 @@ import org.apache.hc.core5.http.protocol.HttpContext;
*/
public interface AsyncServerExchangeHandler extends AsyncDataExchangeHandler {
+ /**
+ * Processes the actual HTTP request. The handler can choose to send
+ * response messages immediately inside the call or asynchronously
+ * at some later point.
+ *
+ * @param request the actual request.
+ * @param entityDetails the request entity details or {@code null} if the request
+ * does not enclose an entity.
+ * @param responseChannel the response channel.
+ * @param context the actual execution context.
+ */
void handleRequest(
HttpRequest request,
EntityDetails entityDetails,
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncServerRequestHandler.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncServerRequestHandler.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncServerRequestHandler.java
index 6e84474..dce7c96 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncServerRequestHandler.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncServerRequestHandler.java
@@ -37,23 +37,75 @@ import org.apache.hc.core5.http.HttpResponse;
import org.apache.hc.core5.http.protocol.HttpContext;
/**
+ * AsyncServerRequestHandler represents a routine for processing of a specific group
+ * of HTTP requests. Request execution filters are designed to take care of protocol
+ * specific aspects, whereas individual request handlers are expected to take care
+ * of application specific HTTP processing. The main purpose of a request handler
+ * is to generate a response object with a content entity to be sent back to
+ * the client in response to the given request.
+ *
+ * @param <T> request representation.
+ *
* @since 5.0
*/
@Contract(threading = ThreadingBehavior.STATELESS)
public interface AsyncServerRequestHandler<T> {
+ /**
+ * Response trigger that can be used to submit a final HTTP response
+ * and terminate HTTP request processing.
+ */
interface ResponseTrigger {
- void sendInformation(HttpResponse response, HttpContext httpContext) throws HttpException, IOException;
+ /**
+ * Sends an intermediate informational HTTP response to the client.
+ *
+ * @param response the intermediate (1xx) HTTP response
+ * @param context the actual execution context.
+ */
+ void sendInformation(HttpResponse response, HttpContext context) throws HttpException, IOException;
- void submitResponse(AsyncResponseProducer responseProducer, HttpContext httpContext) throws HttpException, IOException;
+ /**
+ * Sends a final HTTP response to the client.
+ *
+ * @param responseProducer the HTTP response message producer.
+ * @param context the actual execution context.
+ */
+ void submitResponse(AsyncResponseProducer responseProducer, HttpContext context) throws HttpException, IOException;
- void pushPromise(HttpRequest promise, HttpContext httpContext, AsyncPushProducer responseProducer) throws HttpException, IOException;
+ /**
+ * Pushes a request message head as a promise to deliver a response message.
+ *
+ * @param promise the request message header used as a promise.
+ * @param context the actual execution context.
+ * @param responseProducer the push response message producer.
+ */
+ void pushPromise(HttpRequest promise, HttpContext context, AsyncPushProducer responseProducer) throws HttpException, IOException;
}
+ /**
+ * Triggered to signal new incoming request. The handler can create a {@link AsyncRequestConsumer} based on
+ * properties of the request head and entity details and let it process the request data stream. The request
+ * handler will be used to generate an object that represents request data.
+ *
+ * @param request the incoming request head.
+ * @param entityDetails the request entity details or {@code null} if the request
+ * does not enclose an entity.
+ * @param context the actual execution context.
+ * @return the request handler.
+ */
AsyncRequestConsumer<T> prepare(HttpRequest request, EntityDetails entityDetails, HttpContext context) throws HttpException;
- void handle(T requestMessage, ResponseTrigger responseTrigger, HttpContext context) throws HttpException, IOException;
+ /**
+ * Triggered to handles the request object produced by the {@link AsyncRequestConsumer} returned
+ * from the {@link #prepare(HttpRequest, EntityDetails, HttpContext)} method. The handler can choose
+ * to send response messages immediately inside the call or asynchronously at some later point.
+ *
+ * @param requestObject the request object.
+ * @param responseTrigger the response trigger.
+ * @param context the actual execution context.
+ */
+ void handle(T requestObject, ResponseTrigger responseTrigger, HttpContext context) throws HttpException, IOException;
}
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/BasicPushProducer.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/BasicPushProducer.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/BasicPushProducer.java
index df4271c..09077b4 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/BasicPushProducer.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/BasicPushProducer.java
@@ -36,6 +36,9 @@ import org.apache.hc.core5.http.protocol.HttpContext;
import org.apache.hc.core5.util.Args;
/**
+ * Basic implementation of {@link AsyncPushProducer} that produces one fixed response
+ * and relies on a {@link AsyncEntityProducer} to generate response entity stream.
+ *
* @since 5.0
*/
public class BasicPushProducer implements AsyncPushProducer {
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/BasicRequestConsumer.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/BasicRequestConsumer.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/BasicRequestConsumer.java
index e0290c7..d559381 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/BasicRequestConsumer.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/BasicRequestConsumer.java
@@ -41,6 +41,9 @@ import org.apache.hc.core5.util.Args;
import org.apache.hc.core5.util.Asserts;
/**
+ * Basic implementation of {@link AsyncRequestConsumer} that represents the request message as
+ * a {@link Message} and relies on a {@link AsyncEntityConsumer} to process request entity stream.
+ *
* @since 5.0
*/
public class BasicRequestConsumer<T> implements AsyncRequestConsumer<Message<HttpRequest, T>> {
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/BasicRequestProducer.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/BasicRequestProducer.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/BasicRequestProducer.java
index 58c00de..fed369e 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/BasicRequestProducer.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/BasicRequestProducer.java
@@ -35,6 +35,12 @@ import org.apache.hc.core5.http.HttpRequest;
import org.apache.hc.core5.http.message.BasicHttpRequest;
import org.apache.hc.core5.http.protocol.HttpContext;
+/**
+ * Basic implementation of {@link AsyncRequestProducer} that produces one fixed request
+ * and relies on a {@link AsyncEntityProducer} to generate request entity stream.
+ *
+ * @since 5.0
+ */
public class BasicRequestProducer implements AsyncRequestProducer {
private final HttpRequest request;
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/BasicResponseConsumer.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/BasicResponseConsumer.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/BasicResponseConsumer.java
index f7c032b..25d76e9 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/BasicResponseConsumer.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/BasicResponseConsumer.java
@@ -40,6 +40,10 @@ import org.apache.hc.core5.http.protocol.HttpContext;
import org.apache.hc.core5.util.Args;
/**
+ * Basic implementation of {@link AsyncResponseConsumer} that represents response message as
+ * a {@link Message} and relies on a {@link AsyncEntityConsumer} to process response entity
+ * stream.
+ *
* @since 5.0
*/
public class BasicResponseConsumer<T> implements AsyncResponseConsumer<Message<HttpResponse, T>> {
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/BasicResponseProducer.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/BasicResponseProducer.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/BasicResponseProducer.java
index 27cf8e1..c98b9ee 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/BasicResponseProducer.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/BasicResponseProducer.java
@@ -38,6 +38,9 @@ import org.apache.hc.core5.http.protocol.HttpContext;
import org.apache.hc.core5.util.Args;
/**
+ * Basic implementation of {@link AsyncResponseProducer} that produces one fixed response
+ * and relies on a {@link AsyncEntityProducer} to generate response entity stream.
+ *
* @since 5.0
*/
public class BasicResponseProducer implements AsyncResponseProducer {
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/CapacityChannel.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/CapacityChannel.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/CapacityChannel.java
index 4e724ef..9d73d9e 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/CapacityChannel.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/CapacityChannel.java
@@ -43,7 +43,7 @@ import org.apache.hc.core5.annotation.ThreadingBehavior;
public interface CapacityChannel {
/**
- * Updates data capacity information. The total number of
+ * Updates data capacity information through this channel. The total number of
* bytes the consumer is capable of accepting is incremented
* by the given increment number.
*
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/DataStreamChannel.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/DataStreamChannel.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/DataStreamChannel.java
index e30e42d..d3e3bd8 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/DataStreamChannel.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/DataStreamChannel.java
@@ -54,7 +54,7 @@ public interface DataStreamChannel extends StreamChannel<ByteBuffer> {
void requestOutput();
/**
- * Writes data from the buffer into the underlying byte stream.
+ * Writes data from the buffer through this channel into the underlying byte stream.
* If the underlying byte stream is temporarily unable to accept more data
* it can return zero to indicate that no data could be written to the data
* stream. The data producer can choose to call {@link #requestOutput()}
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/HandlerFactory.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/HandlerFactory.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/HandlerFactory.java
index abcbf8c..fb3b73e 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/HandlerFactory.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/HandlerFactory.java
@@ -33,12 +33,20 @@ import org.apache.hc.core5.http.protocol.HttpContext;
/**
* Abstract handler factory.
*
- * @param <T> resource holder
+ * @param <T> handler type
*
* @since 5.0
*/
public interface HandlerFactory<T extends ResourceHolder> {
+ /**
+ * Creates a new handler instance based on properties of
+ * an incoming request message..
+ *
+ * @param request the incoming reqquest head.
+ * @param context the actual execution context.
+ * @return handler
+ */
T create(HttpRequest request, HttpContext context) throws HttpException;
}
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/RequestChannel.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/RequestChannel.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/RequestChannel.java
index 3c8285e..5ac4e40 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/RequestChannel.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/RequestChannel.java
@@ -46,6 +46,13 @@ import org.apache.hc.core5.http.protocol.HttpContext;
@Contract(threading = ThreadingBehavior.SAFE)
public interface RequestChannel {
- void sendRequest(HttpRequest request, EntityDetails entityDetails, HttpContext httpContext) throws HttpException, IOException;
+ /**
+ * Sends a request through this channel.
+ *
+ * @param request the outgoing request.
+ * @param entityDetails the details of the entity enclosed in the request
+ * @param context the actual execution context.
+ */
+ void sendRequest(HttpRequest request, EntityDetails entityDetails, HttpContext context) throws HttpException, IOException;
}
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/ResponseChannel.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/ResponseChannel.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/ResponseChannel.java
index 9eb41ee..c18a8e6 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/ResponseChannel.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/ResponseChannel.java
@@ -48,10 +48,32 @@ import org.apache.hc.core5.http.protocol.HttpContext;
@Contract(threading = ThreadingBehavior.SAFE)
public interface ResponseChannel {
- void sendInformation(HttpResponse response, HttpContext httpContext) throws HttpException, IOException;
+ /**
+ * Sends an intermediate informational HTTP response through this channel.
+ *
+ * @param response an intermediate (1xx) HTTP response.
+ * @param context the actual execution context.
+ */
+ void sendInformation(HttpResponse response, HttpContext context) throws HttpException, IOException;
- void sendResponse(HttpResponse response, EntityDetails entityDetails, HttpContext httpContext) throws HttpException, IOException;
+ /**
+ * Sends a final HTTP response through this channel.
+ *
+ * @param response a final (non 1xx) HTTP response
+ * @param entityDetails the response entity details or {@code null} if the response
+ * does not enclose an entity.
+ * @param context the actual execution context.
+ */
+ void sendResponse(HttpResponse response, EntityDetails entityDetails, HttpContext context) throws HttpException, IOException;
- void pushPromise(HttpRequest promise, HttpContext httpContext, AsyncPushProducer pushProducer) throws HttpException, IOException;
+ /**
+ * Pushes a request message head through this channel as a promise to deliver
+ * a response message.
+ *
+ * @param promise the request message header used as a promise.
+ * @param context the actual execution context.
+ * @param responseProducer the push response message producer.
+ */
+ void pushPromise(HttpRequest promise, HttpContext context, AsyncPushProducer responseProducer) throws HttpException, IOException;
}
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/command/ExecutableCommand.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/command/ExecutableCommand.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/command/ExecutableCommand.java
index 60359e2..47cb1aa 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/command/ExecutableCommand.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/command/ExecutableCommand.java
@@ -27,14 +27,18 @@
package org.apache.hc.core5.http.nio.command;
+import org.apache.hc.core5.annotation.Internal;
import org.apache.hc.core5.concurrent.CancellableDependency;
import org.apache.hc.core5.reactor.Command;
/**
- * Abstract executable command.
+ * Abstract executable command that may need to do some cleaning up
+ * in case of an failure and also optionally may want to cancel
+ * the associated HTTP message exchange through {@link CancellableDependency}.
*
* @since 5.0
*/
+@Internal
public abstract class ExecutableCommand implements Command {
public abstract CancellableDependency getCancellableDependency();
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/command/RequestExecutionCommand.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/command/RequestExecutionCommand.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/command/RequestExecutionCommand.java
index 98f46f2..05f0961 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/command/RequestExecutionCommand.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/command/RequestExecutionCommand.java
@@ -27,6 +27,7 @@
package org.apache.hc.core5.http.nio.command;
+import org.apache.hc.core5.annotation.Internal;
import org.apache.hc.core5.concurrent.CancellableDependency;
import org.apache.hc.core5.http.nio.AsyncClientExchangeHandler;
import org.apache.hc.core5.http.nio.AsyncPushConsumer;
@@ -39,6 +40,7 @@ import org.apache.hc.core5.util.Args;
*
* @since 5.0
*/
+@Internal
public final class RequestExecutionCommand extends ExecutableCommand {
private final AsyncClientExchangeHandler exchangeHandler;
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/command/ShutdownCommand.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/command/ShutdownCommand.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/command/ShutdownCommand.java
index db7d174..bb215f6 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/command/ShutdownCommand.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/command/ShutdownCommand.java
@@ -31,7 +31,9 @@ import org.apache.hc.core5.io.CloseMode;
import org.apache.hc.core5.reactor.Command;
/**
- * Shutdown command.
+ * Shutdown command. Two shutdown modes are supported: {@link CloseMode#GRACEFUL}
+ * and {@link CloseMode#IMMEDIATE}. The exact implementation of both modes is protocol
+ * or handler specific.
*
* @since 5.0
*/
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/AbstractBinAsyncEntityConsumer.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/AbstractBinAsyncEntityConsumer.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/AbstractBinAsyncEntityConsumer.java
index f270841..4e29209 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/AbstractBinAsyncEntityConsumer.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/AbstractBinAsyncEntityConsumer.java
@@ -37,13 +37,30 @@ import org.apache.hc.core5.http.HttpException;
import org.apache.hc.core5.http.nio.AsyncEntityConsumer;
import org.apache.hc.core5.util.Args;
+/**
+ * Abstract binary entity content consumer.
+ *
+ * @since 5.0
+ *
+ * @param <T> entity representation.
+ */
public abstract class AbstractBinAsyncEntityConsumer<T> extends AbstractBinDataConsumer implements AsyncEntityConsumer<T> {
private volatile FutureCallback<T> resultCallback;
private volatile T content;
+ /**
+ * Triggered to signal beginning of entity content stream.
+ *
+ * @param contentType the entity content type
+ */
protected abstract void streamStart(ContentType contentType) throws HttpException, IOException;
+ /**
+ * Triggered to generate entity representation.
+ *
+ * @return the entity content
+ */
protected abstract T generateContent() throws IOException;
@Override
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/AbstractBinAsyncEntityProducer.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/AbstractBinAsyncEntityProducer.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/AbstractBinAsyncEntityProducer.java
index aaf387c..234c054 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/AbstractBinAsyncEntityProducer.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/AbstractBinAsyncEntityProducer.java
@@ -37,6 +37,8 @@ import org.apache.hc.core5.http.nio.StreamChannel;
import org.apache.hc.core5.util.Args;
/**
+ * Abstract binary entity content producer.
+ *
* @since 5.0
*/
public abstract class AbstractBinAsyncEntityProducer implements AsyncEntityProducer {
@@ -57,6 +59,13 @@ public abstract class AbstractBinAsyncEntityProducer implements AsyncEntityProdu
this.contentType = contentType;
}
+ /**
+ * Triggered to signal the ability of the underlying byte channel
+ * to accept more data. The data producer can choose to write data
+ * immediately inside the call or asynchronously at some later point.
+ *
+ * @param channel the data channel capable to accepting more data.
+ */
protected abstract void produceData(StreamChannel<ByteBuffer> channel) throws IOException;
@Override
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/AbstractBinDataConsumer.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/AbstractBinDataConsumer.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/AbstractBinDataConsumer.java
index e50c90d..8e33020 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/AbstractBinDataConsumer.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/AbstractBinDataConsumer.java
@@ -35,14 +35,34 @@ import org.apache.hc.core5.http.HttpException;
import org.apache.hc.core5.http.nio.AsyncDataConsumer;
import org.apache.hc.core5.http.nio.CapacityChannel;
+/**
+ * Abstract binary data consumer.
+ *
+ * @since 5.0
+ */
public abstract class AbstractBinDataConsumer implements AsyncDataConsumer {
private static final ByteBuffer EMPTY = ByteBuffer.wrap(new byte[0]);
+ /**
+ * Triggered to obtain the current capacity of the consumer.
+ *
+ * @return the number of bytes this consumer is prepared to process.
+ */
protected abstract int capacity();
- protected abstract void data(ByteBuffer data, boolean endOfStream) throws IOException;
+ /**
+ * Triggered to pass incoming data packet to the data consumer.
+ *
+ * @param src the data packet.
+ * @param endOfStream flag indicating whether this data packet is the last in the data stream.
+ *
+ */
+ protected abstract void data(ByteBuffer src, boolean endOfStream) throws IOException;
+ /**
+ * Triggered to signal completion of data processing.
+ */
protected abstract void completed() throws IOException;
@Override
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/AbstractCharAsyncEntityConsumer.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/AbstractCharAsyncEntityConsumer.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/AbstractCharAsyncEntityConsumer.java
index 828b43a..df452bc 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/AbstractCharAsyncEntityConsumer.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/AbstractCharAsyncEntityConsumer.java
@@ -40,15 +40,29 @@ import org.apache.hc.core5.http.nio.AsyncEntityConsumer;
import org.apache.hc.core5.util.Args;
/**
+ * Abstract text entity content consumer.
+ *
* @since 5.0
+ *
+ * @param <T> entity representation.
*/
public abstract class AbstractCharAsyncEntityConsumer<T> extends AbstractCharDataConsumer implements AsyncEntityConsumer<T> {
private volatile FutureCallback<T> resultCallback;
private volatile T content;
+ /**
+ * Triggered to signal beginning of entity content stream.
+ *
+ * @param contentType the entity content type
+ */
protected abstract void streamStart(ContentType contentType) throws HttpException, IOException;
+ /**
+ * Triggered to generate entity representation.
+ *
+ * @return the entity content
+ */
protected abstract T generateContent() throws IOException;
@Override
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/AbstractCharAsyncEntityProducer.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/AbstractCharAsyncEntityProducer.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/AbstractCharAsyncEntityProducer.java
index 2c434f9..b451e06 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/AbstractCharAsyncEntityProducer.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/AbstractCharAsyncEntityProducer.java
@@ -42,6 +42,8 @@ import org.apache.hc.core5.http.nio.StreamChannel;
import org.apache.hc.core5.util.Args;
/**
+ * Abstract text entity content producer.
+ *
* @since 5.0
*/
public abstract class AbstractCharAsyncEntityProducer implements AsyncEntityProducer {
@@ -93,6 +95,13 @@ public abstract class AbstractCharAsyncEntityProducer implements AsyncEntityProd
this.state = State.ACTIVE;
}
+ /**
+ * Triggered to signal the ability of the underlying char channel
+ * to accept more data. The data producer can choose to write data
+ * immediately inside the call or asynchronously at some later point.
+ *
+ * @param channel the data channel capable to accepting more data.
+ */
protected abstract void produceData(StreamChannel<CharBuffer> channel) throws IOException;
@Override
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/AbstractCharDataConsumer.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/AbstractCharDataConsumer.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/AbstractCharDataConsumer.java
index 2eeb50c..f8e27a9 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/AbstractCharDataConsumer.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/AbstractCharDataConsumer.java
@@ -40,6 +40,11 @@ import org.apache.hc.core5.http.HttpException;
import org.apache.hc.core5.http.nio.AsyncDataConsumer;
import org.apache.hc.core5.http.nio.CapacityChannel;
+/**
+ * Abstract text data consumer.
+ *
+ * @since 5.0
+ */
public abstract class AbstractCharDataConsumer implements AsyncDataConsumer {
private static final ByteBuffer EMPTY_BIN = ByteBuffer.wrap(new byte[0]);
@@ -49,10 +54,25 @@ public abstract class AbstractCharDataConsumer implements AsyncDataConsumer {
private volatile Charset charset = StandardCharsets.US_ASCII;
private volatile CharsetDecoder charsetDecoder;
+ /**
+ * Triggered to obtain the current capacity of the consumer.
+ *
+ * @return the number of bytes this consumer is prepared to process.
+ */
protected abstract int capacity();
- protected abstract void data(CharBuffer data, boolean endOfStream) throws IOException;
-
+ /**
+ * Triggered to pass incoming data packet to the data consumer.
+ *
+ * @param src the data packet.
+ * @param endOfStream flag indicating whether this data packet is the last in the data stream.
+ *
+ */
+ protected abstract void data(CharBuffer src, boolean endOfStream) throws IOException;
+
+ /**
+ * Triggered to signal completion of data processing.
+ */
protected abstract void completed() throws IOException;
protected final void setCharset(final Charset charset) {
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/BasicAsyncEntityConsumer.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/BasicAsyncEntityConsumer.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/BasicAsyncEntityConsumer.java
index c195f5e..f17100e 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/BasicAsyncEntityConsumer.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/BasicAsyncEntityConsumer.java
@@ -34,9 +34,14 @@ import org.apache.hc.core5.http.ContentType;
import org.apache.hc.core5.http.HttpException;
import org.apache.hc.core5.util.ByteArrayBuffer;
+/**
+ * Basic {@link org.apache.hc.core5.http.nio.AsyncEntityConsumer} implementation
+ * that processes the data stream content into a byte array.
+ *
+ * @since 5.0
+ */
public class BasicAsyncEntityConsumer extends AbstractBinAsyncEntityConsumer<byte[]> {
-
private final ByteArrayBuffer buffer;
public BasicAsyncEntityConsumer() {
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/BasicAsyncEntityProducer.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/BasicAsyncEntityProducer.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/BasicAsyncEntityProducer.java
index d87e079..605f72f 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/BasicAsyncEntityProducer.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/BasicAsyncEntityProducer.java
@@ -40,6 +40,9 @@ import org.apache.hc.core5.http.nio.DataStreamChannel;
import org.apache.hc.core5.util.Args;
/**
+ * Basic {@link AsyncEntityProducer} implementation that generates data stream
+ * from content of a byte array.
+ *
* @since 5.0
*/
public class BasicAsyncEntityProducer implements AsyncEntityProducer {
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/DigestingEntityConsumer.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/DigestingEntityConsumer.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/DigestingEntityConsumer.java
index 8901005..d1508e4 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/DigestingEntityConsumer.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/DigestingEntityConsumer.java
@@ -42,6 +42,10 @@ import org.apache.hc.core5.http.nio.CapacityChannel;
import org.apache.hc.core5.util.Args;
/**
+ * {@link AsyncEntityConsumer} decorator that calculates a digest hash from
+ * the data stream content and keeps the list of trailers received with
+ * the data stream.
+ *
* @since 5.0
*/
public class DigestingEntityConsumer<T> implements AsyncEntityConsumer<T> {
@@ -104,10 +108,20 @@ public class DigestingEntityConsumer<T> implements AsyncEntityConsumer<T> {
wrapped.releaseResources();
}
+ /**
+ * List of trailers sent with the data stream.
+ *
+ * @return the list of trailers sent with the data stream
+ */
public List<Header> getTrailers() {
return trailers != null ? new ArrayList<>(trailers) : null;
}
+ /**
+ * Returns digest hash.
+ *
+ * @return the digest hash value.
+ */
public byte[] getDigest() {
return digest;
}
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/DigestingEntityProducer.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/DigestingEntityProducer.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/DigestingEntityProducer.java
index ce55e82..37e5b6f 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/DigestingEntityProducer.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/DigestingEntityProducer.java
@@ -43,6 +43,9 @@ import org.apache.hc.core5.util.Args;
import org.apache.hc.core5.util.TextUtils;
/**
+ * {@link AsyncEntityProducer} decorator that calculates a digest hash from
+ * the data stream content and appends its value to the list of trailers.
+ *
* @since 5.0
*/
public class DigestingEntityProducer implements AsyncEntityProducer {
@@ -155,6 +158,11 @@ public class DigestingEntityProducer implements AsyncEntityProducer {
wrapped.releaseResources();
}
+ /**
+ * Returns digest hash.
+ *
+ * @return the digest hash value.
+ */
public byte[] getDigest() {
return digest;
}
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/FileEntityProducer.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/FileEntityProducer.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/FileEntityProducer.java
index 87782cf..a85b5a9 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/FileEntityProducer.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/FileEntityProducer.java
@@ -40,6 +40,9 @@ import org.apache.hc.core5.util.Args;
import org.apache.hc.core5.util.Asserts;
/**
+ * {@link AsyncEntityProducer} implementation that generates data stream
+ * from content of a {@link File}.
+ *
* @since 5.0
*/
public final class FileEntityProducer implements AsyncEntityProducer {
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/NoopEntityConsumer.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/NoopEntityConsumer.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/NoopEntityConsumer.java
index a42d8f5..c8083e0 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/NoopEntityConsumer.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/NoopEntityConsumer.java
@@ -38,6 +38,8 @@ import org.apache.hc.core5.http.nio.AsyncEntityConsumer;
import org.apache.hc.core5.http.nio.CapacityChannel;
/**
+ * No-op {@link AsyncEntityConsumer} that discards all data from the data stream.
+ *
* @since 5.0
*/
public final class NoopEntityConsumer implements AsyncEntityConsumer<Void> {
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/StringAsyncEntityConsumer.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/StringAsyncEntityConsumer.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/StringAsyncEntityConsumer.java
index 8da35e4..1bcda3e 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/StringAsyncEntityConsumer.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/StringAsyncEntityConsumer.java
@@ -34,6 +34,12 @@ import org.apache.hc.core5.http.HttpException;
import org.apache.hc.core5.util.Args;
import org.apache.hc.core5.util.CharArrayBuffer;
+/**
+ * Basic {@link org.apache.hc.core5.http.nio.AsyncEntityConsumer} implementation
+ * that processes the data stream content into a string.
+ *
+ * @since 5.0
+ */
public class StringAsyncEntityConsumer extends AbstractCharAsyncEntityConsumer<String> {
private final int capacityIncrement;
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/StringAsyncEntityProducer.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/StringAsyncEntityProducer.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/StringAsyncEntityProducer.java
index b89269d..6940a8c 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/StringAsyncEntityProducer.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/StringAsyncEntityProducer.java
@@ -35,6 +35,12 @@ import org.apache.hc.core5.http.nio.StreamChannel;
import org.apache.hc.core5.util.Args;
import org.apache.hc.core5.util.Asserts;
+/**
+ * Basic {@link org.apache.hc.core5.http.nio.AsyncDataProducer} implementation that
+ * generates data stream from content of a string.
+ *
+ * @since 5.0
+ */
public class StringAsyncEntityProducer extends AbstractCharAsyncEntityProducer {
private final CharBuffer content;
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/package-info.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/package-info.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/package-info.java
new file mode 100644
index 0000000..faeb090
--- /dev/null
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/entity/package-info.java
@@ -0,0 +1,31 @@
+/*
+ * ====================================================================
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ * ====================================================================
+ *
+ * This software consists of voluntary contributions made by many
+ * individuals on behalf of the Apache Software Foundation. For more
+ * information on the Apache Software Foundation, please see
+ * <http://www.apache.org/>.
+ *
+ */
+
+/**
+ * HTTP message entity APIs for the asynchronous (non-blocking) I/O model.
+ */
+package org.apache.hc.core5.http.nio.entity;
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/package-info.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/package-info.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/package-info.java
index 0101117..f3ea31c 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/package-info.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/package-info.java
@@ -26,8 +26,8 @@
*/
/**
- * Core HTTP component APIs and primitives for asynchronous, event
- * driven communication.
+ * Core HTTP transport APIs for for asynchronous, event
+ * driven I/O model.
* <p>
* The application programming interface is based on the concept
* of channels and event handlers. The channels act as conduits
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/ssl/FixedPortStrategy.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/ssl/FixedPortStrategy.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/ssl/FixedPortStrategy.java
index 09a1ef5..ea62106 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/ssl/FixedPortStrategy.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/ssl/FixedPortStrategy.java
@@ -33,6 +33,8 @@ import java.net.SocketAddress;
import org.apache.hc.core5.util.Args;
/**
+ * Basic implementation of {@link SecurePortStrategy} with a fixed list of secure ports.
+ *
* @since 5.0
*/
public final class FixedPortStrategy implements SecurePortStrategy {
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/ssl/SecurePortStrategy.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/ssl/SecurePortStrategy.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/ssl/SecurePortStrategy.java
index f30fe26..a06aa4b 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/ssl/SecurePortStrategy.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/ssl/SecurePortStrategy.java
@@ -36,6 +36,12 @@ import java.net.SocketAddress;
*/
public interface SecurePortStrategy {
+ /**
+ * Determines if the given address should be secured or considered secure.
+ * @param localAddress the given address.
+ *
+ * @return secure flag.
+ */
boolean isSecure(SocketAddress localAddress);
}
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/ssl/TlsStrategy.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/ssl/TlsStrategy.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/ssl/TlsStrategy.java
index a475510..b3c8636 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/ssl/TlsStrategy.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/ssl/TlsStrategy.java
@@ -33,14 +33,24 @@ import org.apache.hc.core5.http.HttpHost;
import org.apache.hc.core5.reactor.ssl.TransportSecurityLayer;
/**
- * TLS protocol upgrade strategy for non-blocking {@link TransportSecurityLayer} connections.
+ * TLS protocol upgrade strategy for non-blocking {@link TransportSecurityLayer} sessions.
*
* @since 5.0
*/
public interface TlsStrategy {
+ /**
+ * Secures current session layer with LTS security.
+ *
+ * @param sessionLayer the session layer
+ * @param host the name of the opposite endpoint when givem or {@code null} otherwise.
+ * @param localAddress the address of the local endpoint.
+ * @param remoteAddress the address of the remote endpoint.
+ * @param attachment arbitrary object passes to the TLS session initialization code.
+ * @return {@code true} if the session has been upgraded, {@code false} otherwise.
+ */
boolean upgrade(
- TransportSecurityLayer tlsSession,
+ TransportSecurityLayer sessionLayer,
HttpHost host,
SocketAddress localAddress,
SocketAddress remoteAddress,
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/ssl/package-info.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/ssl/package-info.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/ssl/package-info.java
new file mode 100644
index 0000000..409dd1f
--- /dev/null
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/ssl/package-info.java
@@ -0,0 +1,31 @@
+/*
+ * ====================================================================
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ * ====================================================================
+ *
+ * This software consists of voluntary contributions made by many
+ * individuals on behalf of the Apache Software Foundation. For more
+ * information on the Apache Software Foundation, please see
+ * <http://www.apache.org/>.
+ *
+ */
+
+/**
+ * TLS protocol support.
+ */
+package org.apache.hc.core5.http.nio.ssl;
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/AbstractAsyncPushHandler.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/AbstractAsyncPushHandler.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/AbstractAsyncPushHandler.java
index 8f02837..7596d17 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/AbstractAsyncPushHandler.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/AbstractAsyncPushHandler.java
@@ -43,8 +43,11 @@ import org.apache.hc.core5.http.protocol.HttpContext;
import org.apache.hc.core5.util.Args;
/**
- * @param <T> the future result type returned by a callback.
+ * Abstract push response handler.
+ *
* @since 5.0
+ *
+ * @param <T> response message representation.
*/
public abstract class AbstractAsyncPushHandler<T> implements AsyncPushConsumer {
@@ -54,15 +57,26 @@ public abstract class AbstractAsyncPushHandler<T> implements AsyncPushConsumer {
this.responseConsumer = Args.notNull(responseConsumer, "Response consumer");
}
+ /**
+ * Triggered to handle the push message with the given promised request.
+ *
+ * @param promise the promised request message.
+ * @param responseMessage the pushed response message.
+ */
protected abstract void handleResponse(
final HttpRequest promise, final T responseMessage) throws IOException, HttpException;
+ /**
+ * Triggered to handle the exception thrown while processing a push response.
+ *
+ * @param promise the promised request message.
+ * @param cause the cause of error.
+ */
protected void handleError(final HttpRequest promise, final Exception cause) {
- // empty
}
@Override
- public void consumePromise(
+ public final void consumePromise(
final HttpRequest promise,
final HttpResponse response,
final EntityDetails entityDetails,
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/AbstractAsyncRequesterConsumer.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/AbstractAsyncRequesterConsumer.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/AbstractAsyncRequesterConsumer.java
index 52056c4..615e639 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/AbstractAsyncRequesterConsumer.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/AbstractAsyncRequesterConsumer.java
@@ -43,6 +43,15 @@ import org.apache.hc.core5.http.nio.CapacityChannel;
import org.apache.hc.core5.http.protocol.HttpContext;
import org.apache.hc.core5.util.Args;
+/**
+ * Abstract asynchronous request consumer that makes use of {@link AsyncEntityConsumer}
+ * to process request message content.
+ *
+ * @param <T> request processing result representation.
+ * @param <E> request entity representation.
+ *
+ * @since 5.0
+ */
public abstract class AbstractAsyncRequesterConsumer<T, E> implements AsyncRequestConsumer<T> {
private final AsyncEntityConsumer<E> entityConsumer;
@@ -54,6 +63,13 @@ public abstract class AbstractAsyncRequesterConsumer<T, E> implements AsyncReque
this.entityConsumer = entityConsumer;
}
+ /**
+ * Triggered to generate object that represents a result of request message processing.
+ * @param request the request message.
+ * @param entity the request entity.
+ * @param contentType the request content type.
+ * @return the result of request processing.
+ */
protected abstract T buildResult(HttpRequest request, E entity, ContentType contentType);
@Override
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/AbstractAsyncResponseConsumer.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/AbstractAsyncResponseConsumer.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/AbstractAsyncResponseConsumer.java
index 96dfcbb..15568c7 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/AbstractAsyncResponseConsumer.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/AbstractAsyncResponseConsumer.java
@@ -44,6 +44,15 @@ import org.apache.hc.core5.http.nio.CapacityChannel;
import org.apache.hc.core5.http.protocol.HttpContext;
import org.apache.hc.core5.util.Args;
+/**
+ * Abstract asynchronous response consumer that makes use of {@link AsyncEntityConsumer}
+ * to process response message content.
+ *
+ * @param <T> response processing result representation.
+ * @param <E> response entity representation.
+ *
+ * @since 5.0
+ */
public abstract class AbstractAsyncResponseConsumer<T, E> implements AsyncResponseConsumer<T> {
private final AsyncEntityConsumer<E> entityConsumer;
@@ -57,6 +66,13 @@ public abstract class AbstractAsyncResponseConsumer<T, E> implements AsyncRespon
this.exceptionRef = new AtomicReference<>(null);
}
+ /**
+ * Triggered to generate object that represents a result of response message processing.
+ * @param response the response message.
+ * @param entity the response entity.
+ * @param contentType the response content type.
+ * @return the result of response processing.
+ */
protected abstract T buildResult(HttpResponse response, E entity, ContentType contentType);
@Override
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/AbstractAsyncServerAuthFilter.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/AbstractAsyncServerAuthFilter.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/AbstractAsyncServerAuthFilter.java
index 24ccd01..b90d4c0 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/AbstractAsyncServerAuthFilter.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/AbstractAsyncServerAuthFilter.java
@@ -51,6 +51,10 @@ import org.apache.hc.core5.http.protocol.HttpContext;
import org.apache.hc.core5.net.URIAuthority;
/**
+ * Abstract asynchronous HTTP request filter that implements standard HTTP authentication handshake.
+ *
+ * @param <T> authorization token representation.
+ *
* @since 5.0
*/
@Contract(threading = ThreadingBehavior.STATELESS)
@@ -62,18 +66,54 @@ public abstract class AbstractAsyncServerAuthFilter<T> implements AsyncFilterHan
this.respondImmediately = respondImmediately;
}
+ /**
+ * Parses authorization header value into an authentication token sent by the client
+ * as a response to an authentication challenge.
+ *
+ * @param authorizationValue the authorization header value.
+ * @param context the actual execution context.
+ * @return authorization token
+ */
protected abstract T parseChallengeResponse(String authorizationValue, HttpContext context) throws HttpException;
+ /**
+ * Authenticates the client using the authentication token sent by the client
+ * as a response to an authentication challenge.
+ *
+ * @param challengeResponse the authentication token sent by the client
+ * as a response to an authentication challenge.
+ * @param authority the URI authority.
+ * @param requestUri the request URI.
+ * @param context the actual execution context.
+ * @return {@code true} if the client could be successfully authenticated {@code false} otherwise.
+ */
protected abstract boolean authenticate(T challengeResponse, URIAuthority authority, String requestUri, HttpContext context);
+ /**
+ * Generates an authentication challenge in case of unsuccessful authentication.
+ *
+ * @param challengeResponse the authentication token sent by the client
+ * as a response to an authentication challenge
+ * or {@code null} if the client has not sent any.
+ * @param authority the URI authority.
+ * @param requestUri the request URI.
+ * @param context the actual execution context.
+ * @return an authorization challenge value.
+ */
protected abstract String generateChallenge(T challengeResponse, URIAuthority authority, String requestUri, HttpContext context);
+ /**
+ * Generates response body for UNAUTHORIZED response.
+ *
+ * @param unauthorized the response to return as a result of authentication failure.
+ * @return the response content entity.
+ */
protected AsyncEntityProducer generateResponseContent(final HttpResponse unauthorized) {
return new BasicAsyncEntityProducer("Unauthorized");
}
@Override
- public AsyncDataConsumer handle(
+ public final AsyncDataConsumer handle(
final HttpRequest request,
final EntityDetails entityDetails,
final HttpContext context,
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/AbstractServerExchangeHandler.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/AbstractServerExchangeHandler.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/AbstractServerExchangeHandler.java
index 1ebdbba..77610bb 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/AbstractServerExchangeHandler.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/AbstractServerExchangeHandler.java
@@ -51,6 +51,8 @@ import org.apache.hc.core5.http.protocol.HttpContext;
import org.apache.hc.core5.util.Asserts;
/**
+ * Abstract server side message exchange handler.
+ *
* @since 5.0
*/
public abstract class AbstractServerExchangeHandler<T> implements AsyncServerExchangeHandler {
@@ -63,11 +65,28 @@ public abstract class AbstractServerExchangeHandler<T> implements AsyncServerExc
this.responseProducerRef = new AtomicReference<>(null);
}
+ /**
+ * Triggered to supply a request consumer to process the incoming request.
+ * @param request the request message.
+ * @param entityDetails the request entity details.
+ * @param context the actual execution context.
+ * @return the request consumer.
+ */
protected abstract AsyncRequestConsumer<T> supplyConsumer(
HttpRequest request,
EntityDetails entityDetails,
HttpContext context) throws HttpException;
+ /**
+ * Triggered to handles the request object produced by the {@link AsyncRequestConsumer} returned
+ * from the {@link #supplyConsumer(HttpRequest, EntityDetails, HttpContext)} method. The handler
+ * can choose to send response messages immediately inside the call or asynchronously
+ * at some later point.
+ *
+ * @param requestMessage the request message.
+ * @param responseTrigger the response trigger.
+ * @param context the actual execution context.
+ */
protected abstract void handle(
T requestMessage,
AsyncServerRequestHandler.ResponseTrigger responseTrigger,
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/AsyncServerExpectationFilter.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/AsyncServerExpectationFilter.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/AsyncServerExpectationFilter.java
index 242641b..d4e9dc7 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/AsyncServerExpectationFilter.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/AsyncServerExpectationFilter.java
@@ -59,7 +59,7 @@ public class AsyncServerExpectationFilter implements AsyncFilterHandler {
}
@Override
- public AsyncDataConsumer handle(
+ public final AsyncDataConsumer handle(
final HttpRequest request,
final EntityDetails entityDetails,
final HttpContext context,
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/AsyncServerFilterChainElement.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/AsyncServerFilterChainElement.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/AsyncServerFilterChainElement.java
index d423ecc..3e64c5e 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/AsyncServerFilterChainElement.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/AsyncServerFilterChainElement.java
@@ -37,6 +37,11 @@ import org.apache.hc.core5.http.nio.AsyncFilterChain;
import org.apache.hc.core5.http.nio.AsyncFilterHandler;
import org.apache.hc.core5.http.protocol.HttpContext;
+/**
+ * An element in an asynchronous request processing chain.
+ *
+ * @since 5.0
+ */
public final class AsyncServerFilterChainElement {
private final AsyncFilterHandler handler;
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/AsyncServerFilterChainExchangeHandlerFactory.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/AsyncServerFilterChainExchangeHandlerFactory.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/AsyncServerFilterChainExchangeHandlerFactory.java
index c70a8c3..0291db5 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/AsyncServerFilterChainExchangeHandlerFactory.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/AsyncServerFilterChainExchangeHandlerFactory.java
@@ -52,6 +52,12 @@ import org.apache.hc.core5.http.protocol.HttpContext;
import org.apache.hc.core5.util.Args;
import org.apache.hc.core5.util.Asserts;
+/**
+ * Factory for {@link AsyncServerExchangeHandler} instances that delegate request processing
+ * to a {@link AsyncServerFilterChainElement}.
+ *
+ * @since 5.0
+ */
public final class AsyncServerFilterChainExchangeHandlerFactory implements HandlerFactory<AsyncServerExchangeHandler> {
private final AsyncServerFilterChainElement filterChain;
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/BasicAsyncServerExpectationDecorator.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/BasicAsyncServerExpectationDecorator.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/BasicAsyncServerExpectationDecorator.java
index 7fecddc..79fb5a9 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/BasicAsyncServerExpectationDecorator.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/BasicAsyncServerExpectationDecorator.java
@@ -47,6 +47,10 @@ import org.apache.hc.core5.http.protocol.HttpContext;
import org.apache.hc.core5.util.Args;
/**
+ * {@link AsyncServerExchangeHandler} implementation that adds support
+ * for the Expect-Continue handshake to an existing
+ * {@link AsyncServerExchangeHandler}.
+ *
* @since 5.0
*/
public class BasicAsyncServerExpectationDecorator implements AsyncServerExchangeHandler {
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/BasicClientExchangeHandler.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/BasicClientExchangeHandler.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/BasicClientExchangeHandler.java
index f143321..68d03b2 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/BasicClientExchangeHandler.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/BasicClientExchangeHandler.java
@@ -47,9 +47,13 @@ import org.apache.hc.core5.http.protocol.HttpContext;
import org.apache.hc.core5.util.Args;
/**
+ * Basic {@link AsyncClientExchangeHandler} implementation that makes use
+ * of {@link AsyncRequestProducer} to generate request message
+ * and {@link AsyncResponseConsumer} to process the response message returned by the server.
+ *
* @since 5.0
*/
-public class BasicClientExchangeHandler<T> implements AsyncClientExchangeHandler {
+public final class BasicClientExchangeHandler<T> implements AsyncClientExchangeHandler {
private final AsyncRequestProducer requestProducer;
private final AsyncResponseConsumer<T> responseConsumer;
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/BasicServerExchangeHandler.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/BasicServerExchangeHandler.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/BasicServerExchangeHandler.java
index 85f2a3b..38aba92 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/BasicServerExchangeHandler.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/BasicServerExchangeHandler.java
@@ -37,6 +37,9 @@ import org.apache.hc.core5.http.protocol.HttpContext;
import org.apache.hc.core5.util.Args;
/**
+ * Basic {@link AbstractServerExchangeHandler} implementation that delegates
+ * request processing and response generation to a {@link AsyncServerRequestHandler}.
+ *
* @since 5.0
*/
public class BasicServerExchangeHandler<T> extends AbstractServerExchangeHandler<T> {
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/DefaultAsyncResponseExchangeHandlerFactory.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/DefaultAsyncResponseExchangeHandlerFactory.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/DefaultAsyncResponseExchangeHandlerFactory.java
index 1097a08..da8b6e9 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/DefaultAsyncResponseExchangeHandlerFactory.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/DefaultAsyncResponseExchangeHandlerFactory.java
@@ -39,6 +39,10 @@ import org.apache.hc.core5.http.protocol.HttpContext;
import org.apache.hc.core5.util.Args;
/**
+ * Factory for {@link AsyncServerExchangeHandler} instances that make use
+ * of {@link HttpRequestMapper} to dispatch
+ * the request to a particular {@link AsyncServerExchangeHandler} for processing.
+ *
* @since 5.0
*/
public final class DefaultAsyncResponseExchangeHandlerFactory implements HandlerFactory<AsyncServerExchangeHandler> {
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/ImmediateResponseExchangeHandler.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/ImmediateResponseExchangeHandler.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/ImmediateResponseExchangeHandler.java
index 6cbfe89..6fc66f5 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/ImmediateResponseExchangeHandler.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/ImmediateResponseExchangeHandler.java
@@ -48,6 +48,10 @@ import org.apache.hc.core5.http.protocol.HttpContext;
import org.apache.hc.core5.util.Args;
/**
+ * {@link AsyncServerExchangeHandler} implementation that immediately responds
+ * with a predefined response generated by a {@link AsyncResponseProducer} and
+ * ignores any entity content enclosed in the request message.
+ *
* @since 5.0
*/
public final class ImmediateResponseExchangeHandler implements AsyncServerExchangeHandler {
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/TerminalAsyncServerFilter.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/TerminalAsyncServerFilter.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/TerminalAsyncServerFilter.java
index efc9804..f45fa83 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/TerminalAsyncServerFilter.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/TerminalAsyncServerFilter.java
@@ -51,6 +51,10 @@ import org.apache.hc.core5.http.protocol.HttpContext;
import org.apache.hc.core5.util.Args;
/**
+ * {@link AsyncFilterHandler} implementation represents a terminal handler
+ * in an asynchronous request processing pipeline that makes use of {@link HandlerFactory}
+ * to dispatch the request to a particular {@link AsyncServerExchangeHandler}.
+ *
* @since 5.0
*/
@Contract(threading = ThreadingBehavior.STATELESS)
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/classic/AbstractClassicEntityConsumer.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/classic/AbstractClassicEntityConsumer.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/classic/AbstractClassicEntityConsumer.java
index 782b0d2..4d068a0 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/classic/AbstractClassicEntityConsumer.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/classic/AbstractClassicEntityConsumer.java
@@ -45,6 +45,12 @@ import org.apache.hc.core5.http.nio.CapacityChannel;
import org.apache.hc.core5.util.Args;
/**
+ * {@link AsyncEntityConsumer} implementation that acts as a compatibility
+ * layer for classic {@link InputStream} based interfaces. Blocking input
+ * processing is executed through an {@link Executor}.
+ *
+ * @param <T> entity representation.
+ *
* @since 5.0
*/
public abstract class AbstractClassicEntityConsumer<T> implements AsyncEntityConsumer<T> {
@@ -65,6 +71,13 @@ public abstract class AbstractClassicEntityConsumer<T> implements AsyncEntityCon
this.exceptionRef = new AtomicReference<>(null);
}
+ /**
+ * Processes entity data from the given stream.
+ *
+ * @param contentType the entity content type
+ * @param inputStream the input stream
+ * @return the result of entity processing.
+ */
protected abstract T consumeData(ContentType contentType, InputStream inputStream) throws IOException;
@Override
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/classic/AbstractClassicEntityProducer.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/classic/AbstractClassicEntityProducer.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/classic/AbstractClassicEntityProducer.java
index 5ca791f..f9d320a 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/classic/AbstractClassicEntityProducer.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/classic/AbstractClassicEntityProducer.java
@@ -38,6 +38,10 @@ import org.apache.hc.core5.http.nio.DataStreamChannel;
import org.apache.hc.core5.util.Args;
/**
+ * {@link AsyncEntityProducer} implementation that acts as a compatibility
+ * layer for classic {@link OutputStream} based interfaces. Blocking output
+ * processing is executed through an {@link Executor}.
+ *
* @since 5.0
*/
public abstract class AbstractClassicEntityProducer implements AsyncEntityProducer {
@@ -58,13 +62,19 @@ public abstract class AbstractClassicEntityProducer implements AsyncEntityProduc
this.exception = new AtomicReference<>(null);
}
+ /**
+ * Writes out entity data into the given stream.
+ *
+ * @param contentType the entity content type
+ * @param outputStream the output stream
+ */
+ protected abstract void produceData(ContentType contentType, OutputStream outputStream) throws IOException;
+
@Override
public final boolean isRepeatable() {
return false;
}
- protected abstract void produceData(ContentType contentType, OutputStream outputStream) throws IOException;
-
@Override
public final int available() {
return buffer.length();
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/e0592bd2/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/classic/AbstractClassicServerExchangeHandler.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/classic/AbstractClassicServerExchangeHandler.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/classic/AbstractClassicServerExchangeHandler.java
index 78ae034..87d2492 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/classic/AbstractClassicServerExchangeHandler.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/classic/AbstractClassicServerExchangeHandler.java
@@ -56,6 +56,10 @@ import org.apache.hc.core5.util.Args;
import org.apache.hc.core5.util.Asserts;
/**
+ * {@link AsyncServerExchangeHandler} implementation that acts as a compatibility
+ * layer for classic {@link InputStream} / {@link OutputStream} based interfaces.
+ * Blocking input / output processing is executed through an {@link Executor}.
+ *
* @since 5.0
*/
public abstract class AbstractClassicServerExchangeHandler implements AsyncServerExchangeHandler {
@@ -77,15 +81,26 @@ public abstract class AbstractClassicServerExchangeHandler implements AsyncServe
this.state = new AtomicReference<>(State.IDLE);
}
- public Exception getException() {
- return exception.get();
- }
-
+ /**
+ * Handles an incoming request optionally reading its entity content form the given input stream
+ * and generates a response optionally writing out its entity content into the given output stream.
+ *
+ * @param request the incoming request
+ * @param requestStream the request stream if the request encloses an entity,
+ * {@code null} otherwise.
+ * @param response the outgoing response.
+ * @param responseStream the response entity output stream.
+ * @param context the actual execution context.
+ */
protected abstract void handle(
HttpRequest request, InputStream requestStream,
HttpResponse response, OutputStream responseStream,
HttpContext context) throws IOException, HttpException;
+ public Exception getException() {
+ return exception.get();
+ }
+
@Override
public final void handleRequest(
final HttpRequest request,