From 4c041d715555d2c7857007fe354c694acfbd7ef6 Mon Sep 17 00:00:00 2001 From: Stefano Duo Date: Wed, 10 Apr 2024 12:56:39 +0000 Subject: 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 --- .../src/android/net/http/BidirectionalStream.java | 49 ++++++++++++++++++---- android/java/src/android/net/http/UrlRequest.java | 36 +++++++++++++--- 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. 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}. 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. 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}. + * 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. 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}. + * 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. 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}. + * 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. 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}. + * 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. 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}. + * 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. 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}. + * 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. 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}. + * 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. 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}. 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. 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}. 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. 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}. 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. 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}. 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. 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}. 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. 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}. 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); -- cgit v1.2.3