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/05 11:09:13 UTC
[7/8] httpcomponents-core git commit: Javadocs for abstract data
channels, data producers and data consumers
Javadocs for abstract data channels, data producers and data consumers
Project: http://git-wip-us.apache.org/repos/asf/httpcomponents-core/repo
Commit: http://git-wip-us.apache.org/repos/asf/httpcomponents-core/commit/936ac6f1
Tree: http://git-wip-us.apache.org/repos/asf/httpcomponents-core/tree/936ac6f1
Diff: http://git-wip-us.apache.org/repos/asf/httpcomponents-core/diff/936ac6f1
Branch: refs/heads/api_javadocs
Commit: 936ac6f1428a77a578f0cf0c136f6f00c8f0241f
Parents: 49c6296
Author: Oleg Kalnichevski <ol...@apache.org>
Authored: Sat Aug 4 13:34:01 2018 +0200
Committer: Oleg Kalnichevski <ol...@apache.org>
Committed: Sun Aug 5 13:06:12 2018 +0200
----------------------------------------------------------------------
.../hc/core5/http/nio/AsyncDataConsumer.java | 24 ++++++++++++++++
.../hc/core5/http/nio/AsyncDataProducer.java | 14 ++++++++++
.../hc/core5/http/nio/CapacityChannel.java | 9 ++++++
.../hc/core5/http/nio/DataStreamChannel.java | 29 +++++++++++++++++++-
.../hc/core5/http/nio/ResourceHolder.java | 7 +++++
.../apache/hc/core5/http/nio/StreamChannel.java | 21 +++++++++++++-
.../apache/hc/core5/http/nio/package-info.java | 12 ++++++++
7 files changed, 114 insertions(+), 2 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/936ac6f1/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncDataConsumer.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncDataConsumer.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncDataConsumer.java
index 6f3456e..4044837 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncDataConsumer.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncDataConsumer.java
@@ -40,10 +40,34 @@ import org.apache.hc.core5.http.HttpException;
*/
public interface AsyncDataConsumer extends ResourceHolder {
+ /**
+ * Triggered to signal ability of the underlying data stream to receive
+ * data capacity update. The data consumer can choose to write data
+ * immediately inside the call or asynchronously at some later point.
+ *
+ * @param capacityChannel the channel for capacity updates.
+ */
void updateCapacity(CapacityChannel capacityChannel) throws IOException;
+ /**
+ * Triggered to pass incoming data to the data consumer. The consumer must
+ * consume the entire content of the data buffer. The consumer must stop
+ * incrementing its capacity on the capacity channel and must return zero
+ * capacity from this method if it is unable to accept more data.
+ * Once the data consumer has handled accumulated data or allocated more
+ * intermediate storage it can update its capacity information on the capacity
+ * channel.
+ *
+ * @param src data source.
+ * @return current capacity of the data consumer
+ */
int consume(ByteBuffer src) throws IOException;
+ /**
+ * Triggered to signal termination of the data stream.
+ *
+ * @param trailers data stream trailers.
+ */
void streamEnd(List<? extends Header> trailers) throws HttpException, IOException;
}
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/936ac6f1/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncDataProducer.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncDataProducer.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncDataProducer.java
index 4e4a839..5965636 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncDataProducer.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncDataProducer.java
@@ -35,8 +35,22 @@ import java.io.IOException;
*/
public interface AsyncDataProducer extends ResourceHolder {
+ /**
+ * Returns the number of bytes immediately available for output.
+ * This method can be used as a hint to control output events
+ * of the underlying I/O session.
+ *
+ * @return the number of bytes immediately available for output
+ */
int available();
+ /**
+ * Triggered to signal the ability of the underlying data channel
+ * to accept more data. The data producer can choose to write data
+ * immediately inside the call or asynchronously at some later point.
+ *
+ * @param channel the data channel capable to accepting more data.
+ */
void produce(DataStreamChannel channel) throws IOException;
}
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/936ac6f1/httpcore5/src/main/java/org/apache/hc/core5/http/nio/CapacityChannel.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/CapacityChannel.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/CapacityChannel.java
index efc0304..4e724ef 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/CapacityChannel.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/CapacityChannel.java
@@ -35,12 +35,21 @@ import org.apache.hc.core5.annotation.ThreadingBehavior;
* Abstract capacity update channel.
* <p>
* Implementations are expected to be thread-safe.
+ * </p>
*
* @since 5.0
*/
@Contract(threading = ThreadingBehavior.SAFE)
public interface CapacityChannel {
+ /**
+ * Updates data capacity information. The total number of
+ * bytes the consumer is capable of accepting is incremented
+ * by the given increment number.
+ *
+ * @param increment non-negative number of extra bytes the consumer
+ * can accept.
+ */
void update(int increment) throws IOException;
}
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/936ac6f1/httpcore5/src/main/java/org/apache/hc/core5/http/nio/DataStreamChannel.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/DataStreamChannel.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/DataStreamChannel.java
index 2934242..e30e42d 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/DataStreamChannel.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/DataStreamChannel.java
@@ -36,17 +36,44 @@ import org.apache.hc.core5.annotation.ThreadingBehavior;
import org.apache.hc.core5.http.Header;
/**
- * Abstract data stream channel
+ * Abstract byte stream channel
* <p>
* Implementations are expected to be thread-safe.
+ * </p>
*
* @since 5.0
*/
@Contract(threading = ThreadingBehavior.SAFE)
public interface DataStreamChannel extends StreamChannel<ByteBuffer> {
+ /**
+ * Signals intent by the data producer to produce more data.
+ * Once the channel is able to accept data its handler is expected
+ * to trigger an event to notify the data producer.
+ */
void requestOutput();
+ /**
+ * Writes data from the buffer into the underlying byte stream.
+ * If the underlying byte stream is temporarily unable to accept more data
+ * it can return zero to indicate that no data could be written to the data
+ * stream. The data producer can choose to call {@link #requestOutput()}
+ * to signal its intent to produce more data.
+ *
+ * @param src source of data
+ *
+ * @return The number of bytes written, possibly zero
+ */
+ int write(ByteBuffer src) throws IOException;
+
+ /**
+ * Terminates the underlying data stream and optionally writes
+ * a closing sequence with the given trailers.
+ * <p>
+ * Please note that some data streams may not support trailers
+ * and may silently ignore the trailers parameter.
+ * </p>
+ */
void endStream(List<? extends Header> trailers) throws IOException;
}
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/936ac6f1/httpcore5/src/main/java/org/apache/hc/core5/http/nio/ResourceHolder.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/ResourceHolder.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/ResourceHolder.java
index 5c1a7ef..255b2f5 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/ResourceHolder.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/ResourceHolder.java
@@ -26,15 +26,22 @@
*/
package org.apache.hc.core5.http.nio;
+import org.apache.hc.core5.annotation.Contract;
+import org.apache.hc.core5.annotation.ThreadingBehavior;
+
/**
* Abstract resource holder.
* <p>
* Implementations are expected to ensure that {@link #releaseResources()} methods is idempotent and is
* safe to invoke multiple times.
* </p>
+ * <p>
+ * Implementations are expected to be thread-safe.
+ * </p>
*
* @since 5.0
*/
+@Contract(threading = ThreadingBehavior.SAFE)
public interface ResourceHolder {
void releaseResources();
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/936ac6f1/httpcore5/src/main/java/org/apache/hc/core5/http/nio/StreamChannel.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/StreamChannel.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/StreamChannel.java
index 00bf209..49fc1fd 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/StreamChannel.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/StreamChannel.java
@@ -30,14 +30,33 @@ package org.apache.hc.core5.http.nio;
import java.io.IOException;
import java.nio.Buffer;
+import org.apache.hc.core5.annotation.Contract;
+import org.apache.hc.core5.annotation.ThreadingBehavior;
+
/**
- * Abstract stream channel.
+ * Abstract data stream channel.
+ * <p>
+ * Implementations are expected to be thread-safe.
+ * </p>
+ *
+ * @param <T> data container accepted by the channel.
*
* @since 5.0
*/
+@Contract(threading = ThreadingBehavior.SAFE)
public interface StreamChannel<T extends Buffer> {
+ /**
+ * Writes data from the data container into the underlying data stream.
+ *
+ * @param src source of data
+ * @return The number of elements written, possibly zero
+ */
int write(T src) throws IOException;
+ /**
+ * Terminates the underlying data stream and optionally writes
+ * a closing sequence.
+ */
void endStream() throws IOException;
}
http://git-wip-us.apache.org/repos/asf/httpcomponents-core/blob/936ac6f1/httpcore5/src/main/java/org/apache/hc/core5/http/nio/package-info.java
----------------------------------------------------------------------
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/package-info.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/package-info.java
index 00b5fd9..0101117 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/package-info.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/package-info.java
@@ -28,5 +28,17 @@
/**
* Core HTTP component APIs and primitives for asynchronous, event
* driven communication.
+ * <p>
+ * The application programming interface is based on the concept
+ * of channels and event handlers. The channels act as conduits
+ * for asynchronous data output. They are generally expected to
+ * be thread-safe and could be used by multiple threads concurrently.
+ * The event handlers react to as asynchronous signal or event and
+ * handle them. Event handlers can be specialized as data producers,
+ * data consumers or can be both. Generally event handlers can only
+ * be used by a signle thread at a time and do not require synchronization
+ * as long as they do not interact with event handlers run by separate
+ * threads.
+ * <p/>
*/
package org.apache.hc.core5.http.nio;