(httpcomponents-core) branch 5.2.x updated: HTTPCLIENT-2334: AsyncDataProducer javadoc improvements

[ol...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

olegk pushed a commit to branch 5.2.x
in repository https://gitbox.apache.org/repos/asf/httpcomponents-core.git


The following commit(s) were added to refs/heads/5.2.x by this push:
     new e2e904a5b HTTPCLIENT-2334: AsyncDataProducer javadoc improvements
e2e904a5b is described below

commit e2e904a5bbe26aa74c7b1291e667fb891f4ccad3
Author: Oleg Kalnichevski <ol...@apache.org>
AuthorDate: Tue Jul 30 09:43:50 2024 +0200

    HTTPCLIENT-2334: AsyncDataProducer javadoc improvements
---
 .../org/apache/hc/core5/http/nio/AsyncDataProducer.java | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

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 59656369a..25bcbfb8f 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
@@ -39,8 +39,18 @@ 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.
+     * <p>
+     * Please note this method should return zero if the data producer
+     * is unable to produce any more data, in which case
+     * {@link #produce(DataStreamChannel)} method will not get triggered.
+     * The producer can resume writing out data asynchronously
+     * once more data becomes available or request output readiness events
+     * with {@link DataStreamChannel#requestOutput()}.
      *
      * @return the number of bytes immediately available for output
+     *
+     * @see #produce(DataStreamChannel)
+     * @see DataStreamChannel#requestOutput()
      */
     int available();
 
@@ -48,8 +58,13 @@ public interface AsyncDataProducer extends ResourceHolder {
      * 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.
+     * <p>
+     * Please note this method gets triggered only if {@link #available()}
+     * returns a positive value.
+     *
+     * @param channel the data channel capable of accepting more data.
      *
-     * @param channel the data channel capable to accepting more data.
+     * @see #available()
      */
     void produce(DataStreamChannel channel) throws IOException;