Package com.google.android.exoplayer2.source.ads

## Class AdPlaybackState

- java.lang.Object
- - com.google.android.exoplayer2.source.ads.AdPlaybackState

- All Implemented Interfaces:
    `Bundleable`

      public final class AdPlaybackState
      extends Object
      implements Bundleable

  Represents ad group times and information on the state and URIs of ads within each ad group.

  Instances are immutable. Call the `with*` methods to get new instances that have the required changes.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `AdPlaybackState.AdGroup` | Represents a group of ads, with information about their states.
    `static interface` | `AdPlaybackState.AdState` | Represents the state of an ad in an ad group.

    - ### Nested classes/interfaces inherited from interface com.google.android.exoplayer2.Bundleable

      `Bundleable.Creator<T extends Bundleable>`

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static int` | `AD_STATE_AVAILABLE` | State for an ad that has a URL but has not yet been played.
    `static int` | `AD_STATE_ERROR` | State for an ad that could not be loaded.
    `static int` | `AD_STATE_PLAYED` | State for an ad that was played in full.
    `static int` | `AD_STATE_SKIPPED` | State for an ad that was skipped.
    `static int` | `AD_STATE_UNAVAILABLE` | State for an ad that does not yet have a URL.
    `int` | `adGroupCount` | The number of ad groups.
    `long` | `adResumePositionUs` | The position offset in the first unplayed ad at which to begin playback, in microseconds.
    `Object` | `adsId` | The opaque identifier for ads with which this instance is associated, or `null` if unset.
    `long` | `contentDurationUs` | The duration of the content period in microseconds, if known.
    `static Bundleable.Creator<AdPlaybackState>` | `CREATOR` | Object that can restore `AdPlaybackState` from a `Bundle`.
    `static AdPlaybackState` | `NONE` | Ad playback state with no ads.
    `int` | `removedAdGroupCount` | The number of ad groups that have been removed.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `AdPlaybackState​(Object adsId, long... adGroupTimesUs)` | Creates a new ad playback state with the specified ad group times.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `equals​(Object o)` |
    `static AdPlaybackState` | `fromAdPlaybackState​(Object adsId, AdPlaybackState adPlaybackState)` | Returns a copy of the ad playback state with the given ads ID.
    `AdPlaybackState.AdGroup` | `getAdGroup​(int adGroupIndex)` | Returns the specified `AdPlaybackState.AdGroup`.
    `int` | `getAdGroupIndexAfterPositionUs​(long positionUs, long periodDurationUs)` | Returns the index of the next ad group after `positionUs` that should be played.
    `int` | `getAdGroupIndexForPositionUs​(long positionUs, long periodDurationUs)` | Returns the index of the ad group at or before `positionUs` that should be played before the content at `positionUs`.
    `int` | `hashCode()` |
    `boolean` | `isAdInErrorState​(int adGroupIndex, int adIndexInAdGroup)` | Returns whether the specified ad has been marked as in `AD_STATE_ERROR`.
    `Bundle` | `toBundle()` | Returns a `Bundle` representing the information stored in this object.
    `String` | `toString()` |
    `AdPlaybackState` | `withAdCount​(int adGroupIndex, int adCount)` | Returns an instance with the number of ads in `adGroupIndex` resolved to `adCount`.
    `AdPlaybackState` | `withAdDurationsUs​(int adGroupIndex, long... adDurationsUs)` | Returns an instance with the specified ad durations, in microseconds, in the specified ad group.
    `AdPlaybackState` | `withAdDurationsUs​(long[][] adDurationUs)` | Returns an instance with the specified ad durations, in microseconds.
    `AdPlaybackState` | `withAdGroupTimeUs​(int adGroupIndex, long adGroupTimeUs)` | Returns an instance with the specified ad group time.
    `AdPlaybackState` | `withAdLoadError​(int adGroupIndex, int adIndexInAdGroup)` | Returns an instance with the specified ad marked as having a load error.
    `AdPlaybackState` | `withAdResumePositionUs​(long adResumePositionUs)` | Returns an instance with the specified ad resume position, in microseconds, relative to the start of the current ad.
    `AdPlaybackState` | `withAvailableAd​(int adGroupIndex, int adIndexInAdGroup)` | Returns an instance with the specified ad marked as available.
    `AdPlaybackState` | `withAvailableAdUri​(int adGroupIndex, int adIndexInAdGroup, Uri uri)` | Returns an instance with the specified ad URI and the ad marked as available.
    `AdPlaybackState` | `withContentDurationUs​(long contentDurationUs)` | Returns an instance with the specified content duration, in microseconds.
    `AdPlaybackState` | `withContentResumeOffsetUs​(int adGroupIndex, long contentResumeOffsetUs)` | Returns an instance with the specified `AdPlaybackState.AdGroup.contentResumeOffsetUs`, in microseconds, for the specified ad group.
    `AdPlaybackState` | `withIsServerSideInserted​(int adGroupIndex, boolean isServerSideInserted)` | Returns an instance with the specified value for `AdPlaybackState.AdGroup.isServerSideInserted` in the specified ad group.
    `AdPlaybackState` | `withLastAdRemoved​(int adGroupIndex)` | Returns an instance with the last ad of the given ad group removed.
    `AdPlaybackState` | `withNewAdGroup​(int adGroupIndex, long adGroupTimeUs)` | Returns an instance with a new ad group.
    `AdPlaybackState` | `withOriginalAdCount​(int adGroupIndex, int originalAdCount)` | Returns an instance with the specified value for `AdPlaybackState.AdGroup.originalCount` in the specified ad group.
    `AdPlaybackState` | `withPlayedAd​(int adGroupIndex, int adIndexInAdGroup)` | Returns an instance with the specified ad marked as played.
    `AdPlaybackState` | `withRemovedAdGroupCount​(int removedAdGroupCount)` | Returns an instance with the specified number of `removed ad groups`.
    `AdPlaybackState` | `withResetAdGroup​(int adGroupIndex)` | Returns an instance with all ads in the specified ad group reset from final states (played, skipped, error) to either available or unavailable, which allows to play them again.
    `AdPlaybackState` | `withSkippedAd​(int adGroupIndex, int adIndexInAdGroup)` | Returns an instance with the specified ad marked as skipped.
    `AdPlaybackState` | `withSkippedAdGroup​(int adGroupIndex)` | Returns an instance with all ads in the specified ad group skipped (except for those already marked as played or in the error state).

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

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

- - ### Field Detail

    - #### AD_STATE_UNAVAILABLE

          public static final int AD_STATE_UNAVAILABLE

      State for an ad that does not yet have a URL.
      See Also:
        Constant Field Values

    - #### AD_STATE_AVAILABLE

          public static final int AD_STATE_AVAILABLE

      State for an ad that has a URL but has not yet been played.
      See Also:
        Constant Field Values

    - #### AD_STATE_SKIPPED

          public static final int AD_STATE_SKIPPED

      State for an ad that was skipped.
      See Also:
        Constant Field Values

    - #### AD_STATE_PLAYED

          public static final int AD_STATE_PLAYED

      State for an ad that was played in full.
      See Also:
        Constant Field Values

    - #### AD_STATE_ERROR

          public static final int AD_STATE_ERROR

      State for an ad that could not be loaded.
      See Also:
        Constant Field Values

    - #### NONE

          public static final AdPlaybackState NONE

      Ad playback state with no ads.

    - #### adsId

          @Nullable
          public final Object adsId

      The opaque identifier for ads with which this instance is associated, or `null` if unset.

    - #### adGroupCount

          public final int adGroupCount

      The number of ad groups.

    - #### adResumePositionUs

          public final long adResumePositionUs

      The position offset in the first unplayed ad at which to begin playback, in microseconds.

    - #### contentDurationUs

          public final long contentDurationUs

      The duration of the content period in microseconds, if known. `C.TIME_UNSET` otherwise.

    - #### removedAdGroupCount

          public final int removedAdGroupCount

      The number of ad groups that have been removed. Ad groups with indices between `0` (inclusive) and `removedAdGroupCount` (exclusive) will be empty and must not be modified by any of the `with*` methods.

    - #### CREATOR

          public static final Bundleable.Creator<AdPlaybackState> CREATOR

      Object that can restore `AdPlaybackState` from a `Bundle`.

      The `adsId` of restored instances will always be `null`.

  - ### Constructor Detail

    - #### AdPlaybackState

          public AdPlaybackState​(Object adsId,
                                 long... adGroupTimesUs)

      Creates a new ad playback state with the specified ad group times.
      Parameters:
        `adsId` - The opaque identifier for ads with which this instance is associated.
        `adGroupTimesUs` - The times of ad groups in microseconds, relative to the start of the `Timeline.Period` they belong to. A final element with the value `C.TIME_END_OF_SOURCE` indicates that there is a postroll ad.

  - ### Method Detail

    - #### getAdGroup

          public AdPlaybackState.AdGroup getAdGroup​(@IntRange(from=0L)
                                                    int adGroupIndex)

      Returns the specified `AdPlaybackState.AdGroup`.

    - #### getAdGroupIndexForPositionUs

          public int getAdGroupIndexForPositionUs​(long positionUs,
                                                  long periodDurationUs)

      Returns the index of the ad group at or before `positionUs` that should be played before the content at `positionUs`. Returns `C.INDEX_UNSET` if the ad group at or before `positionUs` has no ads remaining to be played, or if there is no such ad group.
      Parameters:
        `positionUs` - The period position at or before which to find an ad group, in microseconds, or `C.TIME_END_OF_SOURCE` for the end of the stream (in which case the index of any unplayed postroll ad group will be returned).
        `periodDurationUs` - The duration of the containing timeline period, in microseconds, or `C.TIME_UNSET` if not known.
      Returns:
        The index of the ad group, or `C.INDEX_UNSET`.

    - #### getAdGroupIndexAfterPositionUs

          public int getAdGroupIndexAfterPositionUs​(long positionUs,
                                                    long periodDurationUs)

      Returns the index of the next ad group after `positionUs` that should be played. Returns `C.INDEX_UNSET` if there is no such ad group.
      Parameters:
        `positionUs` - The period position after which to find an ad group, in microseconds, or `C.TIME_END_OF_SOURCE` for the end of the stream (in which case there can be no ad group after the position).
        `periodDurationUs` - The duration of the containing timeline period, in microseconds, or `C.TIME_UNSET` if not known.
      Returns:
        The index of the ad group, or `C.INDEX_UNSET`.

    - #### isAdInErrorState

          public boolean isAdInErrorState​(@IntRange(from=0L)
                                          int adGroupIndex,
                                          @IntRange(from=0L)
                                          int adIndexInAdGroup)

      Returns whether the specified ad has been marked as in `AD_STATE_ERROR`.

    - #### withAdGroupTimeUs

          @CheckResult
          public AdPlaybackState withAdGroupTimeUs​(@IntRange(from=0L)
                                                   int adGroupIndex,
                                                   long adGroupTimeUs)

      Returns an instance with the specified ad group time.
      Parameters:
        `adGroupIndex` - The index of the ad group.
        `adGroupTimeUs` - The new ad group time, in microseconds, or `C.TIME_END_OF_SOURCE` to indicate a postroll ad.
      Returns:
        The updated ad playback state.

    - #### withNewAdGroup

          @CheckResult
          public AdPlaybackState withNewAdGroup​(@IntRange(from=0L)
                                                int adGroupIndex,
                                                long adGroupTimeUs)

      Returns an instance with a new ad group.
      Parameters:
        `adGroupIndex` - The insertion index of the new group.
        `adGroupTimeUs` - The ad group time, in microseconds, or `C.TIME_END_OF_SOURCE` to indicate a postroll ad.
      Returns:
        The updated ad playback state.

    - #### withAdCount

          @CheckResult
          public AdPlaybackState withAdCount​(@IntRange(from=0L)
                                             int adGroupIndex,
                                             @IntRange(from=1L)
                                             int adCount)

      Returns an instance with the number of ads in `adGroupIndex` resolved to `adCount`. The ad count must be greater than zero.

    - #### withAvailableAdUri

          @CheckResult
          public AdPlaybackState withAvailableAdUri​(@IntRange(from=0L)
                                                    int adGroupIndex,
                                                    @IntRange(from=0L)
                                                    int adIndexInAdGroup,
                                                    Uri uri)

      Returns an instance with the specified ad URI and the ad marked as available.
      Throws:
        `IllegalStateException` - If `Uri.EMPTY` is passed as argument for a client-side inserted ad group.

    - #### withAvailableAd

          @CheckResult
          public AdPlaybackState withAvailableAd​(@IntRange(from=0L)
                                                 int adGroupIndex,
                                                 @IntRange(from=0L)
                                                 int adIndexInAdGroup)

      Returns an instance with the specified ad marked as available.

      Must not be called with client side inserted ad groups. Client side inserted ads should use `withAvailableAdUri(int, int, android.net.Uri)`.

      Throws:
        `IllegalStateException` - in case this methods is called on an ad group that is not server side inserted.

    - #### withPlayedAd

          @CheckResult
          public AdPlaybackState withPlayedAd​(@IntRange(from=0L)
                                              int adGroupIndex,
                                              @IntRange(from=0L)
                                              int adIndexInAdGroup)

      Returns an instance with the specified ad marked as played.

    - #### withSkippedAd

          @CheckResult
          public AdPlaybackState withSkippedAd​(@IntRange(from=0L)
                                               int adGroupIndex,
                                               @IntRange(from=0L)
                                               int adIndexInAdGroup)

      Returns an instance with the specified ad marked as skipped.

    - #### withLastAdRemoved

          @CheckResult
          public AdPlaybackState withLastAdRemoved​(@IntRange(from=0L)
                                                   int adGroupIndex)

      Returns an instance with the last ad of the given ad group removed.

    - #### withAdLoadError

          @CheckResult
          public AdPlaybackState withAdLoadError​(@IntRange(from=0L)
                                                 int adGroupIndex,
                                                 @IntRange(from=0L)
                                                 int adIndexInAdGroup)

      Returns an instance with the specified ad marked as having a load error.

    - #### withSkippedAdGroup

          @CheckResult
          public AdPlaybackState withSkippedAdGroup​(@IntRange(from=0L)
                                                    int adGroupIndex)

      Returns an instance with all ads in the specified ad group skipped (except for those already marked as played or in the error state).

    - #### withAdDurationsUs

          @CheckResult
          public AdPlaybackState withAdDurationsUs​(long[][] adDurationUs)

      Returns an instance with the specified ad durations, in microseconds.

      Must only be used if `removedAdGroupCount` is 0.

    - #### withAdDurationsUs

          @CheckResult
          public AdPlaybackState withAdDurationsUs​(@IntRange(from=0L)
                                                   int adGroupIndex,
                                                   long... adDurationsUs)

      Returns an instance with the specified ad durations, in microseconds, in the specified ad group.

    - #### withAdResumePositionUs

          @CheckResult
          public AdPlaybackState withAdResumePositionUs​(long adResumePositionUs)

      Returns an instance with the specified ad resume position, in microseconds, relative to the start of the current ad.

    - #### withContentDurationUs

          @CheckResult
          public AdPlaybackState withContentDurationUs​(long contentDurationUs)

      Returns an instance with the specified content duration, in microseconds.

    - #### withRemovedAdGroupCount

          @CheckResult
          public AdPlaybackState withRemovedAdGroupCount​(@IntRange(from=0L)
                                                         int removedAdGroupCount)

      Returns an instance with the specified number of `removed ad groups`.

      Ad groups with indices between `0` (inclusive) and `removedAdGroupCount` (exclusive) will be empty and must not be modified by any of the `with*` methods.

    - #### withContentResumeOffsetUs

          @CheckResult
          public AdPlaybackState withContentResumeOffsetUs​(@IntRange(from=0L)
                                                           int adGroupIndex,
                                                           long contentResumeOffsetUs)

      Returns an instance with the specified `AdPlaybackState.AdGroup.contentResumeOffsetUs`, in microseconds, for the specified ad group.

    - #### withOriginalAdCount

          @CheckResult
          public AdPlaybackState withOriginalAdCount​(@IntRange(from=0L)
                                                     int adGroupIndex,
                                                     int originalAdCount)

      Returns an instance with the specified value for `AdPlaybackState.AdGroup.originalCount` in the specified ad group.

    - #### withIsServerSideInserted

          @CheckResult
          public AdPlaybackState withIsServerSideInserted​(@IntRange(from=0L)
                                                          int adGroupIndex,
                                                          boolean isServerSideInserted)

      Returns an instance with the specified value for `AdPlaybackState.AdGroup.isServerSideInserted` in the specified ad group.

    - #### withResetAdGroup

          @CheckResult
          public AdPlaybackState withResetAdGroup​(@IntRange(from=0L)
                                                  int adGroupIndex)

      Returns an instance with all ads in the specified ad group reset from final states (played, skipped, error) to either available or unavailable, which allows to play them again.

    - #### fromAdPlaybackState

          public static AdPlaybackState fromAdPlaybackState​(Object adsId,
                                                            AdPlaybackState adPlaybackState)

      Returns a copy of the ad playback state with the given ads ID.
      Parameters:
        `adsId` - The new ads ID.
        `adPlaybackState` - The ad playback state to copy.
      Returns:
        The new ad playback state.

    - #### equals

          public boolean equals​(@Nullable
                                Object o)

      Overrides:
        `equals` in class `Object`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### toBundle

          public Bundle toBundle()

      Returns a `Bundle` representing the information stored in this object.

      It omits the `adsId` field so the `adsId` of instances restored by `CREATOR` will always be `null`.

      Specified by:
        `toBundle` in interface `Bundleable`