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:29 UTC
[3/6] httpcomponents-core git commit: Javadocs for core HTTP APIs
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/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/0679d155/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,
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/classic/package-info.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/classic/package-info.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/classic/package-info.java
new file mode 100644
index 0000000..a50741c
--- /dev/null
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/classic/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/>.
+ *
+ */
+
+/**
+ * Support classes for the asynchronous I/O model that emulate
+ * behavior of the classic (blocking) I/O model.
+ */
+package org.apache.hc.core5.http.nio.support.classic;
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/package-info.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/package-info.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/package-info.java
new file mode 100644
index 0000000..049eada
--- /dev/null
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/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 asynchronous I/O model.
+ */
+package org.apache.hc.core5.http.nio.support;
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/package-info.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/package-info.java b/httpcore5/src/main/java/org/apache/hc/core5/http/package-info.java
index 7f46068..47153ba 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/package-info.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/package-info.java
@@ -26,7 +26,7 @@
*/
/**
- * Core HTTP component APIs and primitives.
+ * Core HTTP transport component APIs.
* <p>
* These deal with the fundamental things required for using the
* HTTP protocol, such as representing a
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/protocol/RequestHandlerRegistry.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/protocol/RequestHandlerRegistry.java b/httpcore5/src/main/java/org/apache/hc/core5/http/protocol/RequestHandlerRegistry.java
index 3475427..61ced60 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/protocol/RequestHandlerRegistry.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/protocol/RequestHandlerRegistry.java
@@ -40,6 +40,13 @@ import org.apache.hc.core5.http.MisdirectedRequestException;
import org.apache.hc.core5.net.URIAuthority;
import org.apache.hc.core5.util.Args;
+/**
+ * Generic registry of request handlers that can be resolved by properties of request messages.
+ *
+ * @param <T> request handler type.
+ *
+ * @since 5.0
+ */
@Contract(threading = ThreadingBehavior.SAFE_CONDITIONAL)
public class RequestHandlerRegistry<T> implements HttpRequestMapper<T> {
@@ -64,8 +71,6 @@ public class RequestHandlerRegistry<T> implements HttpRequestMapper<T> {
this.virtualMap = new ConcurrentHashMap<>();
}
-
-
public RequestHandlerRegistry(final String canonicalHostName, final UriPatternType patternType) {
this(canonicalHostName, new Supplier<LookupRegistry<T>>() {
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/http/protocol/package-info.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/protocol/package-info.java b/httpcore5/src/main/java/org/apache/hc/core5/http/protocol/package-info.java
index 878e64b..bf307eb 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/protocol/package-info.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/protocol/package-info.java
@@ -26,7 +26,6 @@
*/
/**
- * Core HTTP protocol execution framework and HTTP protocol handlers
- * for synchronous, blocking communication.
+ * Core HTTP protocol interceptors.
*/
package org.apache.hc.core5.http.protocol;
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/reactor/Command.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/reactor/Command.java b/httpcore5/src/main/java/org/apache/hc/core5/reactor/Command.java
index 62c945e..55088bd 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/reactor/Command.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/reactor/Command.java
@@ -30,7 +30,8 @@ package org.apache.hc.core5.reactor;
import org.apache.hc.core5.concurrent.Cancellable;
/**
- * Abstract command {@link IOSession} can act upon.
+ * Abstract command {@link IOSession} can act upon. Pending commands
+ * can be cancelled with {@link Cancellable#cancel()}.
*
* @since 5.0
*/
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/0679d155/httpcore5/src/main/java/org/apache/hc/core5/reactor/ProtocolIOSession.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/reactor/ProtocolIOSession.java b/httpcore5/src/main/java/org/apache/hc/core5/reactor/ProtocolIOSession.java
index a15dfdb..b1f32cf 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/reactor/ProtocolIOSession.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/reactor/ProtocolIOSession.java
@@ -30,7 +30,7 @@ package org.apache.hc.core5.reactor;
import org.apache.hc.core5.reactor.ssl.TransportSecurityLayer;
/**
- * TLS capable {@link IOSession}.
+ * TLS capable, protocol upgradable {@link IOSession}.
*
* @since 5.0
*/