Package com.google.android.exoplayer2.testutil

## Class DataSourceContractTest

- java.lang.Object
- - com.google.android.exoplayer2.testutil.DataSourceContractTest

-     public abstract class DataSourceContractTest
      extends Object

  A collection of contract tests for `DataSource` implementations.

  All these tests should pass for all implementations - behaviour specific to only a subset of implementations should be tested elsewhere.

  Subclasses should only include the logic necessary to construct the DataSource and allow it to successfully read data. They shouldn't include any new `@Test` methods - implementation-specific tests should be in a separate class.

  If one of these tests fails for a particular `DataSource` implementation, that's a bug in the implementation. The test should be overridden in the subclass and annotated `Ignore`, with a link to an issue to track fixing the implementation and un-ignoring the test.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `DataSourceContractTest.FakeTransferListener` | A `TransferListener` that only keeps track of the transferred bytes.
    `static class` | `DataSourceContractTest.TestResource` | Information about a resource that can be used to test the `DataSource` instance.

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `AdditionalFailureInfo` | `additionalFailureInfo` |

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `DataSourceContractTest()` |

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected abstract DataSource` | `createDataSource()` | Creates and returns an instance of the `DataSource`.
    `void` | `dataSpecWithEndPositionOutOfRange_readsToEnd()` |
    `void` | `dataSpecWithLength_readExpectedRange()` |
    `void` | `dataSpecWithPosition_readUntilEnd()` |
    `void` | `dataSpecWithPositionAndLength_readExpectedRange()` |
    `void` | `dataSpecWithPositionAtEnd_throwsPositionOutOfRangeException()` |
    `void` | `dataSpecWithPositionAtEndAndLength_throwsPositionOutOfRangeException()` |
    `void` | `dataSpecWithPositionOutOfRange_throwsPositionOutOfRangeException()` |
    `protected abstract Uri` | `getNotFoundUri()` | Returns a `Uri` that doesn't resolve.
    `void` | `getResponseHeaders_isEmptyWhileNotOpen()` |
    `void` | `getResponseHeaders_resourceNotFound_isEmptyWhileNotOpen()` |
    `protected abstract ImmutableList<DataSourceContractTest.TestResource>` | `getTestResources()` | Returns `DataSourceContractTest.TestResource` instances.
    `protected DataSource` | `getTransferListenerDataSource()` | Returns the `DataSource` that will be included in the `TransferListener` callbacks for the `DataSource` most recently created by `createDataSource()`.
    `void` | `getUri_resourceNotFound_returnsNullIfNotOpened()` |
    `void` | `getUri_returnsNonNullValueOnlyWhileOpen()` |
    `void` | `resourceNotFound()` |
    `void` | `resourceNotFound_transferListenerCallbacks()` |
    `void` | `transferListenerCallbacks()` |
    `void` | `unboundedDataSpec_readUntilEnd()` |
    `void` | `unboundedDataSpecWithGzipFlag_readUntilEnd()` | `DataSpec.FLAG_ALLOW_GZIP` should either be ignored by `DataSource` implementations, or correctly handled (i.e.
    `protected boolean` | `unboundedReadsAreIndefinite()` | Returns whether the `DataSource` will continue reading indefinitely for unbounded `DataSpecs`.

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

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

- - ### Field Detail

    - #### additionalFailureInfo

          public final AdditionalFailureInfo additionalFailureInfo

  - ### Constructor Detail

    - #### DataSourceContractTest

          public DataSourceContractTest()

  - ### Method Detail

    - #### createDataSource

          protected abstract DataSource createDataSource()
                                                  throws Exception

      Creates and returns an instance of the `DataSource`.
      Throws:
        `Exception`

    - #### getTransferListenerDataSource

          @Nullable
          protected DataSource getTransferListenerDataSource()

      Returns the `DataSource` that will be included in the `TransferListener` callbacks for the `DataSource` most recently created by `createDataSource()`. If it's the same `DataSource` then `null` can be returned.

    - #### unboundedReadsAreIndefinite

          protected boolean unboundedReadsAreIndefinite()

      Returns whether the `DataSource` will continue reading indefinitely for unbounded `DataSpecs`.

    - #### getTestResources

          protected abstract ImmutableList<DataSourceContractTest.TestResource> getTestResources()
                                                                                          throws Exception

      Returns `DataSourceContractTest.TestResource` instances.

      Each resource will be used to exercise the `DataSource` instance, allowing different behaviours to be tested.

      If multiple resources are returned, it's recommended to disambiguate them using `DataSourceContractTest.TestResource.Builder.setName(String)`.

      Throws:
        `Exception`

    - #### getNotFoundUri

          protected abstract Uri getNotFoundUri()

      Returns a `Uri` that doesn't resolve.

      This is used to test how a `DataSource` handles nonexistent data.

    - #### unboundedDataSpec_readUntilEnd

          public void unboundedDataSpec_readUntilEnd()
                                              throws Exception

      Throws:
        `Exception`

    - #### dataSpecWithPosition_readUntilEnd

          public void dataSpecWithPosition_readUntilEnd()
                                                 throws Exception

      Throws:
        `Exception`

    - #### dataSpecWithLength_readExpectedRange

          public void dataSpecWithLength_readExpectedRange()
                                                    throws Exception

      Throws:
        `Exception`

    - #### dataSpecWithPositionAndLength_readExpectedRange

          public void dataSpecWithPositionAndLength_readExpectedRange()
                                                               throws Exception

      Throws:
        `Exception`

    - #### dataSpecWithPositionAtEnd_throwsPositionOutOfRangeException

          public void dataSpecWithPositionAtEnd_throwsPositionOutOfRangeException()
                                                                           throws Exception

      Throws:
        `Exception`

    - #### dataSpecWithPositionAtEndAndLength_throwsPositionOutOfRangeException

          public void dataSpecWithPositionAtEndAndLength_throwsPositionOutOfRangeException()
                                                                                    throws Exception

      Throws:
        `Exception`

    - #### dataSpecWithPositionOutOfRange_throwsPositionOutOfRangeException

          public void dataSpecWithPositionOutOfRange_throwsPositionOutOfRangeException()
                                                                                throws Exception

      Throws:
        `Exception`

    - #### dataSpecWithEndPositionOutOfRange_readsToEnd

          public void dataSpecWithEndPositionOutOfRange_readsToEnd()
                                                            throws Exception

      Throws:
        `Exception`

    - #### unboundedDataSpecWithGzipFlag_readUntilEnd

          public void unboundedDataSpecWithGzipFlag_readUntilEnd()
                                                          throws Exception

      `DataSpec.FLAG_ALLOW_GZIP` should either be ignored by `DataSource` implementations, or correctly handled (i.e. the data is decompressed before being returned from `DataReader.read(byte[], int, int)`).
      Throws:
        `Exception`

    - #### resourceNotFound

          public void resourceNotFound()
                                throws Exception

      Throws:
        `Exception`

    - #### transferListenerCallbacks

          public void transferListenerCallbacks()
                                         throws Exception

      Throws:
        `Exception`

    - #### resourceNotFound_transferListenerCallbacks

          public void resourceNotFound_transferListenerCallbacks()
                                                          throws Exception

      Throws:
        `Exception`

    - #### getUri_returnsNonNullValueOnlyWhileOpen

          public void getUri_returnsNonNullValueOnlyWhileOpen()
                                                       throws Exception

      Throws:
        `Exception`

    - #### getUri_resourceNotFound_returnsNullIfNotOpened

          public void getUri_resourceNotFound_returnsNullIfNotOpened()
                                                              throws Exception

      Throws:
        `Exception`

    - #### getResponseHeaders_isEmptyWhileNotOpen

          public void getResponseHeaders_isEmptyWhileNotOpen()
                                                      throws Exception

      Throws:
        `Exception`

    - #### getResponseHeaders_resourceNotFound_isEmptyWhileNotOpen

          public void getResponseHeaders_resourceNotFound_isEmptyWhileNotOpen()
                                                                       throws Exception

      Throws:
        `Exception`