Update UrlRequest and BidirectionalStream documentation

Explicitly state that there are no guarantees regarding the specific object being passed to callbacks within UrlRequest.Callback and BidirectionalStream.Callback.

Bug: 333390290, 328442628

Change-Id: Icbaa3687ed7c99bea9ccdb90339ebb07b56a63ec

2 files changed, 70 insertions, 15 deletions

diff --git a/android/java/src/android/net/http/BidirectionalStream.java b/android/java/src/android/net/http/BidirectionalStream.java
index 2a156687b..d30fa5b4d 100644
--- a/android/java/src/android/net/http/BidirectionalStream.java
+++ b/android/java/src/android/net/http/BidirectionalStream.java
@@ -171,7 +171,11 @@ public abstract class BidirectionalStream {
          * BidirectionalStream#read read()} to start reading data. Consumer may call {@link
          * BidirectionalStream#write write()} to start writing data.
          *
-         * @param stream the stream that is ready.
+         * @param stream the stream that is ready. <strong>This is not guaranteed to be the same
+         *        object as the one received by other callbacks, nor is it guaranteed to be the one
+         *        returned by {@link BidirectionalStream.Builder#build}.</strong> However, method
+         *        calls on this object will have the same effects as calls on the original
+         *        {@link BidirectionalStream}.
          */
         void onStreamReady(@NonNull BidirectionalStream stream);
 
@@ -181,7 +185,11 @@ public abstract class BidirectionalStream {
          * BidirectionalStream#read read()} to start reading. Consumer may call {@link
          * BidirectionalStream#write write()} to start writing or close the stream.
          *
-         * @param stream the stream on which response headers were received.
+         * @param stream the stream on which response headers were received. <strong>This is not
+         *        guaranteed to be the same object as the one received by other callbacks, nor is
+         *        it guaranteed to be the one returned by {@link BidirectionalStream.Builder#build}.
+         *        </strong> However, method calls on this object will have the same effects as
+         *        calls on the original {@link BidirectionalStream}.
          * @param info the response information.
          */
         void onResponseHeadersReceived(@NonNull BidirectionalStream stream,
@@ -194,10 +202,13 @@ public abstract class BidirectionalStream {
          * onResponseTrailersReceived()}, if there was pending read data before trailers were
          * received.
          *
-         * @param stream the stream on which the read completed
+         * @param stream the stream on which the read completed. <strong>This is not guaranteed to
+         *        be the same object as the one received by other callbacks, nor is it guaranteed
+         *        to be the one returned by {@link BidirectionalStream.Builder#build}.</strong>
+         *        However, method calls on this object will have the same effects as calls on the
+         *        original {@link BidirectionalStream}.
          * @param info the response information
          * @param buffer the buffer that was passed to {@link BidirectionalStream#read read()}, now
-         * containing the received data. The buffer's limit is not changed. The buffer's position is
          * set to the end of the received data. If position is not updated, it means the remote side
          * has signaled that it will send no more data.
          * @param endOfStream if true, this is the last read data, remote will not send more data,
@@ -213,7 +224,11 @@ public abstract class BidirectionalStream {
          * limit is not changed. To continue writing, call {@link BidirectionalStream#write
          * write()}.
          *
-         * @param stream the stream on which the write completed
+         * @param stream the stream on which the write completed. <strong>This is not guaranteed to
+         *        be the same object as the one received by other callbacks, nor is it guaranteed
+         *        to be the one returned by {@link BidirectionalStream.Builder#build}.</strong>
+         *        However, method calls on this object will have the same effects as calls on the
+         *        original {@link BidirectionalStream}.
          * @param info the response information
          * @param buffer the buffer that was passed to {@link BidirectionalStream#write write()}.
          *         The
@@ -231,7 +246,11 @@ public abstract class BidirectionalStream {
          *
          * Default implementation takes no action.
          *
-         * @param stream the stream on which response trailers were received
+         * @param stream the stream on which response trailers were received. <strong>This is not
+         *        guaranteed to be the same object as the one received by other callbacks, nor is
+         *        it guaranteed to be the one returned by {@link BidirectionalStream.Builder#build}.
+         *        </strong> However, method calls on this object will have the same effects as calls
+         *        on the original {@link BidirectionalStream}.
          * @param info the response information
          * @param trailers the trailers received
          */
@@ -243,7 +262,11 @@ public abstract class BidirectionalStream {
          * remotely and locally. Once invoked, no further {@link BidirectionalStream.Callback}
          * methods will be invoked.
          *
-         * @param stream the stream which is closed successfully
+         * @param stream the stream which is closed successfully. <strong>This is not guaranteed to
+         *        be the same object as the one received by other callbacks, nor is it guaranteed
+         *        to be the one returned by {@link BidirectionalStream.Builder#build}.</strong>
+         *        However, method calls on this object will have the same effects as calls on the
+         *        original {@link BidirectionalStream}.
          * @param info the response information
          */
         void onSucceeded(@NonNull BidirectionalStream stream, @NonNull UrlResponseInfo info);
@@ -254,7 +277,11 @@ public abstract class BidirectionalStream {
          * mapped to {@link NetworkException#getErrorCode} codes. Once invoked,
          * no further {@link BidirectionalStream.Callback} methods will be invoked.
          *
-         * @param stream the stream which has failed
+         * @param stream the stream which has failed. <strong>This is not guaranteed to
+         *        be the same object as the one received by other callbacks, nor is it guaranteed
+         *        to be the one returned by {@link BidirectionalStream.Builder#build}.</strong>
+         *        However, method calls on this object will have the same effects as calls on the
+         *        original {@link BidirectionalStream}.
          * @param info the response information. May be {@code null} if no response was received.
          * @param error information about the failure
          */
@@ -266,7 +293,11 @@ public abstract class BidirectionalStream {
          * no further {@link BidirectionalStream.Callback} methods will be invoked. Default
          * implementation takes no action.
          *
-         * @param stream the stream that was canceled
+         * @param stream the stream that was canceled. <strong>This is not guaranteed to
+         *        be the same object as the one received by other callbacks, nor is it guaranteed
+         *        to be the one returned by {@link BidirectionalStream.Builder#build}.</strong>
+         *        However, method calls on this object will have the same effects as calls on the
+         *        original {@link BidirectionalStream}.
          * @param info the response information. May be {@code null} if no response was received.
          */
         void onCanceled(@NonNull BidirectionalStream stream, @Nullable UrlResponseInfo info);
diff --git a/android/java/src/android/net/http/UrlRequest.java b/android/java/src/android/net/http/UrlRequest.java
index 3d223f0b7..2443d9307 100644
--- a/android/java/src/android/net/http/UrlRequest.java
+++ b/android/java/src/android/net/http/UrlRequest.java
@@ -217,7 +217,11 @@ public abstract class UrlRequest {
          * The redirect will not be followed until the URLRequest's {@link
          * UrlRequest#followRedirect} method is called, either synchronously or asynchronously.
          *
-         * @param request Request being redirected.
+         * @param request Request being redirected. <strong>This is not guaranteed to be the same
+         *        object as the one received by other callbacks, nor is it guaranteed to be the one
+         *        returned by {@link URLRequest.Builder#build}.</strong> However, method calls on
+         *        this object will have the same effects as calls on the original
+         *        {@link URLRequest}.
          * @param info Response information.
          * @param newLocationUrl Location where request is redirected.
          * @throws Exception if an error occurs while processing a redirect. {@link #onFailed} will
@@ -238,7 +242,11 @@ public abstract class UrlRequest {
          * onSucceeded()} and {@link Callback#onFailed onFailed()}, until {@link UrlRequest#read
          * UrlRequest.read()} is called to attempt to start reading the response body.
          *
-         * @param request Request that started to get response.
+         * @param request Request that started to get response. <strong>This is not guaranteed to be
+         *        the same object as the one received by other callbacks, nor is it guaranteed to be
+         *        the one returned by {@link URLRequest.Builder#build}.</strong> However, method
+         *        calls on this object will have the same effects as calls on the original
+         *        {@link URLRequest}.
          * @param info Response information.
          * @throws Exception if an error occurs while processing response start. {@link #onFailed}
          *         will
@@ -258,7 +266,11 @@ public abstract class UrlRequest {
          * onSucceeded()} and {@link Callback#onFailed onFailed()}, until {@link UrlRequest#read
          * UrlRequest.read()} is called to attempt to continue reading the response body.
          *
-         * @param request Request that received data.
+         * @param request Request that received data. <strong>This is not guaranteed to be the same
+         *        object as the one received by other callbacks, nor is it guaranteed to be the one
+         *        returned by {@link URLRequest.Builder#build}.</strong> However, method calls on
+         *        this object will have the same effects as calls on the original
+         *        {@link URLRequest}.
          * @param info Response information.
          * @param byteBuffer The buffer that was passed in to {@link UrlRequest#read
          *         UrlRequest.read()},
@@ -278,7 +290,11 @@ public abstract class UrlRequest {
          * Invoked when request is completed successfully. Once invoked, no other {@link Callback}
          * methods will be invoked.
          *
-         * @param request Request that succeeded.
+         * @param request Request that succeeded. <strong>This is not guaranteed to be the same
+         *        object as the one received by other callbacks, nor is it guaranteed to be the one
+         *        returned by {@link URLRequest.Builder#build}.</strong> However, method calls on
+         *        this object will have the same effects as calls on the original
+         *        {@link URLRequest}.
          * @param info Response information.
          */
          void onSucceeded(
@@ -289,7 +305,11 @@ public abstract class UrlRequest {
          * other {@link Callback} methods will be invoked. {@code error} provides information about
          * the failure.
          *
-         * @param request Request that failed.
+         * @param request Request that failed. <strong>This is not guaranteed to be the same
+         *        object as the one received by other callbacks, nor is it guaranteed to be the one
+         *        returned by {@link URLRequest.Builder#build}.</strong> However, method calls on
+         *        this object will have the same effects as calls on the original
+         *        {@link URLRequest}.
          * @param info Response information. May be {@code null} if no response was received.
          * @param error information about error.
          */
@@ -300,7 +320,11 @@ public abstract class UrlRequest {
          * Invoked if request was canceled via {@link UrlRequest#cancel}. Once invoked, no other
          * {@link Callback} methods will be invoked. Default implementation takes no action.
          *
-         * @param request Request that was canceled.
+         * @param request Request that was canceled. <strong>This is not guaranteed to be the same
+         *        object as the one received by other callbacks, nor is it guaranteed to be the one
+         *        returned by {@link URLRequest.Builder#build}.</strong> However, method calls on
+         *        this object will have the same effects as calls on the original
+         *        {@link URLRequest}.
          * @param info Response information. May be {@code null} if no response was received.
          */
         void onCanceled(@NonNull UrlRequest request, @Nullable UrlResponseInfo info);