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/25 17:14:31 UTC
[5/6] httpcomponents-core git commit: Javadocs for core HTTP APIs
Javadocs for core HTTP APIs
Project: http://git-wip-us.apache.org/repos/asf/httpcomponents-core/repo
Commit: http://git-wip-us.apache.org/repos/asf/httpcomponents-core/commit/0679d155
Tree: http://git-wip-us.apache.org/repos/asf/httpcomponents-core/tree/0679d155
Diff: http://git-wip-us.apache.org/repos/asf/httpcomponents-core/diff/0679d155
Branch: refs/heads/master
Commit: 0679d1555ec610efc6fcb0539ac22a8b2d99da55
Parents: d7d4f0b
Author: Oleg Kalnichevski <ol...@apache.org>
Authored: Fri Aug 10 17:18:17 2018 +0200
Committer: Oleg Kalnichevski <ol...@apache.org>
Committed: Sat Aug 25 19:04:52 2018 +0200
----------------------------------------------------------------------
.../hc/core5/http/config/CharCodingConfig.java | 2 +-
.../core5/http/impl/BasicEndpointDetails.java | 2 +-
.../hc/core5/http/impl/BasicEntityDetails.java | 2 +-
.../http/impl/BasicHttpConnectionMetrics.java | 2 +-
.../core5/http/impl/DefaultAddressResolver.java | 5 ++
.../hc/core5/http/impl/Http1StreamListener.java | 2 +
.../hc/core5/http/impl/HttpProcessors.java | 42 ++++++++++++++
.../core5/http/impl/IncomingEntityDetails.java | 2 +
.../http/impl/bootstrap/AsyncRequester.java | 7 +++
.../impl/bootstrap/AsyncRequesterBootstrap.java | 2 +
.../core5/http/impl/bootstrap/AsyncServer.java | 5 ++
.../impl/bootstrap/AsyncServerBootstrap.java | 2 +
.../core5/http/impl/bootstrap/FilterEntry.java | 2 +-
.../http/impl/bootstrap/HttpAsyncRequester.java | 7 +++
.../http/impl/bootstrap/HttpAsyncServer.java | 7 +++
.../http/impl/bootstrap/HttpRequester.java | 7 +++
.../core5/http/impl/bootstrap/HttpServer.java | 4 ++
.../http/impl/bootstrap/RequestListener.java | 5 +-
.../http/impl/bootstrap/RequesterBootstrap.java | 4 +-
.../http/impl/bootstrap/ServerBootstrap.java | 4 +-
.../http/impl/bootstrap/StandardFilters.java | 6 ++
.../hc/core5/http/impl/bootstrap/Worker.java | 3 -
.../http/impl/bootstrap/WorkerPoolExecutor.java | 3 -
.../core5/http/impl/bootstrap/package-info.java | 2 +-
.../hc/core5/http/impl/io/package-info.java | 4 +-
.../impl/nio/ClientHttp1IOEventHandler.java | 8 +--
.../nio/ClientHttp1IOEventHandlerFactory.java | 4 +-
.../impl/nio/ClientHttp1StreamDuplexer.java | 9 +++
.../nio/ClientHttp1StreamDuplexerFactory.java | 6 +-
.../impl/nio/HttpConnectionEventHandler.java | 7 +++
.../impl/nio/ServerHttp1IOEventHandler.java | 4 +-
.../nio/ServerHttp1IOEventHandlerFactory.java | 4 +-
.../impl/nio/ServerHttp1StreamDuplexer.java | 9 +++
.../nio/ServerHttp1StreamDuplexerFactory.java | 6 +-
.../hc/core5/http/impl/nio/ServerSupport.java | 5 ++
.../hc/core5/http/impl/nio/package-info.java | 32 +++++++++++
.../apache/hc/core5/http/impl/package-info.java | 3 +-
.../hc/core5/http/io/HttpFilterChain.java | 23 ++++++++
.../hc/core5/http/io/HttpFilterHandler.java | 15 +++++
.../io/HttpResponseInformationCallback.java | 2 +-
.../core5/http/io/HttpServerRequestHandler.java | 28 +++++++++
.../apache/hc/core5/http/io/SocketConfig.java | 2 +-
.../io/entity/AbstractImmutableHttpEntity.java | 2 +-
.../hc/core5/http/io/entity/EntityUtils.java | 2 +-
.../hc/core5/http/io/entity/package-info.java | 2 +-
.../apache/hc/core5/http/io/package-info.java | 3 +-
.../support/AbstractHttpServerAuthFilter.java | 40 +++++++++++++
.../BasicHttpServerExpectationDecorator.java | 13 +++++
.../support/BasicHttpServerRequestHandler.java | 4 ++
.../io/support/HttpServerExpectationFilter.java | 19 +++++++
.../support/HttpServerFilterChainElement.java | 5 ++
.../HttpServerFilterChainRequestHandler.java | 3 +
.../http/io/support/TerminalServerFilter.java | 8 ++-
.../hc/core5/http/io/support/package-info.java | 31 ++++++++++
.../hc/core5/http/message/MessageSupport.java | 2 +-
.../http/nio/AsyncClientExchangeHandler.java | 32 ++++++++++-
.../http/nio/AsyncDataExchangeHandler.java | 5 ++
.../hc/core5/http/nio/AsyncEntityConsumer.java | 19 +++++++
.../hc/core5/http/nio/AsyncEntityProducer.java | 5 ++
.../hc/core5/http/nio/AsyncFilterChain.java | 31 ++++++++++
.../hc/core5/http/nio/AsyncFilterHandler.java | 21 +++++++
.../hc/core5/http/nio/AsyncPushConsumer.java | 18 +++++-
.../hc/core5/http/nio/AsyncPushProducer.java | 17 +++++-
.../hc/core5/http/nio/AsyncRequestConsumer.java | 27 ++++++++-
.../hc/core5/http/nio/AsyncRequestProducer.java | 21 ++++++-
.../core5/http/nio/AsyncResponseConsumer.java | 35 +++++++++++-
.../core5/http/nio/AsyncResponseProducer.java | 16 +++++-
.../http/nio/AsyncServerExchangeHandler.java | 11 ++++
.../http/nio/AsyncServerRequestHandler.java | 60 ++++++++++++++++++--
.../hc/core5/http/nio/BasicPushProducer.java | 3 +
.../hc/core5/http/nio/BasicRequestConsumer.java | 3 +
.../hc/core5/http/nio/BasicRequestProducer.java | 6 ++
.../core5/http/nio/BasicResponseConsumer.java | 4 ++
.../core5/http/nio/BasicResponseProducer.java | 3 +
.../hc/core5/http/nio/CapacityChannel.java | 2 +-
.../hc/core5/http/nio/DataStreamChannel.java | 2 +-
.../hc/core5/http/nio/HandlerFactory.java | 10 +++-
.../hc/core5/http/nio/RequestChannel.java | 9 ++-
.../hc/core5/http/nio/ResponseChannel.java | 28 ++++++++-
.../http/nio/command/ExecutableCommand.java | 6 +-
.../nio/command/RequestExecutionCommand.java | 2 +
.../core5/http/nio/command/ShutdownCommand.java | 4 +-
.../hc/core5/http/nio/command/package-info.java | 31 ++++++++++
.../entity/AbstractBinAsyncEntityConsumer.java | 17 ++++++
.../entity/AbstractBinAsyncEntityProducer.java | 9 +++
.../nio/entity/AbstractBinDataConsumer.java | 22 ++++++-
.../entity/AbstractCharAsyncEntityConsumer.java | 14 +++++
.../entity/AbstractCharAsyncEntityProducer.java | 9 +++
.../nio/entity/AbstractCharDataConsumer.java | 24 +++++++-
.../nio/entity/BasicAsyncEntityConsumer.java | 7 ++-
.../nio/entity/BasicAsyncEntityProducer.java | 3 +
.../nio/entity/DigestingEntityConsumer.java | 14 +++++
.../nio/entity/DigestingEntityProducer.java | 8 +++
.../http/nio/entity/FileEntityProducer.java | 3 +
.../http/nio/entity/NoopEntityConsumer.java | 2 +
.../nio/entity/StringAsyncEntityConsumer.java | 6 ++
.../nio/entity/StringAsyncEntityProducer.java | 6 ++
.../hc/core5/http/nio/entity/package-info.java | 31 ++++++++++
.../apache/hc/core5/http/nio/package-info.java | 3 +-
.../core5/http/nio/ssl/FixedPortStrategy.java | 2 +
.../core5/http/nio/ssl/SecurePortStrategy.java | 6 ++
.../hc/core5/http/nio/ssl/TlsStrategy.java | 14 ++++-
.../hc/core5/http/nio/ssl/package-info.java | 31 ++++++++++
.../nio/support/AbstractAsyncPushHandler.java | 20 ++++++-
.../support/AbstractAsyncRequesterConsumer.java | 16 ++++++
.../support/AbstractAsyncResponseConsumer.java | 16 ++++++
.../support/AbstractAsyncServerAuthFilter.java | 42 +++++++++++++-
.../support/AbstractServerExchangeHandler.java | 19 +++++++
.../support/AsyncServerExpectationFilter.java | 2 +-
.../support/AsyncServerFilterChainElement.java | 5 ++
...ServerFilterChainExchangeHandlerFactory.java | 6 ++
.../BasicAsyncServerExpectationDecorator.java | 4 ++
.../nio/support/BasicClientExchangeHandler.java | 6 +-
.../nio/support/BasicServerExchangeHandler.java | 3 +
...aultAsyncResponseExchangeHandlerFactory.java | 4 ++
.../ImmediateResponseExchangeHandler.java | 4 ++
.../nio/support/TerminalAsyncServerFilter.java | 4 ++
.../classic/AbstractClassicEntityConsumer.java | 13 +++++
.../classic/AbstractClassicEntityProducer.java | 14 ++++-
.../AbstractClassicServerExchangeHandler.java | 23 ++++++--
.../http/nio/support/classic/package-info.java | 32 +++++++++++
.../hc/core5/http/nio/support/package-info.java | 31 ++++++++++
.../org/apache/hc/core5/http/package-info.java | 2 +-
.../http/protocol/RequestHandlerRegistry.java | 9 ++-
.../hc/core5/http/protocol/package-info.java | 3 +-
.../org/apache/hc/core5/reactor/Command.java | 3 +-
.../hc/core5/reactor/ProtocolIOSession.java | 2 +-
127 files changed, 1285 insertions(+), 94 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/config/CharCodingConfig.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/config/CharCodingConfig.java b/httpcore5/src/main/java/org/apache/hc/core5/http/config/CharCodingConfig.java
index cebf584..5c9e749 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/config/CharCodingConfig.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/config/CharCodingConfig.java
@@ -36,7 +36,7 @@ import org.apache.hc.core5.annotation.ThreadingBehavior;
import org.apache.hc.core5.util.Args;
/**
- * HTTP/1.1 connection configuration.
+ * HTTP/1.1 char coding configuration.
*
* @since 4.3
*/
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/impl/BasicEndpointDetails.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/BasicEndpointDetails.java b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/BasicEndpointDetails.java
index 154879f..f312bff 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/BasicEndpointDetails.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/BasicEndpointDetails.java
@@ -37,7 +37,7 @@ import org.apache.hc.core5.http.HttpConnectionMetrics;
*
* @since 5.0
*/
-public class BasicEndpointDetails extends EndpointDetails {
+public final class BasicEndpointDetails extends EndpointDetails {
private final HttpConnectionMetrics metrics;
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/impl/BasicEntityDetails.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/BasicEntityDetails.java b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/BasicEntityDetails.java
index fb6179b..597449e 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/BasicEntityDetails.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/BasicEntityDetails.java
@@ -37,7 +37,7 @@ import org.apache.hc.core5.http.ContentType;
*
* @since 5.0
*/
-public class BasicEntityDetails implements EntityDetails {
+public final class BasicEntityDetails implements EntityDetails {
private final long len;
private final ContentType contentType;
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/impl/BasicHttpConnectionMetrics.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/BasicHttpConnectionMetrics.java b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/BasicHttpConnectionMetrics.java
index dbad586..6b51631 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/BasicHttpConnectionMetrics.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/BasicHttpConnectionMetrics.java
@@ -37,7 +37,7 @@ import org.apache.hc.core5.http.io.HttpTransportMetrics;
*
* @since 4.0
*/
-public class BasicHttpConnectionMetrics implements HttpConnectionMetrics {
+public final class BasicHttpConnectionMetrics implements HttpConnectionMetrics {
private final HttpTransportMetrics inTransportMetric;
private final HttpTransportMetrics outTransportMetric;
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/impl/DefaultAddressResolver.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/DefaultAddressResolver.java b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/DefaultAddressResolver.java
index e1563d3..9346abb 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/DefaultAddressResolver.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/DefaultAddressResolver.java
@@ -33,6 +33,11 @@ import org.apache.hc.core5.function.Resolver;
import org.apache.hc.core5.http.HttpHost;
import org.apache.hc.core5.http.URIScheme;
+/**
+ * Default {@link HttpHost} to {@link InetSocketAddress} resolver.
+ *
+ * @since 5.0
+ */
public final class DefaultAddressResolver implements Resolver<HttpHost, InetSocketAddress> {
public static final DefaultAddressResolver INSTANCE = new DefaultAddressResolver();
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/impl/Http1StreamListener.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/Http1StreamListener.java b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/Http1StreamListener.java
index 3741d3a..f1ce523 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/Http1StreamListener.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/Http1StreamListener.java
@@ -27,6 +27,7 @@
package org.apache.hc.core5.http.impl;
import org.apache.hc.core5.annotation.Contract;
+import org.apache.hc.core5.annotation.Internal;
import org.apache.hc.core5.annotation.ThreadingBehavior;
import org.apache.hc.core5.http.HttpConnection;
import org.apache.hc.core5.http.HttpRequest;
@@ -38,6 +39,7 @@ import org.apache.hc.core5.http.HttpResponse;
* @since 5.0
*/
@Contract(threading = ThreadingBehavior.STATELESS)
+@Internal
public interface Http1StreamListener {
void onRequestHead(HttpConnection connection, HttpRequest request);
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/impl/HttpProcessors.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/HttpProcessors.java b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/HttpProcessors.java
index 803b679..d21c812 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/HttpProcessors.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/HttpProcessors.java
@@ -42,12 +42,21 @@ import org.apache.hc.core5.util.TextUtils;
import org.apache.hc.core5.util.VersionInfo;
/**
+ * Factory class for standard {@link HttpProcessor} instances.
+ *
* @since 5.0
*/
public final class HttpProcessors {
private final static String SOFTWARE = "Apache-HttpCore";
+ /**
+ * Creates {@link HttpProcessorBuilder} initialized with default protocol interceptors
+ * for server side HTTP/1.1 processing.
+ *
+ * @param serverInfo the server info text or {@code null} for default.
+ * @return the processor builder.
+ */
public static HttpProcessorBuilder customServer(final String serverInfo) {
return HttpProcessorBuilder.create()
.addAll(
@@ -60,14 +69,34 @@ public final class HttpProcessors {
new RequestValidateHost());
}
+ /**
+ * Creates {@link HttpProcessor} initialized with default protocol interceptors
+ * for server side HTTP/1.1 processing.
+ *
+ * @param serverInfo the server info text or {@code null} for default.
+ * @return the processor.
+ */
public static HttpProcessor server(final String serverInfo) {
return customServer(serverInfo).build();
}
+ /**
+ * Creates {@link HttpProcessor} initialized with default protocol interceptors
+ * for server side HTTP/1.1 processing.
+ *
+ * @return the processor.
+ */
public static HttpProcessor server() {
return customServer(null).build();
}
+ /**
+ * Creates {@link HttpProcessorBuilder} initialized with default protocol interceptors
+ * for client side HTTP/1.1 processing.
+ *
+ * @param agentInfo the agent info text or {@code null} for default.
+ * @return the processor builder.
+ */
public static HttpProcessorBuilder customClient(final String agentInfo) {
return HttpProcessorBuilder.create()
.addAll(
@@ -79,10 +108,23 @@ public final class HttpProcessors {
new RequestExpectContinue());
}
+ /**
+ * Creates {@link HttpProcessor} initialized with default protocol interceptors
+ * for client side HTTP/1.1 processing.
+ *
+ * @param agentInfo the agent info text or {@code null} for default.
+ * @return the processor.
+ */
public static HttpProcessor client(final String agentInfo) {
return customClient(agentInfo).build();
}
+ /**
+ * Creates {@link HttpProcessor} initialized with default protocol interceptors
+ * for client side HTTP/1.1 processing.
+ *
+ * @return the processor.
+ */
public static HttpProcessor client() {
return customClient(null).build();
}
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/impl/IncomingEntityDetails.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/IncomingEntityDetails.java b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/IncomingEntityDetails.java
index 010132c..9712e40 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/IncomingEntityDetails.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/IncomingEntityDetails.java
@@ -30,6 +30,7 @@ package org.apache.hc.core5.http.impl;
import java.util.Collections;
import java.util.Set;
+import org.apache.hc.core5.annotation.Internal;
import org.apache.hc.core5.http.EntityDetails;
import org.apache.hc.core5.http.Header;
import org.apache.hc.core5.http.HttpHeaders;
@@ -42,6 +43,7 @@ import org.apache.hc.core5.util.Args;
*
* @since 5.0
*/
+@Internal
public class IncomingEntityDetails implements EntityDetails {
private final MessageHeaders message;
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/AsyncRequester.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/AsyncRequester.java b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/AsyncRequester.java
index ca5a767..1e196c2 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/AsyncRequester.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/AsyncRequester.java
@@ -32,6 +32,7 @@ import java.net.InetSocketAddress;
import java.util.List;
import java.util.concurrent.Future;
+import org.apache.hc.core5.annotation.Internal;
import org.apache.hc.core5.concurrent.DefaultThreadFactory;
import org.apache.hc.core5.concurrent.FutureCallback;
import org.apache.hc.core5.function.Callback;
@@ -52,11 +53,17 @@ import org.apache.hc.core5.reactor.IOSessionListener;
import org.apache.hc.core5.util.Args;
import org.apache.hc.core5.util.TimeValue;
+/**
+ * Protocol agnostic client side I/O session initiator.
+ *
+ * @since 5.0
+ */
public class AsyncRequester extends AbstractConnectionInitiatorBase implements IOReactorService {
private final DefaultConnectingIOReactor ioReactor;
private final Resolver<HttpHost, InetSocketAddress> addressResolver;
+ @Internal
public AsyncRequester(
final IOEventHandlerFactory eventHandlerFactory,
final IOReactorConfig ioReactorConfig,
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/AsyncRequesterBootstrap.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/AsyncRequesterBootstrap.java b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/AsyncRequesterBootstrap.java
index ca77d02..8f154e3 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/AsyncRequesterBootstrap.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/AsyncRequesterBootstrap.java
@@ -52,6 +52,8 @@ import org.apache.hc.core5.reactor.IOSessionListener;
import org.apache.hc.core5.util.Timeout;
/**
+ * {@link HttpAsyncRequester} bootstrap.
+ *
* @since 5.0
*/
public class AsyncRequesterBootstrap {
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/AsyncServer.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/AsyncServer.java b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/AsyncServer.java
index 7e1d6d4..04a4630 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/AsyncServer.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/AsyncServer.java
@@ -33,6 +33,7 @@ import java.util.List;
import java.util.Set;
import java.util.concurrent.Future;
+import org.apache.hc.core5.annotation.Internal;
import org.apache.hc.core5.concurrent.DefaultThreadFactory;
import org.apache.hc.core5.concurrent.FutureCallback;
import org.apache.hc.core5.function.Callback;
@@ -51,10 +52,14 @@ import org.apache.hc.core5.reactor.IOSessionListener;
import org.apache.hc.core5.reactor.ListenerEndpoint;
import org.apache.hc.core5.util.TimeValue;
+/**
+ * Protocol agnostic server side I/O session handler.
+ */
public class AsyncServer extends AbstractConnectionInitiatorBase implements IOReactorService, ConnectionAcceptor {
private final DefaultListeningIOReactor ioReactor;
+ @Internal
public AsyncServer(
final IOEventHandlerFactory eventHandlerFactory,
final IOReactorConfig ioReactorConfig,
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/AsyncServerBootstrap.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/AsyncServerBootstrap.java b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/AsyncServerBootstrap.java
index 0ed0a31..3cc7d3f 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/AsyncServerBootstrap.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/AsyncServerBootstrap.java
@@ -66,6 +66,8 @@ import org.apache.hc.core5.reactor.IOSessionListener;
import org.apache.hc.core5.util.Args;
/**
+ * {@link HttpAsyncServer} bootstrap.
+ *
* @since 5.0
*/
public class AsyncServerBootstrap {
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/FilterEntry.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/FilterEntry.java b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/FilterEntry.java
index e15adf8..7f2f99c 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/FilterEntry.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/FilterEntry.java
@@ -27,7 +27,7 @@
package org.apache.hc.core5.http.impl.bootstrap;
-class FilterEntry<T> {
+final class FilterEntry<T> {
enum Postion {BEFORE, AFTER, REPLACE, FIRST, LAST}
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/HttpAsyncRequester.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/HttpAsyncRequester.java b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/HttpAsyncRequester.java
index 00ffc4a..4b13696 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/HttpAsyncRequester.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/HttpAsyncRequester.java
@@ -34,6 +34,7 @@ import java.util.Set;
import java.util.concurrent.Future;
import java.util.concurrent.atomic.AtomicReference;
+import org.apache.hc.core5.annotation.Internal;
import org.apache.hc.core5.concurrent.BasicFuture;
import org.apache.hc.core5.concurrent.ComplexFuture;
import org.apache.hc.core5.concurrent.FutureCallback;
@@ -80,6 +81,8 @@ import org.apache.hc.core5.util.TimeValue;
import org.apache.hc.core5.util.Timeout;
/**
+ * HTTP/1.1 client side message exchange initiator.
+ *
* @since 5.0
*/
public class HttpAsyncRequester extends AsyncRequester implements ConnPoolControl<HttpHost> {
@@ -87,6 +90,10 @@ public class HttpAsyncRequester extends AsyncRequester implements ConnPoolContro
private final ManagedConnPool<HttpHost, IOSession> connPool;
private final TlsStrategy tlsStrategy;
+ /**
+ * Use {@link AsyncRequesterBootstrap} to create instances of this class.
+ */
+ @Internal
public HttpAsyncRequester(
final IOReactorConfig ioReactorConfig,
final IOEventHandlerFactory eventHandlerFactory,
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/HttpAsyncServer.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/HttpAsyncServer.java b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/HttpAsyncServer.java
index c6d0fd6..d4e848f 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/HttpAsyncServer.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/HttpAsyncServer.java
@@ -26,6 +26,7 @@
*/
package org.apache.hc.core5.http.impl.bootstrap;
+import org.apache.hc.core5.annotation.Internal;
import org.apache.hc.core5.function.Callback;
import org.apache.hc.core5.function.Decorator;
import org.apache.hc.core5.http.nio.command.ShutdownCommand;
@@ -37,10 +38,16 @@ import org.apache.hc.core5.reactor.IOSession;
import org.apache.hc.core5.reactor.IOSessionListener;
/**
+ * HTTP/1.1 server side message exchange handler.
+ *
* @since 5.0
*/
public class HttpAsyncServer extends AsyncServer {
+ /**
+ * Use {@link AsyncServerBootstrap} to create instances of this class.
+ */
+ @Internal
public HttpAsyncServer(
final IOEventHandlerFactory eventHandlerFactory,
final IOReactorConfig ioReactorConfig,
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/HttpRequester.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/HttpRequester.java b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/HttpRequester.java
index 16c8dc3..dfe6d0e 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/HttpRequester.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/HttpRequester.java
@@ -40,6 +40,7 @@ import java.util.concurrent.atomic.AtomicReference;
import javax.net.ssl.SSLSocketFactory;
+import org.apache.hc.core5.annotation.Internal;
import org.apache.hc.core5.function.Resolver;
import org.apache.hc.core5.http.ClassicHttpRequest;
import org.apache.hc.core5.http.ClassicHttpResponse;
@@ -77,6 +78,8 @@ import org.apache.hc.core5.util.TimeValue;
import org.apache.hc.core5.util.Timeout;
/**
+ * HTTP/1.1 client side message exchange initiator.
+ *
* @since 5.0
*/
public class HttpRequester implements ConnPoolControl<HttpHost>, ModalCloseable {
@@ -89,6 +92,10 @@ public class HttpRequester implements ConnPoolControl<HttpHost>, ModalCloseable
private final SSLSocketFactory sslSocketFactory;
private final Resolver<HttpHost, InetSocketAddress> addressResolver;
+ /**
+ * Use {@link RequesterBootstrap} to create instances of this class.
+ */
+ @Internal
public HttpRequester(
final HttpRequestExecutor requestExecutor,
final HttpProcessor httpProcessor,
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/HttpServer.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/HttpServer.java b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/HttpServer.java
index a71c1cb..ae87342 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/HttpServer.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/HttpServer.java
@@ -39,6 +39,7 @@ import javax.net.ServerSocketFactory;
import javax.net.ssl.SSLServerSocket;
import javax.net.ssl.SSLServerSocketFactory;
+import org.apache.hc.core5.annotation.Internal;
import org.apache.hc.core5.concurrent.DefaultThreadFactory;
import org.apache.hc.core5.http.ExceptionListener;
import org.apache.hc.core5.http.URIScheme;
@@ -56,6 +57,8 @@ import org.apache.hc.core5.util.Args;
import org.apache.hc.core5.util.TimeValue;
/**
+ * HTTP/1.1 server side message exchange handler.
+ *
* @since 4.4
*/
public class HttpServer implements ModalCloseable {
@@ -78,6 +81,7 @@ public class HttpServer implements ModalCloseable {
private volatile ServerSocket serverSocket;
private volatile RequestListener requestListener;
+ @Internal
public HttpServer(
final int port,
final HttpService httpService,
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/RequestListener.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/RequestListener.java b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/RequestListener.java
index 39def63..6f49ac3 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/RequestListener.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/RequestListener.java
@@ -33,14 +33,11 @@ import java.util.concurrent.ExecutorService;
import java.util.concurrent.atomic.AtomicBoolean;
import org.apache.hc.core5.http.ExceptionListener;
-import org.apache.hc.core5.http.io.SocketConfig;
import org.apache.hc.core5.http.impl.io.HttpService;
import org.apache.hc.core5.http.io.HttpConnectionFactory;
import org.apache.hc.core5.http.io.HttpServerConnection;
+import org.apache.hc.core5.http.io.SocketConfig;
-/**
- * @since 4.4
- */
class RequestListener implements Runnable {
private final SocketConfig socketConfig;
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/RequesterBootstrap.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/RequesterBootstrap.java b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/RequesterBootstrap.java
index cdc18bb..0513d1d 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/RequesterBootstrap.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/RequesterBootstrap.java
@@ -33,7 +33,6 @@ import org.apache.hc.core5.http.ConnectionReuseStrategy;
import org.apache.hc.core5.http.HttpHost;
import org.apache.hc.core5.http.config.CharCodingConfig;
import org.apache.hc.core5.http.config.H1Config;
-import org.apache.hc.core5.http.io.SocketConfig;
import org.apache.hc.core5.http.impl.DefaultAddressResolver;
import org.apache.hc.core5.http.impl.DefaultConnectionReuseStrategy;
import org.apache.hc.core5.http.impl.Http1StreamListener;
@@ -42,6 +41,7 @@ import org.apache.hc.core5.http.impl.io.DefaultBHttpClientConnectionFactory;
import org.apache.hc.core5.http.impl.io.HttpRequestExecutor;
import org.apache.hc.core5.http.io.HttpClientConnection;
import org.apache.hc.core5.http.io.HttpConnectionFactory;
+import org.apache.hc.core5.http.io.SocketConfig;
import org.apache.hc.core5.http.protocol.HttpProcessor;
import org.apache.hc.core5.pool.ConnPoolListener;
import org.apache.hc.core5.pool.LaxConnPool;
@@ -52,6 +52,8 @@ import org.apache.hc.core5.pool.StrictConnPool;
import org.apache.hc.core5.util.Timeout;
/**
+ * {@link HttpRequester} bootstrap.
+ *
* @since 5.0
*/
public class RequesterBootstrap {
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/ServerBootstrap.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/ServerBootstrap.java b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/ServerBootstrap.java
index 0c875a2..629e6c7 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/ServerBootstrap.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/ServerBootstrap.java
@@ -42,7 +42,6 @@ import org.apache.hc.core5.http.URIScheme;
import org.apache.hc.core5.http.config.CharCodingConfig;
import org.apache.hc.core5.http.config.H1Config;
import org.apache.hc.core5.http.config.NamedElementChain;
-import org.apache.hc.core5.http.io.SocketConfig;
import org.apache.hc.core5.http.impl.DefaultConnectionReuseStrategy;
import org.apache.hc.core5.http.impl.Http1StreamListener;
import org.apache.hc.core5.http.impl.HttpProcessors;
@@ -54,6 +53,7 @@ import org.apache.hc.core5.http.io.HttpConnectionFactory;
import org.apache.hc.core5.http.io.HttpFilterHandler;
import org.apache.hc.core5.http.io.HttpRequestHandler;
import org.apache.hc.core5.http.io.HttpServerRequestHandler;
+import org.apache.hc.core5.http.io.SocketConfig;
import org.apache.hc.core5.http.io.support.BasicHttpServerExpectationDecorator;
import org.apache.hc.core5.http.io.support.BasicHttpServerRequestHandler;
import org.apache.hc.core5.http.io.support.HttpServerExpectationFilter;
@@ -67,6 +67,8 @@ import org.apache.hc.core5.net.InetAddressUtils;
import org.apache.hc.core5.util.Args;
/**
+ * {@link HttpServer} bootstrap.
+ *
* @since 4.4
*/
public class ServerBootstrap {
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/StandardFilters.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/StandardFilters.java b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/StandardFilters.java
index 1aaca85..9864901 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/StandardFilters.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/StandardFilters.java
@@ -27,6 +27,12 @@
package org.apache.hc.core5.http.impl.bootstrap;
+/**
+ * Filters supported by async and classic server implementations
+ *
+ * @see AsyncServerBootstrap
+ * @see ServerBootstrap
+ */
public enum StandardFilters {
EXPECT_CONTINUE, MAIN_HANDLER
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/Worker.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/Worker.java b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/Worker.java
index b943e68..8d6a883 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/Worker.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/Worker.java
@@ -33,9 +33,6 @@ import org.apache.hc.core5.http.protocol.BasicHttpContext;
import org.apache.hc.core5.http.protocol.HttpCoreContext;
import org.apache.hc.core5.io.CloseMode;
-/**
- * @since 4.4
- */
class Worker implements Runnable {
private final HttpService httpservice;
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/WorkerPoolExecutor.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/WorkerPoolExecutor.java b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/WorkerPoolExecutor.java
index fde6d0c..15f2b92 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/WorkerPoolExecutor.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/WorkerPoolExecutor.java
@@ -35,9 +35,6 @@ import java.util.concurrent.ThreadFactory;
import java.util.concurrent.ThreadPoolExecutor;
import java.util.concurrent.TimeUnit;
-/**
- * @since 4.4
- */
class WorkerPoolExecutor extends ThreadPoolExecutor {
private final Map<Worker, Boolean> workerSet;
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/package-info.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/package-info.java b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/package-info.java
index 632bd0d..1070ff9 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/package-info.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/package-info.java
@@ -26,6 +26,6 @@
*/
/**
- * HTTP requester and server bootstrap.
+ * HTTP/1.1 requester and server bootstrap.
*/
package org.apache.hc.core5.http.impl.bootstrap;
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/impl/io/package-info.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/io/package-info.java b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/io/package-info.java
index 4b8027c..6e8bed7 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/io/package-info.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/io/package-info.java
@@ -26,7 +26,7 @@
*/
/**
- * Default implementations of message parses and writers
- * for synchronous, blocking communication.
+ * Default implementation of HTTP/1.1 transport based on the classic
+ * (blocking) I/O model.
*/
package org.apache.hc.core5.http.impl.io;
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/ClientHttp1IOEventHandler.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/ClientHttp1IOEventHandler.java b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/ClientHttp1IOEventHandler.java
index 1800d4b..3cf7d8f 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/ClientHttp1IOEventHandler.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/ClientHttp1IOEventHandler.java
@@ -27,15 +27,13 @@
package org.apache.hc.core5.http.impl.nio;
-import org.apache.hc.core5.annotation.Contract;
-import org.apache.hc.core5.annotation.ThreadingBehavior;
-
/**
- * {@link org.apache.hc.core5.reactor.IOEventHandler} that implements client side HTTP/1.1 messaging protocol.
+ * {@link org.apache.hc.core5.reactor.IOEventHandler} that implements
+ * client side HTTP/1.1 messaging protocol with full support for
+ * duplexed message transmission and message pipelining.
*
* @since 5.0
*/
-@Contract(threading = ThreadingBehavior.IMMUTABLE_CONDITIONAL)
public class ClientHttp1IOEventHandler extends AbstractHttp1IOEventHandler {
public ClientHttp1IOEventHandler(final ClientHttp1StreamDuplexer streamDuplexer) {
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/ClientHttp1IOEventHandlerFactory.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/ClientHttp1IOEventHandlerFactory.java b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/ClientHttp1IOEventHandlerFactory.java
index 6d94c57..5055a95 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/ClientHttp1IOEventHandlerFactory.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/ClientHttp1IOEventHandlerFactory.java
@@ -35,9 +35,11 @@ import org.apache.hc.core5.reactor.ProtocolIOSession;
import org.apache.hc.core5.util.Args;
/**
+ * {@link ClientHttp1IOEventHandler} factory.
+ *
* @since 5.0
*/
-@Contract(threading = ThreadingBehavior.IMMUTABLE)
+@Contract(threading = ThreadingBehavior.IMMUTABLE_CONDITIONAL)
public class ClientHttp1IOEventHandlerFactory implements IOEventHandlerFactory {
private final ClientHttp1StreamDuplexerFactory streamDuplexerFactory;
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/ClientHttp1StreamDuplexer.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/ClientHttp1StreamDuplexer.java b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/ClientHttp1StreamDuplexer.java
index c3bdcfa..820ed7b 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/ClientHttp1StreamDuplexer.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/ClientHttp1StreamDuplexer.java
@@ -35,6 +35,7 @@ import java.util.List;
import java.util.Queue;
import java.util.concurrent.ConcurrentLinkedQueue;
+import org.apache.hc.core5.annotation.Internal;
import org.apache.hc.core5.http.ConnectionClosedException;
import org.apache.hc.core5.http.ConnectionReuseStrategy;
import org.apache.hc.core5.http.ContentLengthStrategy;
@@ -68,6 +69,14 @@ import org.apache.hc.core5.reactor.ProtocolIOSession;
import org.apache.hc.core5.util.Args;
import org.apache.hc.core5.util.Asserts;
+/**
+ * I/O event handler for events fired by {@link ProtocolIOSession} that implements
+ * client side HTTP/1.1 messaging protocol with full support for
+ * duplexed message transmission and message pipelining.
+ *
+ * @since 5.0
+ */
+@Internal
public class ClientHttp1StreamDuplexer extends AbstractHttp1StreamDuplexer<HttpResponse, HttpRequest> {
private final HttpProcessor httpProcessor;
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/ClientHttp1StreamDuplexerFactory.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/ClientHttp1StreamDuplexerFactory.java b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/ClientHttp1StreamDuplexerFactory.java
index 0272faa..1f54f38 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/ClientHttp1StreamDuplexerFactory.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/ClientHttp1StreamDuplexerFactory.java
@@ -28,6 +28,7 @@
package org.apache.hc.core5.http.impl.nio;
import org.apache.hc.core5.annotation.Contract;
+import org.apache.hc.core5.annotation.Internal;
import org.apache.hc.core5.annotation.ThreadingBehavior;
import org.apache.hc.core5.http.ConnectionReuseStrategy;
import org.apache.hc.core5.http.ContentLengthStrategy;
@@ -45,9 +46,12 @@ import org.apache.hc.core5.reactor.ProtocolIOSession;
import org.apache.hc.core5.util.Args;
/**
+ * {@link ClientHttp1StreamDuplexer} factory.
+ *
* @since 5.0
*/
-@Contract(threading = ThreadingBehavior.IMMUTABLE)
+@Contract(threading = ThreadingBehavior.IMMUTABLE_CONDITIONAL)
+@Internal
public final class ClientHttp1StreamDuplexerFactory {
private final HttpProcessor httpProcessor;
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/HttpConnectionEventHandler.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/HttpConnectionEventHandler.java b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/HttpConnectionEventHandler.java
index a3fcf58..e378781 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/HttpConnectionEventHandler.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/HttpConnectionEventHandler.java
@@ -26,8 +26,15 @@
*/
package org.apache.hc.core5.http.impl.nio;
+import org.apache.hc.core5.annotation.Internal;
import org.apache.hc.core5.http.HttpConnection;
import org.apache.hc.core5.reactor.IOEventHandler;
+/**
+ * {@link IOEventHandler} that also exposes {@link HttpConnection} properties.
+ *
+ * @since 5.0
+ */
+@Internal
public interface HttpConnectionEventHandler extends IOEventHandler, HttpConnection {
}
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/ServerHttp1IOEventHandler.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/ServerHttp1IOEventHandler.java b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/ServerHttp1IOEventHandler.java
index 57218dd..8e16470 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/ServerHttp1IOEventHandler.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/ServerHttp1IOEventHandler.java
@@ -31,7 +31,9 @@ import org.apache.hc.core5.annotation.Contract;
import org.apache.hc.core5.annotation.ThreadingBehavior;
/**
- * {@link org.apache.hc.core5.reactor.IOEventHandler} that implements server side HTTP/1.1 messaging protocol.
+ * {@link org.apache.hc.core5.reactor.IOEventHandler} that implements
+ * server side HTTP/1.1 messaging protocol with full support for
+ * duplexed message transmission and message pipelining.
*
* @since 5.0
*/
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/ServerHttp1IOEventHandlerFactory.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/ServerHttp1IOEventHandlerFactory.java b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/ServerHttp1IOEventHandlerFactory.java
index ee84dfa..7a47a1d 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/ServerHttp1IOEventHandlerFactory.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/ServerHttp1IOEventHandlerFactory.java
@@ -37,9 +37,11 @@ import org.apache.hc.core5.reactor.ProtocolIOSession;
import org.apache.hc.core5.util.Args;
/**
+ * {@link ServerHttp1IOEventHandler} factory.
+ *
* @since 5.0
*/
-@Contract(threading = ThreadingBehavior.IMMUTABLE)
+@Contract(threading = ThreadingBehavior.IMMUTABLE_CONDITIONAL)
public class ServerHttp1IOEventHandlerFactory implements IOEventHandlerFactory {
private final ServerHttp1StreamDuplexerFactory streamDuplexerFactory;
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/ServerHttp1StreamDuplexer.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/ServerHttp1StreamDuplexer.java b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/ServerHttp1StreamDuplexer.java
index edfca1e..ab97c1a 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/ServerHttp1StreamDuplexer.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/ServerHttp1StreamDuplexer.java
@@ -35,6 +35,7 @@ import java.util.List;
import java.util.Queue;
import java.util.concurrent.ConcurrentLinkedQueue;
+import org.apache.hc.core5.annotation.Internal;
import org.apache.hc.core5.http.ConnectionClosedException;
import org.apache.hc.core5.http.ConnectionReuseStrategy;
import org.apache.hc.core5.http.ContentLengthStrategy;
@@ -67,6 +68,14 @@ import org.apache.hc.core5.reactor.ProtocolIOSession;
import org.apache.hc.core5.util.Args;
import org.apache.hc.core5.util.Asserts;
+/**
+ * I/O event handler for events fired by {@link ProtocolIOSession} that implements
+ * server side HTTP/1.1 messaging protocol with full support for
+ * duplexed message transmission and message pipelining.
+ *
+ * @since 5.0
+ */
+@Internal
public class ServerHttp1StreamDuplexer extends AbstractHttp1StreamDuplexer<HttpRequest, HttpResponse> {
private final String scheme;
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/ServerHttp1StreamDuplexerFactory.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/ServerHttp1StreamDuplexerFactory.java b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/ServerHttp1StreamDuplexerFactory.java
index e92cd0a..b34c8e5 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/ServerHttp1StreamDuplexerFactory.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/ServerHttp1StreamDuplexerFactory.java
@@ -28,6 +28,7 @@
package org.apache.hc.core5.http.impl.nio;
import org.apache.hc.core5.annotation.Contract;
+import org.apache.hc.core5.annotation.Internal;
import org.apache.hc.core5.annotation.ThreadingBehavior;
import org.apache.hc.core5.http.ConnectionReuseStrategy;
import org.apache.hc.core5.http.ContentLengthStrategy;
@@ -47,9 +48,12 @@ import org.apache.hc.core5.reactor.ProtocolIOSession;
import org.apache.hc.core5.util.Args;
/**
+ * {@link ServerHttp1StreamDuplexer} factory.
+ *
* @since 5.0
*/
-@Contract(threading = ThreadingBehavior.IMMUTABLE)
+@Contract(threading = ThreadingBehavior.IMMUTABLE_CONDITIONAL)
+@Internal
public final class ServerHttp1StreamDuplexerFactory {
private final HttpProcessor httpProcessor;
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/ServerSupport.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/ServerSupport.java b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/ServerSupport.java
index 5cf9f78..c6d0c56 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/ServerSupport.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/ServerSupport.java
@@ -38,6 +38,11 @@ import org.apache.hc.core5.http.UnsupportedHttpVersionException;
import org.apache.hc.core5.http.nio.AsyncResponseProducer;
import org.apache.hc.core5.http.nio.BasicResponseProducer;
+/**
+ * HTTP Server support methods.
+ *
+ * @since 5.0
+ */
@Internal
public class ServerSupport {
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/package-info.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/package-info.java b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/package-info.java
new file mode 100644
index 0000000..02424b5
--- /dev/null
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/package-info.java
@@ -0,0 +1,32 @@
+/*
+ * ====================================================================
+ * 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/>.
+ *
+ */
+
+/**
+ * Default implementation of HTTP/1.1 transport based on
+ * the asynchronous (non-blocking) I/O model.
+ */
+package org.apache.hc.core5.http.impl.nio;
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/impl/package-info.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/package-info.java b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/package-info.java
index 0c0fbb4..b408113 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/package-info.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/package-info.java
@@ -26,7 +26,6 @@
*/
/**
- * Default implementations of HTTP connections for synchronous,
- * blocking communication.
+ * Default implementations of core HTTP APIs.
*/
package org.apache.hc.core5.http.impl;
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/io/HttpFilterChain.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/io/HttpFilterChain.java b/httpcore5/src/main/java/org/apache/hc/core5/http/io/HttpFilterChain.java
index f863307..0d81a6f 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/io/HttpFilterChain.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/io/HttpFilterChain.java
@@ -36,19 +36,42 @@ import org.apache.hc.core5.http.HttpException;
import org.apache.hc.core5.http.protocol.HttpContext;
/**
+ * HttpFilterChain represents a single element in the server side request processing chain.
+ *
* @since 5.0
*/
@Contract(threading = ThreadingBehavior.STATELESS)
public interface HttpFilterChain {
+ /**
+ * Response trigger that can be used to generate the final HTTP response
+ * and terminate HTTP request processing.
+ */
interface ResponseTrigger {
+ /**
+ * Sends an intermediate informational HTTP response to the client.
+ *
+ * @param response an intermediate (1xx) HTTP response.
+ */
void sendInformation(ClassicHttpResponse response) throws HttpException, IOException;
+ /**
+ * Sends a final HTTP response to the client.
+ *
+ * @param response a final (non 1xx) HTTP response.
+ */
void submitResponse(ClassicHttpResponse response) throws HttpException, IOException;
}
+ /**
+ * Proceeds to the next element in the request processing chain.
+ *
+ * @param request the actual request.
+ * @param responseTrigger the response trigger.
+ * @param context the actual execution context.
+ */
void proceed(
ClassicHttpRequest request,
ResponseTrigger responseTrigger,
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/io/HttpFilterHandler.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/io/HttpFilterHandler.java b/httpcore5/src/main/java/org/apache/hc/core5/http/io/HttpFilterHandler.java
index 4409784..10bec16 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/io/HttpFilterHandler.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/io/HttpFilterHandler.java
@@ -35,11 +35,26 @@ import org.apache.hc.core5.http.HttpException;
import org.apache.hc.core5.http.protocol.HttpContext;
/**
+ * HttpFilterHandler represents a routine for handling all incoming requests
+ * in the server side request processing chain.
+ *
* @since 5.0
*/
@Contract(threading = ThreadingBehavior.STATELESS)
public interface HttpFilterHandler {
+ /**
+ * Processes the incoming HTTP request and if processing has been completed
+ * submits a final response to the client. The handler must not use
+ * the response trigger after passing control to the next filter with the
+ * {@link HttpFilterChain#proceed(ClassicHttpRequest, HttpFilterChain.ResponseTrigger, HttpContext)}
+ * method.
+ *
+ * @param request the actual request.
+ * @param responseTrigger the response trigger.
+ * @param context the actual execution context.
+ * @param chain the next element in the request processing chain.
+ */
void handle(
ClassicHttpRequest request,
HttpFilterChain.ResponseTrigger responseTrigger,
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/io/HttpResponseInformationCallback.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/io/HttpResponseInformationCallback.java b/httpcore5/src/main/java/org/apache/hc/core5/http/io/HttpResponseInformationCallback.java
index 76e5c97..394c537 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/io/HttpResponseInformationCallback.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/io/HttpResponseInformationCallback.java
@@ -33,7 +33,7 @@ import org.apache.hc.core5.http.HttpResponse;
import org.apache.hc.core5.http.protocol.HttpContext;
/**
- * Information message callback.
+ * Informational (1xx) HTTP response callback.
*
* @since 5.0
*/
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/io/HttpServerRequestHandler.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/io/HttpServerRequestHandler.java b/httpcore5/src/main/java/org/apache/hc/core5/http/io/HttpServerRequestHandler.java
index 648b781..8d07104 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/io/HttpServerRequestHandler.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/io/HttpServerRequestHandler.java
@@ -36,19 +36,47 @@ import org.apache.hc.core5.http.HttpException;
import org.apache.hc.core5.http.protocol.HttpContext;
/**
+ * HttpServerRequestHandler 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.
+ *
* @since 5.0
*/
@Contract(threading = ThreadingBehavior.STATELESS)
public interface HttpServerRequestHandler {
+ /**
+ * Response trigger that can be used to submit a final HTTP response
+ * and terminate HTTP request processing.
+ */
interface ResponseTrigger {
+ /**
+ * Sends an intermediate informational HTTP response to the client.
+ *
+ * @param response the intermediate (1xx) HTTP response
+ */
void sendInformation(ClassicHttpResponse response) throws HttpException, IOException;
+ /**
+ * Sends a final HTTP response to the client.
+ *
+ * @param response the final (non 1xx) HTTP response
+ */
void submitResponse(ClassicHttpResponse response) throws HttpException, IOException;
}
+ /**
+ * Handles the request and submits a final response to be sent back to the client.
+ *
+ * @param request the actual request.
+ * @param responseTrigger the response trigger.
+ * @param context the actual execution context.
+ */
void handle(
ClassicHttpRequest request,
ResponseTrigger responseTrigger,
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/io/SocketConfig.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/io/SocketConfig.java b/httpcore5/src/main/java/org/apache/hc/core5/http/io/SocketConfig.java
index 65fc3b5..8afa462 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/io/SocketConfig.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/io/SocketConfig.java
@@ -36,7 +36,7 @@ import org.apache.hc.core5.util.TimeValue;
import org.apache.hc.core5.util.Timeout;
/**
- * Socket configuration.
+ * Classic I/O network socket configuration.
*
* @since 4.3
*/
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/io/entity/AbstractImmutableHttpEntity.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/io/entity/AbstractImmutableHttpEntity.java b/httpcore5/src/main/java/org/apache/hc/core5/http/io/entity/AbstractImmutableHttpEntity.java
index 1ec31ee..bbc6f53 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/io/entity/AbstractImmutableHttpEntity.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/io/entity/AbstractImmutableHttpEntity.java
@@ -39,7 +39,7 @@ import org.apache.hc.core5.util.Args;
*
* @since 5.0
*/
-public abstract class AbstractImmutableHttpEntity implements HttpEntity, HttpContentProducer {
+public abstract class AbstractImmutableHttpEntity implements HttpEntity {
static final int OUTPUT_BUFFER_SIZE = 4096;
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/io/entity/EntityUtils.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/io/entity/EntityUtils.java b/httpcore5/src/main/java/org/apache/hc/core5/http/io/entity/EntityUtils.java
index 1873af8..a806ead 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/io/entity/EntityUtils.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/io/entity/EntityUtils.java
@@ -49,7 +49,7 @@ import org.apache.hc.core5.util.ByteArrayBuffer;
import org.apache.hc.core5.util.CharArrayBuffer;
/**
- * Static helpers for dealing with {@link HttpEntity}s.
+ * Support methods for {@link HttpEntity}.
*
* @since 4.0
*/
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/io/entity/package-info.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/io/entity/package-info.java b/httpcore5/src/main/java/org/apache/hc/core5/http/io/entity/package-info.java
index 5f9fef2..614a628 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/io/entity/package-info.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/io/entity/package-info.java
@@ -26,6 +26,6 @@
*/
/**
- * Core HTTP entity implementations.
+ * HTTP message entity APIs based on the classic (blocking) I/O model.
*/
package org.apache.hc.core5.http.io.entity;
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/io/package-info.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/io/package-info.java b/httpcore5/src/main/java/org/apache/hc/core5/http/io/package-info.java
index d0f516c..4068696 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/io/package-info.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/io/package-info.java
@@ -26,7 +26,6 @@
*/
/**
- * HTTP message parser and writer APIs for synchronous, blocking
- * communication.
+ * Core HTTP transport APIs based on the classic (blocking) I/O model.
*/
package org.apache.hc.core5.http.io;
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/io/support/AbstractHttpServerAuthFilter.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/io/support/AbstractHttpServerAuthFilter.java b/httpcore5/src/main/java/org/apache/hc/core5/http/io/support/AbstractHttpServerAuthFilter.java
index a000c27..7eae508 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/io/support/AbstractHttpServerAuthFilter.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/io/support/AbstractHttpServerAuthFilter.java
@@ -47,6 +47,10 @@ import org.apache.hc.core5.http.protocol.HttpContext;
import org.apache.hc.core5.net.URIAuthority;
/**
+ * Abstract HTTP request filter that implements standard HTTP authentication handshake.
+ *
+ * @param <T> authorization token representation.
+ *
* @since 5.0
*/
@Contract(threading = ThreadingBehavior.STATELESS)
@@ -58,12 +62,48 @@ public abstract class AbstractHttpServerAuthFilter<T> implements HttpFilterHandl
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 HttpEntity generateResponseContent(final HttpResponse unauthorized) {
return new StringEntity("Unauthorized");
}
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/io/support/BasicHttpServerExpectationDecorator.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/io/support/BasicHttpServerExpectationDecorator.java b/httpcore5/src/main/java/org/apache/hc/core5/http/io/support/BasicHttpServerExpectationDecorator.java
index 1920a4c..c4f25e8 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/io/support/BasicHttpServerExpectationDecorator.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/io/support/BasicHttpServerExpectationDecorator.java
@@ -41,6 +41,10 @@ import org.apache.hc.core5.http.protocol.HttpContext;
import org.apache.hc.core5.util.Args;
/**
+ * {@link HttpServerRequestHandler} implementation that adds support
+ * for the Expect-Continue handshake to an existing
+ * {@link HttpServerRequestHandler}.
+ *
* @since 5.0
*/
public class BasicHttpServerExpectationDecorator implements HttpServerRequestHandler {
@@ -51,6 +55,15 @@ public class BasicHttpServerExpectationDecorator implements HttpServerRequestHan
this.requestHandler = Args.notNull(requestHandler, "Request handler");
}
+ /**
+ * Verifies the HTTP request and decides whether it meets server expectations and the request
+ * processing can continue.
+ *
+ * @param request the incoming HTTP request.
+ * @param context the actual execution context.
+ * @return {@code null} if the request meets expectations or a final HTTP response
+ * with an error status representing the cause of expectation failure.
+ */
protected ClassicHttpResponse verify(final ClassicHttpRequest request, final HttpContext context) {
return null;
}
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/io/support/BasicHttpServerRequestHandler.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/io/support/BasicHttpServerRequestHandler.java b/httpcore5/src/main/java/org/apache/hc/core5/http/io/support/BasicHttpServerRequestHandler.java
index 1fa9a47..c317846 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/io/support/BasicHttpServerRequestHandler.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/io/support/BasicHttpServerRequestHandler.java
@@ -42,6 +42,10 @@ import org.apache.hc.core5.http.protocol.HttpContext;
import org.apache.hc.core5.util.Args;
/**
+ * Basic {@link HttpServerRequestHandler} implementation that makes use of
+ * {@link HttpRequestMapper} to dispatch the request to a particular
+ * {@link HttpRequestHandler} for processing.
+ *
* @since 5.0
*/
public class BasicHttpServerRequestHandler implements HttpServerRequestHandler {
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/io/support/HttpServerExpectationFilter.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/io/support/HttpServerExpectationFilter.java b/httpcore5/src/main/java/org/apache/hc/core5/http/io/support/HttpServerExpectationFilter.java
index 9b5aacf..a419959 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/io/support/HttpServerExpectationFilter.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/io/support/HttpServerExpectationFilter.java
@@ -44,15 +44,34 @@ import org.apache.hc.core5.http.message.BasicClassicHttpResponse;
import org.apache.hc.core5.http.protocol.HttpContext;
/**
+ * HttpServerExpectationFilter add support for the Expect-Continue handshake
+ * to the request processing pipeline.
+ *
* @since 5.0
*/
@Contract(threading = ThreadingBehavior.STATELESS)
public class HttpServerExpectationFilter implements HttpFilterHandler {
+ /**
+ * Verifies the HTTP request and decides whether it meets server expectations and the request
+ * processing can continue.
+ *
+ * @param request the incoming HTTP request.
+ * @param context the actual execution context.
+ * @return {@code true} if the request meets expectations or {@code false} otherwise.
+ */
protected boolean verify(final ClassicHttpRequest request, final HttpContext context) throws HttpException {
return true;
}
+ /**
+ * Generates response content entity for the final HTTP response with an error status
+ * representing the cause of expectation failure.
+ *
+ * @param expectationFailed the final HTTP response.
+ * @return the content entity for the final HTTP response with an error status
+ * representing the cause of expectation failure.
+ */
protected HttpEntity generateResponseContent(final HttpResponse expectationFailed) throws HttpException {
return null;
}
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/io/support/HttpServerFilterChainElement.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/io/support/HttpServerFilterChainElement.java b/httpcore5/src/main/java/org/apache/hc/core5/http/io/support/HttpServerFilterChainElement.java
index 69d429f..939c468 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/io/support/HttpServerFilterChainElement.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/io/support/HttpServerFilterChainElement.java
@@ -35,6 +35,11 @@ import org.apache.hc.core5.http.io.HttpFilterChain;
import org.apache.hc.core5.http.io.HttpFilterHandler;
import org.apache.hc.core5.http.protocol.HttpContext;
+/**
+ * An element in a request processing chain.
+ *
+ * @since 5.0
+ */
public final class HttpServerFilterChainElement {
private final HttpFilterHandler handler;
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/io/support/HttpServerFilterChainRequestHandler.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/io/support/HttpServerFilterChainRequestHandler.java b/httpcore5/src/main/java/org/apache/hc/core5/http/io/support/HttpServerFilterChainRequestHandler.java
index c6064b9..b008345 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/io/support/HttpServerFilterChainRequestHandler.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/io/support/HttpServerFilterChainRequestHandler.java
@@ -38,6 +38,9 @@ import org.apache.hc.core5.http.protocol.HttpContext;
import org.apache.hc.core5.util.Args;
/**
+ * {@link HttpServerRequestHandler} implementation that delegates request processing
+ * to a {@link HttpServerFilterChainElement}.
+ *
* @since 5.0
*/
public class HttpServerFilterChainRequestHandler implements HttpServerRequestHandler {
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/io/support/TerminalServerFilter.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/io/support/TerminalServerFilter.java b/httpcore5/src/main/java/org/apache/hc/core5/http/io/support/TerminalServerFilter.java
index a059f4c..5955f68 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/io/support/TerminalServerFilter.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/io/support/TerminalServerFilter.java
@@ -44,6 +44,10 @@ import org.apache.hc.core5.http.protocol.HttpContext;
import org.apache.hc.core5.util.Args;
/**
+ * {@link HttpFilterHandler} implementation represents a terminal handler
+ * in a request processing pipeline that makes use of {@link HttpRequestMapper}
+ * to dispatch the request to a particular {@link HttpRequestHandler}.
+ *
* @since 5.0
*/
@Contract(threading = ThreadingBehavior.STATELESS)
@@ -52,7 +56,9 @@ public final class TerminalServerFilter implements HttpFilterHandler {
private final HttpRequestMapper<HttpRequestHandler> handlerMapper;
private final HttpResponseFactory<ClassicHttpResponse> responseFactory;
- public TerminalServerFilter(final HttpRequestMapper<HttpRequestHandler> handlerMapper, final HttpResponseFactory<ClassicHttpResponse> responseFactory) {
+ public TerminalServerFilter(
+ final HttpRequestMapper<HttpRequestHandler> handlerMapper,
+ final HttpResponseFactory<ClassicHttpResponse> responseFactory) {
this.handlerMapper = Args.notNull(handlerMapper, "Handler mapper");
this.responseFactory = responseFactory != null ? responseFactory : DefaultClassicHttpResponseFactory.INSTANCE;
}
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/io/support/package-info.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/io/support/package-info.java b/httpcore5/src/main/java/org/apache/hc/core5/http/io/support/package-info.java
new file mode 100644
index 0000000..207f7d5
--- /dev/null
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/io/support/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/>.
+ *
+ */
+
+/**
+ * Support classes for the classic (blocking) I/O model.
+ */
+package org.apache.hc.core5.http.io.support;
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/message/MessageSupport.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/message/MessageSupport.java b/httpcore5/src/main/java/org/apache/hc/core5/http/message/MessageSupport.java
index f015ed3..faa2ac6 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/message/MessageSupport.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/message/MessageSupport.java
@@ -47,7 +47,7 @@ import org.apache.hc.core5.util.CharArrayBuffer;
import org.apache.hc.core5.util.TextUtils;
/**
- * Message support functions.
+ * Support methods for HTTP message processing.
*
* @since 5.0
*/
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncClientExchangeHandler.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncClientExchangeHandler.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncClientExchangeHandler.java
index 160168d..75f8c56 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncClientExchangeHandler.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncClientExchangeHandler.java
@@ -41,12 +41,38 @@ import org.apache.hc.core5.http.protocol.HttpContext;
*/
public interface AsyncClientExchangeHandler extends AsyncDataExchangeHandler {
- void produceRequest(RequestChannel channel, 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 produceRequest(RequestChannel channel, HttpContext context) throws HttpException, IOException;
- void consumeResponse(HttpResponse response, EntityDetails entityDetails, HttpContext httpContext) 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.
+ */
+ void consumeResponse(HttpResponse response, EntityDetails entityDetails, HttpContext context) throws HttpException, IOException;
- void consumeInformation(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 consumeInformation(HttpResponse response, HttpContext context) throws HttpException, IOException;
+ /**
+ * Triggered to cancel the message exchange.
+ */
void cancel();
}
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncDataExchangeHandler.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncDataExchangeHandler.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncDataExchangeHandler.java
index 3bc09e5..e942e39 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncDataExchangeHandler.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncDataExchangeHandler.java
@@ -34,6 +34,11 @@ package org.apache.hc.core5.http.nio;
*/
public interface AsyncDataExchangeHandler extends AsyncDataConsumer, AsyncDataProducer {
+ /**
+ * 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/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncEntityConsumer.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncEntityConsumer.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncEntityConsumer.java
index 027e147..b276e39 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncEntityConsumer.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncEntityConsumer.java
@@ -35,14 +35,33 @@ import org.apache.hc.core5.http.HttpException;
/**
* Abstract asynchronous message entity consumer.
*
+ * @param <T> entity representation.
+ *
* @since 5.0
*/
public interface AsyncEntityConsumer<T> extends AsyncDataConsumer {
+ /**
+ * Signals beginning of an incoming request entity stream.
+ *
+ * @param entityDetails the details of the incoming message entity.
+ * @param resultCallback the result callback.
+ */
void streamStart(EntityDetails entityDetails, 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 entity processing when it becomes available or {@code null}
+ * if the entity is still being received.
+ *
+ * @return the response processing result.
+ */
T getContent();
}
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncEntityProducer.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncEntityProducer.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncEntityProducer.java
index 0814760..6fa519f 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncEntityProducer.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncEntityProducer.java
@@ -41,6 +41,11 @@ public interface AsyncEntityProducer extends AsyncDataProducer, EntityDetails {
*/
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/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncFilterChain.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncFilterChain.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncFilterChain.java
index c2ef87d..33a892a 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncFilterChain.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncFilterChain.java
@@ -37,21 +37,52 @@ import org.apache.hc.core5.http.HttpResponse;
import org.apache.hc.core5.http.protocol.HttpContext;
/**
+ * AsyncFilterChain represents a single element in the server side request processing chain.
+ *
* @since 5.0
*/
@Contract(threading = ThreadingBehavior.STATELESS)
public interface AsyncFilterChain {
+ /**
+ * Response trigger that can be used to generate the final HTTP response
+ * and terminate HTTP request processing.
+ */
interface ResponseTrigger {
+ /**
+ * Sends an intermediate informational HTTP response to the client.
+ *
+ * @param response the intermediate (1xx) HTTP response.
+ */
void sendInformation(HttpResponse response) throws HttpException, IOException;
+ /**
+ * Sends a final HTTP response to the client.
+ *
+ * @param response the final (non 1xx) HTTP response.
+ */
void submitResponse(HttpResponse response, AsyncEntityProducer entityProducer) 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 responseProducer the push response message producer.
+ */
void pushPromise(HttpRequest promise, AsyncPushProducer responseProducer) throws HttpException, IOException;
}
+ /**
+ * Proceeds to the next element in the request processing chain.
+ *
+ * @param request the actual request.
+ * @param entityDetails the request entity details or {@code null} if the request
+ * does not enclose an entity.
+ * @param responseTrigger the response trigger.
+ * @param context the actual execution context.
+ */
AsyncDataConsumer proceed(
HttpRequest request,
EntityDetails entityDetails,