| // Copyright 2014 The Chromium Authors |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| |
| package org.chromium.net; |
| |
| import java.nio.ByteBuffer; |
| import java.util.concurrent.Executor; |
| |
| import androidx.annotation.NonNull; |
| import androidx.annotation.Nullable; |
| |
| /** |
| * Controls an HTTP request (GET, PUT, POST etc). Created by {@link UrlRequest.Builder}, which can |
| * be obtained by calling {@link CronetEngine#newUrlRequestBuilder}. Note: All methods must be |
| * called on the {@link Executor} passed to {@link CronetEngine#newUrlRequestBuilder}. |
| */ |
| public abstract class UrlRequest { |
| /** |
| * Builder for {@link UrlRequest}s. Allows configuring requests before constructing them with |
| * {@link Builder#build}. The builder can be created by calling {@link |
| * CronetEngine#newUrlRequestBuilder}. |
| */ |
| public abstract static class Builder { |
| /** |
| * Sets the HTTP method verb to use for this request. |
| * |
| * <p>The default when this method is not called is "GET" if the request has |
| * no body or "POST" if it does. |
| * |
| * @param method "GET", "HEAD", "DELETE", "POST" or "PUT". |
| * @return the builder to facilitate chaining. |
| */ |
| public abstract Builder setHttpMethod(String method); |
| |
| /** |
| * Adds a request header. |
| * |
| * @param header header name. |
| * @param value header value. |
| * @return the builder to facilitate chaining. |
| */ |
| public abstract Builder addHeader(String header, String value); |
| |
| /** |
| * Disables cache for the request. If context is not set up to use cache, this call has no |
| * effect. |
| * |
| * @return the builder to facilitate chaining. |
| */ |
| public abstract Builder disableCache(); |
| |
| /** Lowest request priority. Passed to {@link #setPriority}. */ |
| public static final int REQUEST_PRIORITY_IDLE = 0; |
| |
| /** Very low request priority. Passed to {@link #setPriority}. */ |
| public static final int REQUEST_PRIORITY_LOWEST = 1; |
| |
| /** Low request priority. Passed to {@link #setPriority}. */ |
| public static final int REQUEST_PRIORITY_LOW = 2; |
| |
| /** |
| * Medium request priority. Passed to {@link #setPriority}. This is the default priority |
| * given to the request. |
| */ |
| public static final int REQUEST_PRIORITY_MEDIUM = 3; |
| |
| /** Highest request priority. Passed to {@link #setPriority}. */ |
| public static final int REQUEST_PRIORITY_HIGHEST = 4; |
| |
| /** |
| * Sets priority of the request which should be one of the {@link #REQUEST_PRIORITY_IDLE |
| * REQUEST_PRIORITY_*} values. The request is given {@link #REQUEST_PRIORITY_MEDIUM} |
| * priority if this method is not called. |
| * |
| * @param priority priority of the request which should be one of the {@link |
| * #REQUEST_PRIORITY_IDLE REQUEST_PRIORITY_*} values. |
| * @return the builder to facilitate chaining. |
| */ |
| public abstract Builder setPriority(int priority); |
| |
| /** |
| * Sets upload data provider. Switches method to "POST" if not explicitly set. Starting the |
| * request will throw an exception if a Content-Type header is not set. |
| * |
| * @param uploadDataProvider responsible for providing the upload data. |
| * @param executor All {@code uploadDataProvider} methods will be invoked using this {@code |
| * Executor}. May optionally be the same {@code Executor} the request itself is using. |
| * @return the builder to facilitate chaining. |
| */ |
| public abstract Builder setUploadDataProvider( |
| UploadDataProvider uploadDataProvider, Executor executor); |
| |
| /** |
| * Marks that the executors this request will use to notify callbacks (for {@code |
| * UploadDataProvider}s and {@code UrlRequest.Callback}s) is intentionally performing inline |
| * execution, like Guava's directExecutor or {@link |
| * java.util.concurrent.ThreadPoolExecutor.CallerRunsPolicy}. |
| * |
| * <p><b>Warning:</b> This option makes it easy to accidentally block the network thread. |
| * It should not be used if your callbacks perform disk I/O, acquire locks, or call into |
| * other code you don't carefully control and audit. |
| */ |
| public abstract Builder allowDirectExecutor(); |
| |
| /** |
| * Associates the annotation object with this request. May add more than one. Passed through |
| * to a {@link RequestFinishedInfo.Listener}, see {@link |
| * RequestFinishedInfo#getAnnotations}. |
| * |
| * @param annotation an object to pass on to the {@link RequestFinishedInfo.Listener} with a |
| * {@link RequestFinishedInfo}. |
| * @return the builder to facilitate chaining. |
| */ |
| public Builder addRequestAnnotation(Object annotation) { |
| return this; |
| } |
| |
| /** |
| * Binds the request to the specified network handle. Cronet will send this request only |
| * using the network associated to this handle. If this network disconnects the request will |
| * fail, the exact error will depend on the stage of request processing when the network |
| * disconnects. Network handles can be obtained through {@code Network#getNetworkHandle}. |
| * Only available starting from Android Marshmallow. |
| * |
| * @param networkHandle the network handle to bind the request to. Specify {@link |
| * CronetEngine#UNBIND_NETWORK_HANDLE} to unbind. |
| * @return the builder to facilitate chaining. |
| */ |
| public Builder bindToNetwork(long networkHandle) { |
| return this; |
| } |
| |
| /** |
| * Sets {@link android.net.TrafficStats} tag to use when accounting socket traffic caused by |
| * this request. See {@link android.net.TrafficStats} for more information. If no tag is set |
| * (e.g. this method isn't called), then Android accounts for the socket traffic caused by |
| * this request as if the tag value were set to 0. <p> <b>NOTE:</b>Setting a tag disallows |
| * sharing of sockets with requests with other tags, which may adversely effect performance |
| * by prohibiting connection sharing. In other words use of multiplexed sockets (e.g. HTTP/2 |
| * and QUIC) will only be allowed if all requests have the same socket tag. |
| * |
| * @param tag the tag value used to when accounting for socket traffic caused by this |
| * request. |
| * Tags between 0xFFFFFF00 and 0xFFFFFFFF are reserved and used internally by system |
| * services like {@link android.app.DownloadManager} when performing traffic on behalf of an |
| * application. |
| * @return the builder to facilitate chaining. |
| */ |
| public Builder setTrafficStatsTag(int tag) { |
| return this; |
| } |
| |
| /** |
| * Sets specific UID to use when accounting socket traffic caused by this request. See |
| * {@link android.net.TrafficStats} for more information. Designed for use when performing |
| * an operation on behalf of another application. Caller must hold {@code |
| * MODIFY_NETWORK_ACCOUNTING} permission. By default traffic is attributed to UID of caller. |
| * |
| * <p><b>NOTE:</b>Setting a UID disallows sharing of sockets with requests with other UIDs, |
| * which may adversely effect performance by prohibiting connection sharing. In other words |
| * use of multiplexed sockets (e.g. HTTP/2 and QUIC) will only be allowed if all requests |
| * have the same UID set. |
| * |
| * @param uid the UID to attribute socket traffic caused by this request. |
| * @return the builder to facilitate chaining. |
| */ |
| public Builder setTrafficStatsUid(int uid) { |
| return this; |
| } |
| |
| /** |
| * Sets a listener that gets invoked after {@link Callback#onCanceled onCanceled()}, {@link |
| * Callback#onFailed onFailed()} or {@link Callback#onSucceeded onSucceeded()} return. |
| * |
| * <p>The listener is invoked with the request finished info on an |
| * {@link java.util.concurrent.Executor} provided by {@link |
| * RequestFinishedInfo.Listener#getExecutor getExecutor()}. |
| * |
| * @param listener the listener for finished requests. |
| * @return the builder to facilitate chaining. |
| */ |
| public Builder setRequestFinishedListener(RequestFinishedInfo.Listener listener) { |
| return this; |
| } |
| |
| /** |
| * Creates a {@link UrlRequest} using configuration within this {@link Builder}. The |
| * returned |
| * {@code UrlRequest} can then be started by calling {@link UrlRequest#start}. |
| * |
| * @return constructed {@link UrlRequest} using configuration within this {@link Builder}. |
| */ |
| public abstract UrlRequest build(); |
| } |
| |
| /** |
| * Users of Cronet extend this class to receive callbacks indicating the progress of a {@link |
| * UrlRequest} being processed. An instance of this class is passed in to {@link |
| * UrlRequest.Builder}'s constructor when constructing the {@code UrlRequest}. |
| * <p> |
| * Note: All methods will be invoked on the thread of the {@link java.util.concurrent.Executor} |
| * used during construction of the {@code UrlRequest}. |
| */ |
| public abstract static class Callback { |
| /** |
| * Invoked whenever a redirect is encountered. This will only be invoked between the call to |
| * {@link UrlRequest#start} and {@link Callback#onResponseStarted onResponseStarted()}. The |
| * body of the redirect response, if it has one, will be ignored. |
| * |
| * 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 info Response information. |
| * @param newLocationUrl Location where request is redirected. |
| * @throws Exception if an error occurs while processing a redirect. {@link #onFailed} will |
| * be |
| * called with the thrown exception set as the cause of the {@link CallbackException}. |
| */ |
| public abstract void onRedirectReceived( |
| UrlRequest request, UrlResponseInfo info, String newLocationUrl) throws Exception; |
| |
| /** |
| * Invoked when the final set of headers, after all redirects, is received. Will only be |
| * invoked once for each request. |
| * |
| * With the exception of {@link Callback#onCanceled onCanceled()}, no other {@link Callback} |
| * method will be invoked for the request, including {@link Callback#onSucceeded |
| * 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 info Response information. |
| * @throws Exception if an error occurs while processing response start. {@link #onFailed} |
| * will |
| * be called with the thrown exception set as the cause of the {@link CallbackException}. |
| */ |
| public abstract void onResponseStarted(UrlRequest request, UrlResponseInfo info) |
| throws Exception; |
| |
| /** |
| * Invoked whenever part of the response body has been read. Only part of the buffer may be |
| * populated, even if the entire response body has not yet been consumed. |
| * |
| * With the exception of {@link Callback#onCanceled onCanceled()}, no other {@link Callback} |
| * method will be invoked for the request, including {@link Callback#onSucceeded |
| * 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 info Response information. |
| * @param byteBuffer The buffer that was passed in to {@link UrlRequest#read |
| * UrlRequest.read()}, |
| * now containing the received data. The buffer's position is updated to the end of the |
| * received data. The buffer's limit is not changed. |
| * @throws Exception if an error occurs while processing a read completion. {@link |
| * #onFailed} |
| * will be called with the thrown exception set as the cause of the {@link |
| * CallbackException}. |
| */ |
| public abstract void onReadCompleted( |
| UrlRequest request, UrlResponseInfo info, ByteBuffer byteBuffer) throws Exception; |
| |
| /** |
| * Invoked when request is completed successfully. Once invoked, no other {@link Callback} |
| * methods will be invoked. |
| * |
| * @param request Request that succeeded. |
| * @param info Response information. |
| */ |
| public abstract void onSucceeded(UrlRequest request, UrlResponseInfo info); |
| |
| /** |
| * Invoked if request failed for any reason after {@link UrlRequest#start}. Once invoked, no |
| * other {@link Callback} methods will be invoked. {@code error} provides information about |
| * the failure. |
| * |
| * @param request Request that failed. |
| * @param info Response information. May be {@code null} if no response was received. |
| * @param error information about error. |
| */ |
| public abstract void onFailed( |
| UrlRequest request, UrlResponseInfo info, CronetException error); |
| |
| /** |
| * 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 info Response information. May be {@code null} if no response was received. |
| */ |
| public void onCanceled(UrlRequest request, UrlResponseInfo info) {} |
| } |
| |
| /** Request status values returned by {@link #getStatus}. */ |
| public static class Status { |
| /** This state indicates that the request is completed, canceled, or is not started. */ |
| public static final int INVALID = -1; |
| |
| /** |
| * This state corresponds to a resource load that has either not yet begun or is idle |
| * waiting for the consumer to do something to move things along (e.g. when the consumer of |
| * a {@link UrlRequest} has not called {@link UrlRequest#read read()} yet). |
| */ |
| public static final int IDLE = 0; |
| |
| /** |
| * When a socket pool group is below the maximum number of sockets allowed per group, but a |
| * new socket cannot be created due to the per-pool socket limit, this state is returned by |
| * all requests for the group waiting on an idle connection, except those that may be |
| * serviced by a pending new connection. |
| */ |
| public static final int WAITING_FOR_STALLED_SOCKET_POOL = 1; |
| |
| /** |
| * When a socket pool group has reached the maximum number of sockets allowed per group, |
| * this state is returned for all requests that don't have a socket, except those that |
| * correspond to a pending new connection. |
| */ |
| public static final int WAITING_FOR_AVAILABLE_SOCKET = 2; |
| |
| /** |
| * This state indicates that the URLRequest delegate has chosen to block this request before |
| * it was sent over the network. |
| */ |
| public static final int WAITING_FOR_DELEGATE = 3; |
| |
| /** |
| * This state corresponds to a resource load that is blocked waiting for access to a |
| * resource in the cache. If multiple requests are made for the same resource, the first |
| * request will be responsible for writing (or updating) the cache entry and the second |
| * request will be deferred until the first completes. This may be done to optimize for |
| * cache reuse. |
| */ |
| public static final int WAITING_FOR_CACHE = 4; |
| |
| /** |
| * This state corresponds to a resource being blocked waiting for the PAC script to be |
| * downloaded. |
| */ |
| public static final int DOWNLOADING_PAC_FILE = 5; |
| |
| /** |
| * This state corresponds to a resource load that is blocked waiting for a proxy autoconfig |
| * script to return a proxy server to use. |
| */ |
| public static final int RESOLVING_PROXY_FOR_URL = 6; |
| |
| /** |
| * This state corresponds to a resource load that is blocked waiting for a proxy autoconfig |
| * script to return a proxy server to use, but that proxy script is busy resolving the IP |
| * address of a host. |
| */ |
| public static final int RESOLVING_HOST_IN_PAC_FILE = 7; |
| |
| /** |
| * This state indicates that we're in the process of establishing a tunnel through the proxy |
| * server. |
| */ |
| public static final int ESTABLISHING_PROXY_TUNNEL = 8; |
| |
| /** |
| * This state corresponds to a resource load that is blocked waiting for a host name to be |
| * resolved. This could either indicate resolution of the origin server corresponding to the |
| * resource or to the host name of a proxy server used to fetch the resource. |
| */ |
| public static final int RESOLVING_HOST = 9; |
| |
| /** |
| * This state corresponds to a resource load that is blocked waiting for a TCP connection |
| * (or other network connection) to be established. HTTP requests that reuse a keep-alive |
| * connection skip this state. |
| */ |
| public static final int CONNECTING = 10; |
| |
| /** |
| * This state corresponds to a resource load that is blocked waiting for the SSL handshake |
| * to complete. |
| */ |
| public static final int SSL_HANDSHAKE = 11; |
| |
| /** |
| * This state corresponds to a resource load that is blocked waiting to completely upload a |
| * request to a server. In the case of a HTTP POST request, this state includes the period |
| * of time during which the message body is being uploaded. |
| */ |
| public static final int SENDING_REQUEST = 12; |
| |
| /** |
| * This state corresponds to a resource load that is blocked waiting for the response to a |
| * network request. In the case of a HTTP transaction, this corresponds to the period after |
| * the request is sent and before all of the response headers have been received. |
| */ |
| public static final int WAITING_FOR_RESPONSE = 13; |
| |
| /** |
| * This state corresponds to a resource load that is blocked waiting for a read to complete. |
| * In the case of a HTTP transaction, this corresponds to the period after the response |
| * headers have been received and before all of the response body has been downloaded. |
| * (NOTE: This state only applies for an {@link UrlRequest} while there is an outstanding |
| * {@link UrlRequest#read read()} operation.) |
| */ |
| public static final int READING_RESPONSE = 14; |
| |
| private Status() {} |
| } |
| |
| /** Listener class used with {@link #getStatus} to receive the status of a {@link UrlRequest}. */ |
| public abstract static class StatusListener { |
| /** |
| * Invoked on {@link UrlRequest}'s {@link Executor}'s thread when request status is |
| * obtained. |
| * |
| * @param status integer representing the status of the request. It is one of the values |
| * defined |
| * in {@link Status}. |
| */ |
| public abstract void onStatus(int status); |
| } |
| |
| /** |
| * See {@link UrlRequest.Builder#setHttpMethod(String)}. |
| */ |
| @Nullable |
| public abstract String getHttpMethod(); |
| |
| /** |
| * See {@link UrlRequest.Builder#addHeader(String, String)} |
| */ |
| @NonNull |
| public abstract UrlResponseInfo.HeaderBlock getHeaders(); |
| |
| /** |
| * See {@link Builder#setCacheDisabled(boolean)} |
| */ |
| public abstract boolean isCacheDisabled(); |
| |
| /** |
| * See {@link UrlRequest.Builder#setDirectExecutorAllowed(boolean)} |
| */ |
| public abstract boolean isDirectExecutorAllowed(); |
| |
| /** |
| * See {@link Builder#setPriority(int)} |
| */ |
| public abstract int getPriority(); |
| |
| /** |
| * See {@link Builder#setTrafficStatsTag(int)} |
| */ |
| public abstract boolean hasTrafficStatsTag(); |
| |
| /** |
| * See {@link Builder#setTrafficStatsTag(int)} |
| */ |
| public abstract int getTrafficStatsTag(); |
| |
| /** |
| * See {@link Builder#setTrafficStatsUid(int)} |
| */ |
| public abstract boolean hasTrafficStatsUid(); |
| |
| /** |
| * See {@link Builder#setTrafficStatsUid(int)} |
| */ |
| public abstract int getTrafficStatsUid(); |
| |
| /** |
| * Starts the request, all callbacks go to {@link Callback}. May only be called once. May not be |
| * called if {@link #cancel} has been called. |
| */ |
| public abstract void start(); |
| |
| /** |
| * Follows a pending redirect. Must only be called at most once for each invocation of {@link |
| * Callback#onRedirectReceived onRedirectReceived()}. |
| */ |
| public abstract void followRedirect(); |
| |
| /** |
| * Attempts to read part of the response body into the provided buffer. Must only be called at |
| * most once in response to each invocation of the {@link Callback#onResponseStarted |
| * onResponseStarted()} and {@link Callback#onReadCompleted onReadCompleted()} methods of the |
| * {@link Callback}. Each call will result in an asynchronous call to either the {@link Callback |
| * Callback's} {@link Callback#onReadCompleted onReadCompleted()} method if data is read, its |
| * {@link Callback#onSucceeded onSucceeded()} method if there's no more data to read, or its |
| * {@link Callback#onFailed onFailed()} method if there's an error. |
| * |
| * @param buffer {@link ByteBuffer} to write response body to. Must be a direct ByteBuffer. The |
| * embedder must not read or modify buffer's position, limit, or data between its position and |
| * limit until the request calls back into the {@link Callback}. |
| */ |
| public abstract void read(ByteBuffer buffer); |
| |
| /** |
| * Cancels the request. Can be called at any time. {@link Callback#onCanceled onCanceled()} will |
| * be invoked when cancellation is complete and no further callback methods will be invoked. If |
| * the request has completed or has not started, calling {@code cancel()} has no effect and |
| * {@code onCanceled()} will not be invoked. If the {@link Executor} passed in during {@code |
| * UrlRequest} construction runs tasks on a single thread, and {@code cancel()} is called on |
| * that thread, no callback methods (besides {@code onCanceled()}) will be invoked after {@code |
| * cancel()} is called. Otherwise, at most one callback method may be invoked after {@code |
| * cancel()} has completed. |
| */ |
| public abstract void cancel(); |
| |
| /** |
| * Returns {@code true} if the request was successfully started and is now finished (completed, |
| * canceled, or failed). |
| * |
| * @return {@code true} if the request was successfully started and is now finished (completed, |
| * canceled, or failed). |
| */ |
| public abstract boolean isDone(); |
| |
| /** |
| * Queries the status of the request. |
| * |
| * @param listener a {@link StatusListener} that will be invoked with the request's current |
| * status. {@code listener} will be invoked back on the {@link Executor} passed in when the |
| * request was created. |
| */ |
| public abstract void getStatus(final StatusListener listener); |
| |
| // Note: There are deliberately no accessors for the results of the request |
| // here. Having none removes any ambiguity over when they are populated, |
| // particularly in the redirect case. |
| } |
