DataSpec

Artifact: androidx.media3:media3-datasource

Kotlin |Java

@UnstableApi
public final class DataSpec

Defines a region of data in a resource.

Summary

Nested types
`public final class DataSpec.Builder` Builds `DataSpec` instances.
`@Documented @Retention(value = RetentionPolicy.SOURCE) @Target(value = TYPE_USE) @IntDef(flag = true, value = ) public annotation DataSpec.Flags` The flags that apply to any request for data.
`@Documented @Retention(value = RetentionPolicy.SOURCE) @Target(value = TYPE_USE) @IntDef(value = ) public annotation DataSpec.HttpMethod` HTTP methods supported by ExoPlayer `HttpDataSource`s.

Constants
`static final int`	`FLAG_ALLOW_CACHE_FRAGMENTATION = 4` Allows fragmentation of this request into multiple cache files, meaning a cache eviction policy will be able to evict individual fragments of the data.
`static final int`	`FLAG_ALLOW_GZIP = 1` Allows an underlying network stack to request that the server use gzip compression.
`static final int`	`FLAG_DONT_CACHE_IF_LENGTH_UNKNOWN = 2` Prevents caching if the length cannot be resolved when the `DataSource` is opened.
`static final int`	`FLAG_MIGHT_NOT_USE_FULL_NETWORK_SPEED = 8` Indicates there are known external factors that might prevent the data from being loaded at full network speed (e.g. server throttling or unfinished live media chunks).
`static final int`	`HTTP_METHOD_GET = 1` HTTP GET method.
`static final int`	`HTTP_METHOD_HEAD = 3` HTTP HEAD method.
`static final int`	`HTTP_METHOD_POST = 2` HTTP POST method.

Public fields
`final long`	`absoluteStreamPosition` This field is deprecated. Use `position` except for specific use cases where the absolute position within the resource is required within a `DataSource` chain.
`final @Nullable Object`	`customData` Application specific data.
`final int`	`@DataSpec.Flags flags` Request `flags`.
`final @Nullable byte[]`	`httpBody` The HTTP request body, null otherwise.
`final int`	`@DataSpec.HttpMethod httpMethod` The HTTP method to use when requesting the data.
`final Map<String, String>`	`httpRequestHeaders` Additional HTTP headers to use when requesting the data.
`final @Nullable String`	`key` A key that uniquely identifies the resource.
`final long`	`length` The length of the data, or `LENGTH_UNSET`.
`final long`	`position` The position of the data when read from `uri`.
`final Uri`	`uri` A `Uri` from which data belonging to the resource can be read.
`final long`	`uriPositionOffset` The offset of the data located at `uri` within the resource.

Public constructors
`DataSpec(Uri uri)` Constructs an instance.
`DataSpec(Uri uri, long position, long length)` Constructs an instance.
`DataSpec(Uri uri, long position, long length, @Nullable String key)` This method is deprecated. Use `Builder`.

Public constructors

DataSpec(Uri uri)

Constructs an instance.

DataSpec(Uri uri, long position, long length)

Constructs an instance.

DataSpec(Uri uri, long position, long length, @Nullable String key)

This method is deprecated.

Use Builder.

Public methods
`DataSpec.Builder`	`buildUpon()` Returns a `DataSpec.Builder` initialized with the values of this instance.
`final String`	`getHttpMethodString()` Returns the uppercase HTTP method name (e.g., "GET", "POST", "HEAD") corresponding to the `httpMethod`.
`static String`	`getStringForHttpMethod(@DataSpec.HttpMethod int httpMethod)` Returns an uppercase HTTP method name (e.g., "GET", "POST", "HEAD") corresponding to the given `HttpMethod`.
`boolean`	`isFlagSet(@DataSpec.Flags int flag)` Returns whether the given flag is set.
`DataSpec`	`subrange(long offset)` Returns a data spec that represents a subrange of the data defined by this DataSpec.
`DataSpec`	`subrange(long offset, long length)` Returns a data spec that represents a subrange of the data defined by this DataSpec.
`String`	`toString()`
`DataSpec`	`withAdditionalHeaders( Map<String, String> additionalHttpRequestHeaders )` Returns a copy this data spec with additional HTTP request headers.
`DataSpec`	`withRequestHeaders(Map<String, String> httpRequestHeaders)` Returns a copy of this data spec with the specified HTTP request headers.
`DataSpec`	`withUri(Uri uri)` Returns a copy of this data spec with the specified Uri.

