Package com.google.android.exoplayer2.upstream

## Class DataSpec

- java.lang.Object
- - com.google.android.exoplayer2.upstream.DataSpec

-     public final class DataSpec
      extends Object

  Defines a region of data in a resource.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `DataSpec.Builder` | Builds `DataSpec` instances.
    `static interface` | `DataSpec.Flags` | The flags that apply to any request for data.
    `static interface` | `DataSpec.HttpMethod` | HTTP methods supported by ExoPlayer `HttpDataSource`s.

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `long` | `absoluteStreamPosition` | Deprecated. Use `position` except for specific use cases where the absolute position within the resource is required within a `DataSource` chain.
    `Object` | `customData` | Application specific data.
    `static int` | `FLAG_ALLOW_CACHE_FRAGMENTATION` | 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 int` | `FLAG_ALLOW_GZIP` | Allows an underlying network stack to request that the server use gzip compression.
    `static int` | `FLAG_DONT_CACHE_IF_LENGTH_UNKNOWN` | Prevents caching if the length cannot be resolved when the `DataSource` is opened.
    `static int` | `FLAG_MIGHT_NOT_USE_FULL_NETWORK_SPEED` | Indicates there are known external factors that might prevent the data from being loaded at full network speed (e.g.
    `@com.google.android.exoplayer2.upstream.DataSpec.Flags int` | `flags` | Request `flags`.
    `static int` | `HTTP_METHOD_GET` | HTTP GET method.
    `static int` | `HTTP_METHOD_HEAD` | HTTP HEAD method.
    `static int` | `HTTP_METHOD_POST` | HTTP POST method.
    `byte[]` | `httpBody` | The HTTP request body, null otherwise.
    `@com.google.android.exoplayer2.upstream.DataSpec.HttpMethod int` | `httpMethod` | The HTTP method to use when requesting the data.
    `Map<String,​String>` | `httpRequestHeaders` | Additional HTTP headers to use when requesting the data.
    `String` | `key` | A key that uniquely identifies the resource.
    `long` | `length` | The length of the data, or `C.LENGTH_UNSET`.
    `long` | `position` | The position of the data when read from `uri`.
    `Uri` | `uri` | A `Uri` from which data belonging to the resource can be read.
    `long` | `uriPositionOffset` | The offset of the data located at `uri` within the resource.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `DataSpec​(Uri uri)` | Constructs an instance.
    `DataSpec​(Uri uri, @com.google.android.exoplayer2.upstream.DataSpec.Flags int flags)` | Deprecated. Use `DataSpec.Builder`.
    `DataSpec​(Uri uri, @com.google.android.exoplayer2.upstream.DataSpec.HttpMethod int httpMethod, byte[] httpBody, long absoluteStreamPosition, long position, long length, String key, @com.google.android.exoplayer2.upstream.DataSpec.Flags int flags)` | Deprecated. Use `DataSpec.Builder`.
    `DataSpec​(Uri uri, @com.google.android.exoplayer2.upstream.DataSpec.HttpMethod int httpMethod, byte[] httpBody, long absoluteStreamPosition, long position, long length, String key, @com.google.android.exoplayer2.upstream.DataSpec.Flags int flags, Map<String,​String> httpRequestHeaders)` | Deprecated. Use `DataSpec.Builder`.
    `DataSpec​(Uri uri, byte[] postBody, long absoluteStreamPosition, long position, long length, String key, @com.google.android.exoplayer2.upstream.DataSpec.Flags int flags)` | Deprecated. Use `DataSpec.Builder`.
    `DataSpec​(Uri uri, long position, long length)` | Constructs an instance.
    `DataSpec​(Uri uri, long absoluteStreamPosition, long position, long length, String key, @com.google.android.exoplayer2.upstream.DataSpec.Flags int flags)` | Deprecated. Use `DataSpec.Builder`.
    `DataSpec​(Uri uri, long position, long length, String key)` | Deprecated. Use `DataSpec.Builder`.
    `DataSpec​(Uri uri, long position, long length, String key, @com.google.android.exoplayer2.upstream.DataSpec.Flags int flags)` | Deprecated. Use `DataSpec.Builder`.
    `DataSpec​(Uri uri, long position, long length, String key, @com.google.android.exoplayer2.upstream.DataSpec.Flags int flags, Map<String,​String> httpRequestHeaders)` | Deprecated. Use `DataSpec.Builder`.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `DataSpec.Builder` | `buildUpon()` | Returns a `DataSpec.Builder` initialized with the values of this instance.
    `String` | `getHttpMethodString()` | Returns the uppercase HTTP method name (e.g., "GET", "POST", "HEAD") corresponding to the `httpMethod`.
    `static String` | `getStringForHttpMethod​(@com.google.android.exoplayer2.upstream.DataSpec.HttpMethod int httpMethod)` | Returns an uppercase HTTP method name (e.g., "GET", "POST", "HEAD") corresponding to the given `DataSpec.HttpMethod`.
    `boolean` | `isFlagSet​(@com.google.android.exoplayer2.upstream.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.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### FLAG_ALLOW_GZIP

          public static final int FLAG_ALLOW_GZIP

      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 `DataSource` does make a network request, then the value returned from `DataSource.open(DataSpec)` will typically be `C.LENGTH_UNSET`. The data read from `DataReader.read(byte[], int, int)` will be the decompressed data.

      See Also:
        Constant Field Values

    - #### FLAG_DONT_CACHE_IF_LENGTH_UNKNOWN

          public static final int FLAG_DONT_CACHE_IF_LENGTH_UNKNOWN

      Prevents caching if the length cannot be resolved when the `DataSource` is opened.
      See Also:
        Constant Field Values

    - #### FLAG_ALLOW_CACHE_FRAGMENTATION

          public static final int FLAG_ALLOW_CACHE_FRAGMENTATION

      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).
      See Also:
        Constant Field Values

    - #### FLAG_MIGHT_NOT_USE_FULL_NETWORK_SPEED

          public static final int FLAG_MIGHT_NOT_USE_FULL_NETWORK_SPEED

      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).
      See Also:
        Constant Field Values

    - #### HTTP_METHOD_GET

          public static final int HTTP_METHOD_GET

      HTTP GET method.
      See Also:
        Constant Field Values

    - #### HTTP_METHOD_POST

          public static final int HTTP_METHOD_POST

      HTTP POST method.
      See Also:
        Constant Field Values

    - #### HTTP_METHOD_HEAD

          public static final int HTTP_METHOD_HEAD

      HTTP HEAD method.
      See Also:
        Constant Field Values

    - #### 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 `DataSource` 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.

    - #### httpMethod

          public final @com.google.android.exoplayer2.upstream.DataSpec.HttpMethod int httpMethod

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

    - #### httpBody

          @Nullable
          public final byte[] httpBody

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

    - #### 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 `HttpDataSource.setRequestProperty(String, String)`, and using `HttpDataSource.Factory.setDefaultRequestProperties(Map)`.

    - #### absoluteStreamPosition

          @Deprecated
          public final long absoluteStreamPosition

      Deprecated.
      Use `position` except for specific use cases where the absolute position within the resource is required within a `DataSource` chain. Where the absolute position is required, use `uriPositionOffset + position`.
      The absolute position of the data in the resource.

    - #### position

          public final long position

      The position of the data when read from `uri`.

    - #### length

          public final long length

      The length of the data, or `C.LENGTH_UNSET`.

    - #### key

          @Nullable
          public final 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.

    - #### flags

          public final @com.google.android.exoplayer2.upstream.DataSpec.Flags int flags

      Request `flags`.

    - #### customData

          @Nullable
          public final 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.

  - ### Constructor Detail

    - #### DataSpec

          public DataSpec​(Uri uri)

      Constructs an instance.
      Parameters:
        `uri` - `uri`.

    - #### DataSpec

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

      Constructs an instance.
      Parameters:
        `uri` - `uri`.
        `position` - `position`.
        `length` - `length`.

    - #### DataSpec

          @Deprecated
          public DataSpec​(Uri uri,
                          @com.google.android.exoplayer2.upstream.DataSpec.Flags int flags)

      Deprecated.
      Use `DataSpec.Builder`.
      Constructs an instance.
      Parameters:
        `uri` - `uri`.
        `flags` - `flags`.

    - #### DataSpec

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

      Deprecated.
      Use `DataSpec.Builder`.
      Constructs an instance.
      Parameters:
        `uri` - `uri`.
        `position` - `position`.
        `length` - `length`.
        `key` - `key`.

    - #### DataSpec

          @Deprecated
          public DataSpec​(Uri uri,
                          long position,
                          long length,
                          @Nullable
                          String key,
                          @com.google.android.exoplayer2.upstream.DataSpec.Flags int flags)

      Deprecated.
      Use `DataSpec.Builder`.
      Constructs an instance.
      Parameters:
        `uri` - `uri`.
        `position` - `position`.
        `length` - `length`.
        `key` - `key`.
        `flags` - `flags`.

    - #### DataSpec

          @Deprecated
          public DataSpec​(Uri uri,
                          long position,
                          long length,
                          @Nullable
                          String key,
                          @com.google.android.exoplayer2.upstream.DataSpec.Flags int flags,
                          Map<String,​String> httpRequestHeaders)

      Deprecated.
      Use `DataSpec.Builder`.
      Constructs an instance.
      Parameters:
        `uri` - `uri`.
        `position` - `position`, equal to `position`.
        `length` - `length`.
        `key` - `key`.
        `flags` - `flags`.
        `httpRequestHeaders` - `httpRequestHeaders`

    - #### DataSpec

          @Deprecated
          public DataSpec​(Uri uri,
                          long absoluteStreamPosition,
                          long position,
                          long length,
                          @Nullable
                          String key,
                          @com.google.android.exoplayer2.upstream.DataSpec.Flags int flags)

      Deprecated.
      Use `DataSpec.Builder`.
      Constructs an instance where `uriPositionOffset` may be non-zero.
      Parameters:
        `uri` - `uri`.
        `absoluteStreamPosition` - The sum of `uriPositionOffset` and `position`.
        `position` - `position`.
        `length` - `length`.
        `key` - `key`.
        `flags` - `flags`.

    - #### DataSpec

          @Deprecated
          public DataSpec​(Uri uri,
                          @Nullable
                          byte[] postBody,
                          long absoluteStreamPosition,
                          long position,
                          long length,
                          @Nullable
                          String key,
                          @com.google.android.exoplayer2.upstream.DataSpec.Flags int flags)

      Deprecated.
      Use `DataSpec.Builder`. Note that the httpMethod must be set explicitly for the Builder.
      Construct a instance where `uriPositionOffset` may be non-zero. The `httpMethod` is inferred from `postBody`. If `postBody` is non-null then `httpMethod` is set to `HTTP_METHOD_POST`. If `postBody` is null then `httpMethod` is set to `HTTP_METHOD_GET`.
      Parameters:
        `uri` - `uri`.
        `postBody` - `httpBody` The body of the HTTP request, which is also used to infer the `httpMethod`.
        `absoluteStreamPosition` - The sum of `uriPositionOffset` and `position`.
        `position` - `position`.
        `length` - `length`.
        `key` - `key`.
        `flags` - `flags`.

    - #### DataSpec

          @Deprecated
          public DataSpec​(Uri uri,
                          @com.google.android.exoplayer2.upstream.DataSpec.HttpMethod int httpMethod,
                          @Nullable
                          byte[] httpBody,
                          long absoluteStreamPosition,
                          long position,
                          long length,
                          @Nullable
                          String key,
                          @com.google.android.exoplayer2.upstream.DataSpec.Flags int flags)

      Deprecated.
      Use `DataSpec.Builder`.
      Construct a instance where `uriPositionOffset` may be non-zero.
      Parameters:
        `uri` - `uri`.
        `httpMethod` - `httpMethod`.
        `httpBody` - `httpBody`.
        `absoluteStreamPosition` - The sum of `uriPositionOffset` and `position`.
        `position` - `position`.
        `length` - `length`.
        `key` - `key`.
        `flags` - `flags`.

    - #### DataSpec

          @Deprecated
          public DataSpec​(Uri uri,
                          @com.google.android.exoplayer2.upstream.DataSpec.HttpMethod int httpMethod,
                          @Nullable
                          byte[] httpBody,
                          long absoluteStreamPosition,
                          long position,
                          long length,
                          @Nullable
                          String key,
                          @com.google.android.exoplayer2.upstream.DataSpec.Flags int flags,
                          Map<String,​String> httpRequestHeaders)

      Deprecated.
      Use `DataSpec.Builder`.
      Construct a instance where `uriPositionOffset` may be non-zero.
      Parameters:
        `uri` - `uri`.
        `httpMethod` - `httpMethod`.
        `httpBody` - `httpBody`.
        `absoluteStreamPosition` - The sum of `uriPositionOffset` and `position`.
        `position` - `position`.
        `length` - `length`.
        `key` - `key`.
        `flags` - `flags`.
        `httpRequestHeaders` - `httpRequestHeaders`.

  - ### Method Detail

    - #### getStringForHttpMethod

          public static String getStringForHttpMethod​(@com.google.android.exoplayer2.upstream.DataSpec.HttpMethod int httpMethod)

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

    - #### isFlagSet

          public boolean isFlagSet​(@com.google.android.exoplayer2.upstream.DataSpec.Flags int flag)

      Returns whether the given flag is set.
      Parameters:
        `flag` - Flag to be checked if it is set.

    - #### getHttpMethodString

          public final String getHttpMethodString()

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

    - #### buildUpon

          public DataSpec.Builder buildUpon()

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

    - #### 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:
        `offset` - The offset of the subrange.
      Returns:
        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:
        `offset` - The offset of the subrange.
        `length` - The length of the subrange.
      Returns:
        A data spec that represents a subrange of the data defined by this DataSpec.

    - #### withUri

          public DataSpec withUri​(Uri uri)

      Returns a copy of this data spec with the specified Uri.
      Parameters:
        `uri` - The new source `Uri`.
      Returns:
        The copied data spec with the specified Uri.

    - #### 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:
        `httpRequestHeaders` - The HTTP request headers.
      Returns:
        The copied data spec with the specified HTTP request headers.

    - #### 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:
        `additionalHttpRequestHeaders` - The additional HTTP request headers.
      Returns:
        The copied data spec with the additional HTTP request headers.

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`