UrlRequest.Builder

public static abstract class UrlRequest.Builder extends Object

Builder for UrlRequests. Allows configuring requests before constructing them with build(). The builder can be created by calling CronetEngine.newUrlRequestBuilder(String, UrlRequest.Callback, Executor).

Constant Summary

int	REQUEST_PRIORITY_HIGHEST	Highest request priority.
int	REQUEST_PRIORITY_IDLE	Lowest request priority.
int	REQUEST_PRIORITY_LOW	Low request priority.
int	REQUEST_PRIORITY_LOWEST	Very low request priority.
int	REQUEST_PRIORITY_MEDIUM	Medium request priority.

Public Constructor Summary

Builder()

Public Method Summary

abstract UrlRequest.Builder	addHeader(String header, String value) Adds a request header.
UrlRequest.Builder	addRequestAnnotation(Object annotation) Associates the annotation object with this request.
abstract UrlRequest.Builder	allowDirectExecutor() Marks that the executors this request will use to notify callbacks (for `UploadDataProvider`s and `UrlRequest.Callback`s) is intentionally performing inline execution, like Guava's directExecutor or `ThreadPoolExecutor.CallerRunsPolicy`.
abstract UrlRequest	build() Creates a `UrlRequest` using configuration within this `UrlRequest.Builder`.
abstract UrlRequest.Builder	disableCache() Disables cache for the request.
abstract UrlRequest.Builder	setHttpMethod(String method) Sets the HTTP method verb to use for this request.
abstract UrlRequest.Builder	setPriority(int priority) Sets priority of the request which should be one of the `REQUEST_PRIORITY_*` values.
UrlRequest.Builder	setRequestFinishedListener(RequestFinishedInfo.Listener listener) Sets a listener that gets invoked after `onCanceled()`, `onFailed()` or `onSucceeded()` return.
UrlRequest.Builder	setTrafficStatsTag(int tag) Sets `TrafficStats` tag to use when accounting socket traffic caused by this request.
UrlRequest.Builder	setTrafficStatsUid(int uid) Sets specific UID to use when accounting socket traffic caused by this request.
abstract UrlRequest.Builder	setUploadDataProvider(UploadDataProvider uploadDataProvider, Executor executor) Sets upload data provider.

Inherited Method Summary

From class java.lang.Object

Object	clone()
boolean	equals(Object arg0)
void	finalize()
final Class<?>	getClass()
int	hashCode()
final void	notify()
final void	notifyAll()
String	toString()
final void	wait(long arg0, int arg1)
final void	wait(long arg0)
final void	wait()

Constants

public static final int REQUEST_PRIORITY_HIGHEST

Highest request priority. Passed to setPriority(int).

Constant Value: 4

public static final int REQUEST_PRIORITY_IDLE

Lowest request priority. Passed to setPriority(int).

Constant Value: 0

public static final int REQUEST_PRIORITY_LOW

Low request priority. Passed to setPriority(int).

Constant Value: 2

public static final int REQUEST_PRIORITY_LOWEST

Very low request priority. Passed to setPriority(int).

Constant Value: 1

public static final int REQUEST_PRIORITY_MEDIUM

Medium request priority. Passed to setPriority(int). This is the default priority given to the request.

Constant Value: 3

Public Constructors

public Builder ()

Public Methods

public abstract UrlRequest.Builder addHeader (String header, String value)

Adds a request header.

Parameters

header	header name.
value	header value.

Returns

the builder to facilitate chaining.

public UrlRequest.Builder addRequestAnnotation (Object annotation)

Associates the annotation object with this request. May add more than one. Passed through to a RequestFinishedInfo.Listener, see RequestFinishedInfo.getAnnotations().

Parameters

annotation	an object to pass on to the `RequestFinishedInfo.Listener` with a `RequestFinishedInfo`.

Returns

the builder to facilitate chaining.

public abstract UrlRequest.Builder allowDirectExecutor ()

Marks that the executors this request will use to notify callbacks (for UploadDataProviders and UrlRequest.Callbacks) is intentionally performing inline execution, like Guava's directExecutor or ThreadPoolExecutor.CallerRunsPolicy.

Warning: 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 UrlRequest build ()

Creates a UrlRequest using configuration within this UrlRequest.Builder. The returned UrlRequest can then be started by calling UrlRequest.start().

Returns

constructed UrlRequest using configuration within this UrlRequest.Builder.

public abstract UrlRequest.Builder disableCache ()

Disables cache for the request. If context is not set up to use cache, this call has no effect.

Returns

the builder to facilitate chaining.

public abstract UrlRequest.Builder setHttpMethod (String method)

Sets the HTTP method verb to use for this request.

The default when this method is not called is "GET" if the request has no body or "POST" if it does.

Parameters

method	"GET", "HEAD", "DELETE", "POST" or "PUT".

Returns

the builder to facilitate chaining.

public abstract UrlRequest.Builder setPriority (int priority)

Sets priority of the request which should be one of the REQUEST_PRIORITY_* values. The request is given REQUEST_PRIORITY_MEDIUM priority if this method is not called.

Parameters

priority	priority of the request which should be one of the `REQUEST_PRIORITY_*` values.

Returns

the builder to facilitate chaining.

public UrlRequest.Builder setRequestFinishedListener (RequestFinishedInfo.Listener listener)

Sets a listener that gets invoked after onCanceled(), onFailed() or onSucceeded() return.

The listener is invoked with the request finished info on an Executor provided by getExecutor().

Parameters

listener	the listener for finished requests.

Returns

the builder to facilitate chaining.

public UrlRequest.Builder setTrafficStatsTag (int tag)

Sets TrafficStats tag to use when accounting socket traffic caused by this request. See 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.

NOTE: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.

Parameters

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 `DownloadManager` when performing traffic on behalf of an application.

Returns

the builder to facilitate chaining.

public UrlRequest.Builder setTrafficStatsUid (int uid)

Sets specific UID to use when accounting socket traffic caused by this request. See TrafficStats for more information. Designed for use when performing an operation on behalf of another application. Caller must hold MODIFY_NETWORK_ACCOUNTING permission. By default traffic is attributed to UID of caller.

NOTE: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.

Parameters

uid	the UID to attribute socket traffic caused by this request.

Returns

the builder to facilitate chaining.

public abstract UrlRequest.Builder setUploadDataProvider (UploadDataProvider uploadDataProvider, Executor executor)

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.

Parameters

uploadDataProvider	responsible for providing the upload data.
executor	All `uploadDataProvider` methods will be invoked using this `Executor`. May optionally be the same `Executor` the request itself is using.

Returns

the builder to facilitate chaining.