Constants

FLAG_ALLOW_CACHE_FRAGMENTATION

public static final int FLAG_ALLOW_CACHE_FRAGMENTATION = 4

Allows fragmentation of this request into multiple cache files, meaning a cache eviction policy will be able to evict individual fragments of the data. Depending on the cache implementation, setting this flag may also enable more concurrent access to the data (e.g. reading one fragment whilst writing another).

FLAG_ALLOW_GZIP

public static final int FLAG_ALLOW_GZIP = 1

Allows an underlying network stack to request that the server use gzip compression.

Should not typically be set if the data being requested is already compressed (e.g. most audio and video requests). May be set when requesting other data.

When a DataSource is used to request data with this flag set, and if the does make a network request, then the value returned from open will typically be LENGTH_UNSET. The data read from read will be the decompressed data.

FLAG_DONT_CACHE_IF_LENGTH_UNKNOWN

public static final int FLAG_DONT_CACHE_IF_LENGTH_UNKNOWN = 2

Prevents caching if the length cannot be resolved when the DataSource is opened.

FLAG_MIGHT_NOT_USE_FULL_NETWORK_SPEED

public static final int FLAG_MIGHT_NOT_USE_FULL_NETWORK_SPEED = 8

Indicates there are known external factors that might prevent the data from being loaded at full network speed (e.g. server throttling or unfinished live media chunks).

HTTP_METHOD_GET

public static final int HTTP_METHOD_GET = 1

HTTP GET method.

HTTP_METHOD_HEAD

public static final int HTTP_METHOD_HEAD = 3

HTTP HEAD method.

HTTP_METHOD_POST

public static final int HTTP_METHOD_POST = 2

HTTP POST method.

Public fields

absoluteStreamPosition

public final long absoluteStreamPosition

The absolute position of the data in the resource.

customData

public final @Nullable Object customData

Application specific data.

This field is intended for advanced use cases in which applications require the ability to attach custom data to DataSpec instances. The custom data should be immutable.

flags

@DataSpec.Flags
public final int flags

Request flags.

httpBody

public final @Nullable byte[] httpBody

The HTTP request body, null otherwise. If the body is non-null, then httpBody.length will be non-zero.

httpMethod

@DataSpec.HttpMethod
public final int httpMethod

The HTTP method to use when requesting the data. This value will be ignored by non-HTTP implementations.

httpRequestHeaders

public final Map<String, String> httpRequestHeaders

Additional HTTP headers to use when requesting the data.

Note: This map is for additional headers specific to the data being requested. It does not include headers that are set directly by HttpDataSource implementations. In particular, this means the following headers are not included:

Range: HttpDataSource implementations derive the Range header from position and length.
Accept-Encoding: HttpDataSource implementations derive the Accept-Encoding header based on whether flags includes FLAG_ALLOW_GZIP.
User-Agent: HttpDataSource implementations set the User-Agent header directly.
Other headers set at the HttpDataSource layer. I.e., headers set using setRequestProperty, and using setDefaultRequestProperties.

key

public final @Nullable String key

A key that uniquely identifies the resource. Used for cache indexing. May be null if the data spec is not intended to be used in conjunction with a cache.

length

public final long length

The length of the data, or LENGTH_UNSET.

position

public final long position

The position of the data when read from uri.

uri

public final Uri uri

A Uri from which data belonging to the resource can be read.

uriPositionOffset

public final long uriPositionOffset

The offset of the data located at uri within the resource.

Equal to 0 unless uri provides access to a subset of the resource. As an example, consider a resource that can be requested over the network and is 1000 bytes long. If uri points to a local file that contains just bytes [200-300], then this field will be set to 200.

