1 // Copyright 2014 The Chromium Authors 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 package android.net.http; 6 7 import android.annotation.IntDef; 8 import android.annotation.SuppressLint; 9 import android.net.Network; 10 11 import androidx.annotation.NonNull; 12 import androidx.annotation.Nullable; 13 14 import java.lang.annotation.Retention; 15 import java.lang.annotation.RetentionPolicy; 16 import java.nio.ByteBuffer; 17 import java.util.List; 18 import java.util.Map; 19 import java.util.concurrent.Executor; 20 21 /** 22 * Controls an HTTP request (GET, PUT, POST etc). 23 * Created by {@link UrlRequest.Builder}, which can be obtained by calling 24 * {@link HttpEngine#newUrlRequestBuilder}. 25 * Note: All methods must be called on the {@link Executor} passed to 26 * {@link HttpEngine#newUrlRequestBuilder}. 27 */ 28 public abstract class UrlRequest { 29 UrlRequest()30 UrlRequest() {} 31 32 /** 33 * Lowest request priority. Passed to {@link Builder#setPriority}. 34 */ 35 public static final int REQUEST_PRIORITY_IDLE = 0; 36 /** 37 * Very low request priority. Passed to {@link Builder#setPriority}. 38 */ 39 public static final int REQUEST_PRIORITY_LOWEST = 1; 40 /** 41 * Low request priority. Passed to {@link Builder#setPriority}. 42 */ 43 public static final int REQUEST_PRIORITY_LOW = 2; 44 /** 45 * Medium request priority. Passed to {@link Builder#setPriority}. This is the 46 * default priority given to the request. 47 */ 48 public static final int REQUEST_PRIORITY_MEDIUM = 3; 49 /** 50 * Highest request priority. Passed to {@link Builder#setPriority}. 51 */ 52 public static final int REQUEST_PRIORITY_HIGHEST = 4; 53 54 /** 55 * Builder for {@link UrlRequest}s. Allows configuring requests before constructing them 56 * with {@link Builder#build}. The builder can be created by calling 57 * {@link HttpEngine#newUrlRequestBuilder}. 58 */ 59 // SuppressLint: Builder can not be final since this is abstract and inherited 60 // e.g. ExperimentalUrlRequest.Builder 61 @SuppressLint("StaticFinalBuilder") 62 public abstract static class Builder { 63 Builder()64 Builder() {} 65 66 /** 67 * Sets the HTTP method verb to use for this request. 68 * 69 * <p>The default when this method is not called is "GET" if the request has 70 * no body or "POST" if it does. 71 * 72 * @param method "GET", "HEAD", "DELETE", "POST" or "PUT". 73 * @return the builder to facilitate chaining. 74 */ 75 @NonNull setHttpMethod(@onNull String method)76 public abstract Builder setHttpMethod(@NonNull String method); 77 78 /** 79 * Adds a request header. 80 * 81 * @param header header name. 82 * @param value header value. 83 * @return the builder to facilitate chaining. 84 */ 85 @NonNull addHeader(@onNull String header, @NonNull String value)86 public abstract Builder addHeader(@NonNull String header, @NonNull String value); 87 88 /** 89 * Whether to disable cache for the request. If the engine is not set up to use cache, 90 * this call has no effect. 91 * @param disableCache {@code true} to disable cache, {@code false} otherwise. 92 * @return the builder to facilitate chaining. 93 */ 94 @NonNull setCacheDisabled(boolean disableCache)95 public abstract Builder setCacheDisabled(boolean disableCache); 96 97 /** 98 * Sets priority of the request which should be one of the {@link #REQUEST_PRIORITY_IDLE 99 * REQUEST_PRIORITY_*} values. The request is given {@link #REQUEST_PRIORITY_MEDIUM} 100 * priority if this method is not called. 101 * 102 * @param priority priority of the request which should be one of the {@link 103 * #REQUEST_PRIORITY_IDLE REQUEST_PRIORITY_*} values. 104 * @return the builder to facilitate chaining. 105 */ 106 @NonNull setPriority(int priority)107 public abstract Builder setPriority(int priority); 108 109 /** 110 * Sets upload data provider. Switches method to "POST" if not explicitly set. Starting the 111 * request will throw an exception if a Content-Type header is not set. 112 * 113 * @param uploadDataProvider responsible for providing the upload data. 114 * @param executor All {@code uploadDataProvider} methods will be invoked using this {@code 115 * Executor}. May optionally be the same {@code Executor} the request itself is using. 116 * @return the builder to facilitate chaining. 117 */ 118 // SuppressLint: UploadDataProvider is wrapped by other classes after set. 119 // Also, UploadDataProvider is a class to provide an upload body and getter is not useful 120 @NonNull @SuppressLint("MissingGetterMatchingBuilder") setUploadDataProvider( @onNull UploadDataProvider uploadDataProvider, @NonNull Executor executor)121 public abstract Builder setUploadDataProvider( 122 @NonNull UploadDataProvider uploadDataProvider, @NonNull Executor executor); 123 124 /** 125 * Marks whether the executors this request will use to notify callbacks (for 126 * {@code UploadDataProvider}s and {@code UrlRequest.Callback}s) is intentionally performing 127 * inline execution, like Guava's directExecutor or 128 * {@link java.util.concurrent.ThreadPoolExecutor.CallerRunsPolicy}. 129 * 130 * <p><b>Warning:</b> If set to true: This option makes it easy to accidentally block the 131 * network thread. This should not be done if your callbacks perform disk I/O, acquire 132 * locks, or call into other code you don't carefully control and audit. 133 * 134 * @param allowDirectExecutor {@code true} to allow executors performing inline execution, 135 * {@code false} otherwise. 136 * @return the builder to facilitate chaining. 137 */ 138 @NonNull setDirectExecutorAllowed(boolean allowDirectExecutor)139 public abstract Builder setDirectExecutorAllowed(boolean allowDirectExecutor); 140 141 /** 142 * Binds the request to the specified network. The HTTP stack will send this request 143 * only using the network associated to this handle. If this network disconnects the request 144 * will fail, the exact error will depend on the stage of request processing when 145 * the network disconnects. 146 * 147 * @param network the network to bind the request to. Specify {@code null} to unbind. 148 * @return the builder to facilitate chaining. 149 */ 150 @NonNull @SuppressLint("BuilderSetStyle") bindToNetwork(@ullable Network network)151 public abstract Builder bindToNetwork(@Nullable Network network); 152 153 /** 154 * Sets {@link android.net.TrafficStats} tag to use when accounting socket traffic caused by 155 * this request. See {@link android.net.TrafficStats} for more information. If no tag is 156 * set (e.g. this method isn't called), then Android accounts for the socket traffic caused 157 * by this request as if the tag value were set to 0. 158 * <p> 159 * <b>NOTE:</b>Setting a tag disallows sharing of sockets with requests 160 * with other tags, which may adversely effect performance by prohibiting 161 * connection sharing. In other words use of multiplexed sockets (e.g. HTTP/2 162 * and QUIC) will only be allowed if all requests have the same socket tag. 163 * 164 * @param tag the tag value used to when accounting for socket traffic caused by this 165 * request. Tags between 0xFFFFFF00 and 0xFFFFFFFF are reserved and used 166 * internally by system services like {@link android.app.DownloadManager} when 167 * performing traffic on behalf of an application. 168 * @return the builder to facilitate chaining. 169 */ 170 @NonNull setTrafficStatsTag(int tag)171 public abstract Builder setTrafficStatsTag(int tag); 172 173 /** 174 * Sets specific UID to use when accounting socket traffic caused by this request. See 175 * {@link android.net.TrafficStats} for more information. Designed for use when performing 176 * an operation on behalf of another application. Caller must hold 177 * {@code android.Manifest.permission#MODIFY_NETWORK_ACCOUNTING} permission. By default 178 * traffic is attributed to UID of caller. 179 * <p> 180 * <b>NOTE:</b>Setting a UID disallows sharing of sockets with requests 181 * with other UIDs, which may adversely effect performance by prohibiting 182 * connection sharing. In other words use of multiplexed sockets (e.g. HTTP/2 183 * and QUIC) will only be allowed if all requests have the same UID set. 184 * 185 * @param uid the UID to attribute socket traffic caused by this request. 186 * @return the builder to facilitate chaining. 187 */ 188 @NonNull setTrafficStatsUid(int uid)189 public abstract Builder setTrafficStatsUid(int uid); 190 191 /** 192 * Creates a {@link UrlRequest} using configuration within this {@link Builder}. The 193 * returned 194 * {@code UrlRequest} can then be started by calling {@link UrlRequest#start}. 195 * 196 * @return constructed {@link UrlRequest} using configuration within this {@link Builder}. 197 */ 198 @NonNull build()199 public abstract UrlRequest build(); 200 } 201 202 /** 203 * Users of the HTTP stack extend this class to receive callbacks indicating the 204 * progress of a {@link UrlRequest} being processed. An instance of this class 205 * is passed in to {@link UrlRequest.Builder}'s constructor when 206 * constructing the {@code UrlRequest}. 207 * <p> 208 * Note: All methods will be invoked on the thread of the {@link java.util.concurrent.Executor} 209 * used during construction of the {@code UrlRequest}. 210 */ 211 public interface Callback { 212 /** 213 * Invoked whenever a redirect is encountered. This will only be invoked between the call to 214 * {@link UrlRequest#start} and {@link Callback#onResponseStarted onResponseStarted()}. The 215 * body of the redirect response, if it has one, will be ignored. 216 * 217 * The redirect will not be followed until the URLRequest's {@link 218 * UrlRequest#followRedirect} method is called, either synchronously or asynchronously. 219 * 220 * @param request Request being redirected. <strong>This is not guaranteed to be the same 221 * object as the one received by other callbacks, nor is it guaranteed to be the one 222 * returned by {@link URLRequest.Builder#build}.</strong> However, method calls on 223 * this object will have the same effects as calls on the original 224 * {@link URLRequest}. 225 * @param info Response information. 226 * @param newLocationUrl Location where request is redirected. 227 * @throws Exception if an error occurs while processing a redirect. {@link #onFailed} will 228 * be 229 * called with the thrown exception set as the cause of the {@link CallbackException}. 230 */ 231 // SuppressLint: Exception will be wrapped and passed to #onFailed, see above javadoc 232 @SuppressLint("GenericException") onRedirectReceived(@onNull UrlRequest request, @NonNull UrlResponseInfo info, @NonNull String newLocationUrl)233 void onRedirectReceived(@NonNull UrlRequest request, 234 @NonNull UrlResponseInfo info, @NonNull String newLocationUrl) throws Exception; 235 236 /** 237 * Invoked when the final set of headers, after all redirects, is received. Will only be 238 * invoked once for each request. 239 * 240 * With the exception of {@link Callback#onCanceled onCanceled()}, no other {@link Callback} 241 * method will be invoked for the request, including {@link Callback#onSucceeded 242 * onSucceeded()} and {@link Callback#onFailed onFailed()}, until {@link UrlRequest#read 243 * UrlRequest.read()} is called to attempt to start reading the response body. 244 * 245 * @param request Request that started to get response. <strong>This is not guaranteed to be 246 * the same object as the one received by other callbacks, nor is it guaranteed to be 247 * the one returned by {@link URLRequest.Builder#build}.</strong> However, method 248 * calls on this object will have the same effects as calls on the original 249 * {@link URLRequest}. 250 * @param info Response information. 251 * @throws Exception if an error occurs while processing response start. {@link #onFailed} 252 * will 253 * be called with the thrown exception set as the cause of the {@link CallbackException}. 254 */ 255 // SuppressLint: Exception will be wrapped and passed to #onFailed, see above javadoc 256 @SuppressLint("GenericException") onResponseStarted(@onNull UrlRequest request, @NonNull UrlResponseInfo info)257 void onResponseStarted(@NonNull UrlRequest request, 258 @NonNull UrlResponseInfo info) throws Exception; 259 260 /** 261 * Invoked whenever part of the response body has been read. Only part of the buffer may be 262 * populated, even if the entire response body has not yet been consumed. 263 * 264 * With the exception of {@link Callback#onCanceled onCanceled()}, no other {@link Callback} 265 * method will be invoked for the request, including {@link Callback#onSucceeded 266 * onSucceeded()} and {@link Callback#onFailed onFailed()}, until {@link UrlRequest#read 267 * UrlRequest.read()} is called to attempt to continue reading the response body. 268 * 269 * @param request Request that received data. <strong>This is not guaranteed to be the same 270 * object as the one received by other callbacks, nor is it guaranteed to be the one 271 * returned by {@link URLRequest.Builder#build}.</strong> However, method calls on 272 * this object will have the same effects as calls on the original 273 * {@link URLRequest}. 274 * @param info Response information. 275 * @param byteBuffer The buffer that was passed in to {@link UrlRequest#read 276 * UrlRequest.read()}, 277 * now containing the received data. The buffer's position is updated to the end of the 278 * received data. The buffer's limit is not changed. 279 * @throws Exception if an error occurs while processing a read completion. {@link 280 * #onFailed} 281 * will be called with the thrown exception set as the cause of the {@link 282 * CallbackException}. 283 */ 284 // SuppressLint: Exception will be wrapped and passed to #onFailed, see above javadoc 285 @SuppressLint("GenericException") onReadCompleted(@onNull UrlRequest request, @NonNull UrlResponseInfo info, @NonNull ByteBuffer byteBuffer)286 void onReadCompleted(@NonNull UrlRequest request, 287 @NonNull UrlResponseInfo info, @NonNull ByteBuffer byteBuffer) throws Exception; 288 289 /** 290 * Invoked when request is completed successfully. Once invoked, no other {@link Callback} 291 * methods will be invoked. 292 * 293 * @param request Request that succeeded. <strong>This is not guaranteed to be the same 294 * object as the one received by other callbacks, nor is it guaranteed to be the one 295 * returned by {@link URLRequest.Builder#build}.</strong> However, method calls on 296 * this object will have the same effects as calls on the original 297 * {@link URLRequest}. 298 * @param info Response information. 299 */ onSucceeded( @onNull UrlRequest request, @NonNull UrlResponseInfo info)300 void onSucceeded( 301 @NonNull UrlRequest request, @NonNull UrlResponseInfo info); 302 303 /** 304 * Invoked if request failed for any reason after {@link UrlRequest#start}. Once invoked, no 305 * other {@link Callback} methods will be invoked. {@code error} provides information about 306 * the failure. 307 * 308 * @param request Request that failed. <strong>This is not guaranteed to be the same 309 * object as the one received by other callbacks, nor is it guaranteed to be the one 310 * returned by {@link URLRequest.Builder#build}.</strong> However, method calls on 311 * this object will have the same effects as calls on the original 312 * {@link URLRequest}. 313 * @param info Response information. May be {@code null} if no response was received. 314 * @param error information about error. 315 */ onFailed(@onNull UrlRequest request, @Nullable UrlResponseInfo info, @NonNull HttpException error)316 void onFailed(@NonNull UrlRequest request, 317 @Nullable UrlResponseInfo info, @NonNull HttpException error); 318 319 /** 320 * Invoked if request was canceled via {@link UrlRequest#cancel}. Once invoked, no other 321 * {@link Callback} methods will be invoked. Default implementation takes no action. 322 * 323 * @param request Request that was canceled. <strong>This is not guaranteed to be the same 324 * object as the one received by other callbacks, nor is it guaranteed to be the one 325 * returned by {@link URLRequest.Builder#build}.</strong> However, method calls on 326 * this object will have the same effects as calls on the original 327 * {@link URLRequest}. 328 * @param info Response information. May be {@code null} if no response was received. 329 */ onCanceled(@onNull UrlRequest request, @Nullable UrlResponseInfo info)330 void onCanceled(@NonNull UrlRequest request, @Nullable UrlResponseInfo info); 331 } 332 333 /** @hide */ 334 @Retention(RetentionPolicy.SOURCE) 335 @IntDef({ 336 Status.INVALID, 337 Status.IDLE, 338 Status.WAITING_FOR_STALLED_SOCKET_POOL, 339 Status.WAITING_FOR_AVAILABLE_SOCKET, 340 Status.WAITING_FOR_DELEGATE, 341 Status.WAITING_FOR_CACHE, 342 Status.DOWNLOADING_PAC_FILE, 343 Status.RESOLVING_PROXY_FOR_URL, 344 Status.RESOLVING_PROXY_FOR_URL, 345 Status.RESOLVING_HOST_IN_PAC_FILE, 346 Status.ESTABLISHING_PROXY_TUNNEL, 347 Status.RESOLVING_HOST, 348 Status.CONNECTING, 349 Status.SSL_HANDSHAKE, 350 Status.SENDING_REQUEST, 351 Status.WAITING_FOR_RESPONSE, 352 Status.READING_RESPONSE}) 353 public @interface UrlRequestStatus {} 354 355 /** 356 * Request status values returned by {@link #getStatus}. 357 */ 358 public static class Status { 359 /** 360 * This state indicates that the request is completed, canceled, or is not started. 361 */ 362 public static final int INVALID = -1; 363 /** 364 * This state corresponds to a resource load that has either not yet begun or is idle 365 * waiting for the consumer to do something to move things along (e.g. when the consumer of 366 * a {@link UrlRequest} has not called {@link UrlRequest#read read()} yet). 367 */ 368 public static final int IDLE = 0; 369 /** 370 * When a socket pool group is below the maximum number of sockets allowed per group, but a 371 * new socket cannot be created due to the per-pool socket limit, this state is returned by 372 * all requests for the group waiting on an idle connection, except those that may be 373 * serviced by a pending new connection. 374 */ 375 public static final int WAITING_FOR_STALLED_SOCKET_POOL = 1; 376 /** 377 * When a socket pool group has reached the maximum number of sockets allowed per group, 378 * this state is returned for all requests that don't have a socket, except those that 379 * correspond to a pending new connection. 380 */ 381 public static final int WAITING_FOR_AVAILABLE_SOCKET = 2; 382 /** 383 * This state indicates that the URLRequest delegate has chosen to block this request before 384 * it was sent over the network. 385 */ 386 public static final int WAITING_FOR_DELEGATE = 3; 387 /** 388 * This state corresponds to a resource load that is blocked waiting for access to a 389 * resource in the cache. If multiple requests are made for the same resource, the first 390 * request will be responsible for writing (or updating) the cache entry and the second 391 * request will be deferred until the first completes. This may be done to optimize for 392 * cache reuse. 393 */ 394 public static final int WAITING_FOR_CACHE = 4; 395 /** 396 * This state corresponds to a resource being blocked waiting for the PAC script to be 397 * downloaded. 398 */ 399 public static final int DOWNLOADING_PAC_FILE = 5; 400 /** 401 * This state corresponds to a resource load that is blocked waiting for a proxy autoconfig 402 * script to return a proxy server to use. 403 */ 404 public static final int RESOLVING_PROXY_FOR_URL = 6; 405 /** 406 * This state corresponds to a resource load that is blocked waiting for a proxy autoconfig 407 * script to return a proxy server to use, but that proxy script is busy resolving the IP 408 * address of a host. 409 */ 410 public static final int RESOLVING_HOST_IN_PAC_FILE = 7; 411 /** 412 * This state indicates that we're in the process of establishing a tunnel through the proxy 413 * server. 414 */ 415 public static final int ESTABLISHING_PROXY_TUNNEL = 8; 416 /** 417 * This state corresponds to a resource load that is blocked waiting for a host name to be 418 * resolved. This could either indicate resolution of the origin server corresponding to the 419 * resource or to the host name of a proxy server used to fetch the resource. 420 */ 421 public static final int RESOLVING_HOST = 9; 422 /** 423 * This state corresponds to a resource load that is blocked waiting for a TCP connection 424 * (or other network connection) to be established. HTTP requests that reuse a keep-alive 425 * connection skip this state. 426 */ 427 public static final int CONNECTING = 10; 428 /** 429 * This state corresponds to a resource load that is blocked waiting for the SSL handshake 430 * to complete. 431 */ 432 public static final int SSL_HANDSHAKE = 11; 433 /** 434 * This state corresponds to a resource load that is blocked waiting to completely upload a 435 * request to a server. In the case of a HTTP POST request, this state includes the period 436 * of time during which the message body is being uploaded. 437 */ 438 public static final int SENDING_REQUEST = 12; 439 /** 440 * This state corresponds to a resource load that is blocked waiting for the response to a 441 * network request. In the case of a HTTP transaction, this corresponds to the period after 442 * the request is sent and before all of the response headers have been received. 443 */ 444 public static final int WAITING_FOR_RESPONSE = 13; 445 /** 446 * This state corresponds to a resource load that is blocked waiting for a read to complete. 447 * In the case of a HTTP transaction, this corresponds to the period after the response 448 * headers have been received and before all of the response body has been downloaded. 449 * (NOTE: This state only applies for an {@link UrlRequest} while there is an outstanding 450 * {@link UrlRequest#read read()} operation.) 451 */ 452 public static final int READING_RESPONSE = 14; 453 Status()454 private Status() {} 455 } 456 457 /** 458 * Listener interface used with {@link #getStatus} to receive the status of a 459 * {@link UrlRequest}. 460 */ 461 public interface StatusListener { 462 /** 463 * Invoked on {@link UrlRequest}'s {@link Executor}'s thread when request status is 464 * obtained. 465 * 466 * @param status integer representing the status of the request. It is one of the values 467 * defined 468 * in {@link Status}. 469 */ onStatus(@rlRequestStatus int status)470 void onStatus(@UrlRequestStatus int status); 471 } 472 473 /** 474 * See {@link UrlRequest.Builder#setHttpMethod(String)}. 475 */ 476 @Nullable getHttpMethod()477 public abstract String getHttpMethod(); 478 479 /** 480 * See {@link UrlRequest.Builder#addHeader(String, String)} 481 */ 482 @NonNull getHeaders()483 public abstract HeaderBlock getHeaders(); 484 485 /** 486 * See {@link Builder#setCacheDisabled(boolean)} 487 */ isCacheDisabled()488 public abstract boolean isCacheDisabled(); 489 490 /** 491 * See {@link UrlRequest.Builder#setDirectExecutorAllowed(boolean)} 492 */ isDirectExecutorAllowed()493 public abstract boolean isDirectExecutorAllowed(); 494 495 /** 496 * See {@link Builder#setPriority(int)} 497 */ getPriority()498 public abstract int getPriority(); 499 500 /** 501 * See {@link Builder#setTrafficStatsTag(int)} 502 */ hasTrafficStatsTag()503 public abstract boolean hasTrafficStatsTag(); 504 505 /** 506 * See {@link Builder#setTrafficStatsTag(int)} 507 */ getTrafficStatsTag()508 public abstract int getTrafficStatsTag(); 509 510 /** 511 * See {@link Builder#setTrafficStatsUid(int)} 512 */ hasTrafficStatsUid()513 public abstract boolean hasTrafficStatsUid(); 514 515 /** 516 * See {@link Builder#setTrafficStatsUid(int)} 517 */ getTrafficStatsUid()518 public abstract int getTrafficStatsUid(); 519 520 /** 521 * Starts the request, all callbacks go to {@link Callback}. May only be called 522 * once. May not be called if {@link #cancel} has been called. 523 */ start()524 public abstract void start(); 525 526 /** 527 * Follows a pending redirect. Must only be called at most once for each invocation of {@link 528 * Callback#onRedirectReceived onRedirectReceived()}. 529 */ followRedirect()530 public abstract void followRedirect(); 531 532 /** 533 * Attempts to read part of the response body into the provided buffer. Must only be called at 534 * most once in response to each invocation of the {@link Callback#onResponseStarted 535 * onResponseStarted()} and {@link Callback#onReadCompleted onReadCompleted()} methods of the 536 * {@link Callback}. Each call will result in an asynchronous call to either the {@link Callback 537 * Callback's} {@link Callback#onReadCompleted onReadCompleted()} method if data is read, its 538 * {@link Callback#onSucceeded onSucceeded()} method if there's no more data to read, or its 539 * {@link Callback#onFailed onFailed()} method if there's an error. 540 * 541 * @param buffer {@link ByteBuffer} to write response body to. Must be a direct ByteBuffer. The 542 * embedder must not read or modify buffer's position, limit, or data between its position and 543 * limit until the request calls back into the {@link Callback}. 544 */ read(@onNull ByteBuffer buffer)545 public abstract void read(@NonNull ByteBuffer buffer); 546 547 /** 548 * Cancels the request. Can be called at any time. {@link Callback#onCanceled onCanceled()} will 549 * be invoked when cancellation is complete and no further callback methods will be invoked. If 550 * the request has completed or has not started, calling {@code cancel()} has no effect and 551 * {@code onCanceled()} will not be invoked. If the {@link Executor} passed in during {@code 552 * UrlRequest} construction runs tasks on a single thread, and {@code cancel()} is called on 553 * that thread, no callback methods (besides {@code onCanceled()}) will be invoked after {@code 554 * cancel()} is called. Otherwise, at most one callback method may be invoked after {@code 555 * cancel()} has completed. 556 */ cancel()557 public abstract void cancel(); 558 559 /** 560 * Returns {@code true} if the request was successfully started and is now finished (completed, 561 * canceled, or failed). 562 * 563 * @return {@code true} if the request was successfully started and is now finished (completed, 564 * canceled, or failed). 565 */ isDone()566 public abstract boolean isDone(); 567 568 /** 569 * Queries the status of the request. 570 * 571 * <p>This is most useful to query the status of the request before any of the 572 * {@link UrlRequest.Callback} methods are called by Cronet. 573 * 574 * <p>The {@code listener} will be invoked back on the {@link Executor} passed in when 575 * the request was created. While you can assume the callback will be invoked in a timely 576 * fashion, the API doesn't make any guarantees about the latency, nor does it specify the 577 * order in which the listener and other callbacks will be invoked. 578 * 579 * @param listener a {@link StatusListener} that will be invoked with 580 * the request's current status. 581 */ 582 // SuppressLint: The listener will be invoked back on the Executor passed in when the request 583 // was created. 584 @SuppressLint("ExecutorRegistration") getStatus(@onNull final StatusListener listener)585 public abstract void getStatus(@NonNull final StatusListener listener); 586 587 // Note: There are deliberately no accessors for the results of the request 588 // here. Having none removes any ambiguity over when they are populated, 589 // particularly in the redirect case. 590 } 591