From eeee2389d4d1f0d776ac75e492469dea9c817a0e Mon Sep 17 00:00:00 2001
From: Olivier L Applin <olapplin@amazon.com>
Date: Fri, 18 Oct 2024 18:02:02 -0400
Subject: [PATCH] Response input stream javadoc improvement (#5671)

* Improve ResponseInputStream javadoc about close/abort regarding connection pooling

* mention specific http clients
---
 .../awssdk/core/ResponseInputStream.java      | 19 +++++++++++++------
 1 file changed, 13 insertions(+), 6 deletions(-)

diff --git a/core/sdk-core/src/main/java/software/amazon/awssdk/core/ResponseInputStream.java b/core/sdk-core/src/main/java/software/amazon/awssdk/core/ResponseInputStream.java
index b7203961cec5..90df32b24113 100644
--- a/core/sdk-core/src/main/java/software/amazon/awssdk/core/ResponseInputStream.java
+++ b/core/sdk-core/src/main/java/software/amazon/awssdk/core/ResponseInputStream.java
@@ -25,13 +25,20 @@
 
 /**
  * Input stream that provides access to the unmarshalled POJO response returned by the service in addition to the streamed
- * contents. This input stream should be closed to release the underlying connection back to the connection pool.
- *
+ * contents. This input stream should be closed after all data has been read from the stream.
+ * <p>
+ * Note about the Apache http client: This input stream can be used to leverage a feature of the Apache http client where
+ * connections are released back to the connection pool to be reused. As such, calling {@link ResponseInputStream#close() close}
+ * on this input stream will result in reading the remaining data from the stream and leaving the connection open, even if the
+ * stream was only partially read from. For large http payload, this means reading <em>all</em> of the http body before releasing
+ * the connection which may add latency.
+ * <p>
+ * If it is not desired to read remaining data from the stream, you can explicitly abort the connection via {@link #abort()}
+ * instead. This will close the underlying connection and require establishing a new HTTP connection on subsequent requests which
+ * may outweigh the cost of reading the additional data.
  * <p>
- * If it is not desired to read remaining data from the stream, you can explicitly abort the connection via {@link #abort()}.
- * Note that this will close the underlying connection and require establishing an HTTP connection which may outweigh the
- * cost of reading the additional data.
- * </p>
+ * The Url Connection and Crt http clients are not subject to this behaviour so the {@link ResponseInputStream#close() close} and
+ * {@link ResponseInputStream#abort() abort} methods will behave similarly with them.
  */
 @SdkPublicApi
 public final class ResponseInputStream<ResponseT> extends SdkFilterInputStream implements Abortable {