This field can be ignored except for in specific circumstances where the absolute position in the resource is required in a DataSource chain. One example is when a needs to decrypt the content as it's read. In this case the absolute position in the resource is typically needed to correctly initialize the decryption algorithm.

Public constructors

DataSpec

public DataSpec(Uri uri)

Constructs an instance.

Parameters
`Uri uri`	`uri`.

DataSpec

public DataSpec(Uri uri, long position, long length)

Constructs an instance.

Parameters
`Uri uri`	`uri`.
`long position`	`position`.
`long length`	`length`.

DataSpec

public DataSpec(Uri uri, long position, long length, @Nullable String key)

Constructs an instance.

Parameters
`Uri uri`	`uri`.
`long position`	`position`.
`long length`	`length`.
`@Nullable String key`	`key`.

Public methods

buildUpon

public DataSpec.Builder buildUpon()

Returns a DataSpec.Builder initialized with the values of this instance.

getHttpMethodString

public final String getHttpMethodString()

Returns the uppercase HTTP method name (e.g., "GET", "POST", "HEAD") corresponding to the httpMethod.

getStringForHttpMethod

public static String getStringForHttpMethod(@DataSpec.HttpMethod int httpMethod)

Returns an uppercase HTTP method name (e.g., "GET", "POST", "HEAD") corresponding to the given HttpMethod.

isFlagSet

public boolean isFlagSet(@DataSpec.Flags int flag)

Returns whether the given flag is set.

Parameters
`@DataSpec.Flags int flag`	Flag to be checked if it is set.

subrange

public DataSpec subrange(long offset)

Returns a data spec that represents a subrange of the data defined by this DataSpec. The subrange includes data from the offset up to the end of this DataSpec.

Parameters
`long offset`	The offset of the subrange.

Returns
`DataSpec`	A data spec that represents a subrange of the data defined by this DataSpec.

subrange

public DataSpec subrange(long offset, long length)

Returns a data spec that represents a subrange of the data defined by this DataSpec.

Parameters
`long offset`	The offset of the subrange.
`long length`	The length of the subrange.

Returns
`DataSpec`	A data spec that represents a subrange of the data defined by this DataSpec.

toString

public String toString()

withAdditionalHeaders

public DataSpec withAdditionalHeaders(
    Map<String, String> additionalHttpRequestHeaders
)

Returns a copy this data spec with additional HTTP request headers. Headers in additionalHttpRequestHeaders will overwrite any headers already in the data spec that have the same keys.

Parameters
`Map<String, String> additionalHttpRequestHeaders`	The additional HTTP request headers.

Returns
`DataSpec`	The copied data spec with the additional HTTP request headers.

withRequestHeaders

public DataSpec withRequestHeaders(Map<String, String> httpRequestHeaders)

Returns a copy of this data spec with the specified HTTP request headers. Headers already in the data spec are not copied to the new instance.

Parameters
`Map<String, String> httpRequestHeaders`	The HTTP request headers.

Returns
`DataSpec`	The copied data spec with the specified HTTP request headers.

withUri

public DataSpec withUri(Uri uri)

Returns a copy of this data spec with the specified Uri.

Parameters
`Uri uri`	The new source `Uri`.

Returns
`DataSpec`	The copied data spec with the specified Uri.

DataSpec

Summary

Nested types

Constants

Public fields

Public constructors

Public methods

Constants

FLAG_ALLOW_CACHE_FRAGMENTATION

FLAG_ALLOW_GZIP

FLAG_DONT_CACHE_IF_LENGTH_UNKNOWN

FLAG_MIGHT_NOT_USE_FULL_NETWORK_SPEED

HTTP_METHOD_GET

HTTP_METHOD_HEAD

HTTP_METHOD_POST

Public fields

absoluteStreamPosition

customData

flags

httpBody

httpMethod

httpRequestHeaders

key

length

position

uri

uriPositionOffset

Public constructors

DataSpec

DataSpec

DataSpec

Public methods

buildUpon

getHttpMethodString

getStringForHttpMethod

isFlagSet

subrange

subrange

toString

withAdditionalHeaders

withRequestHeaders

withUri