Package com.castlabs.android.player.exceptions

# Class PlaylistException

java.lang.Object
java.lang.Throwable
java.lang.Exception
com.castlabs.android.player.exceptions.PlaylistException

All Implemented Interfaces:
  `Serializable`

public class PlaylistException extends Exception
Exception that represents a playlist-related error. This exception provides additional context about which playlist item failed and the current playlist state, allowing applications to implement their own recovery logic.

There are two types of playlist errors:

- `CastlabsPlayerException.TYPE_PLAYLIST_ITEM_PREFETCH_FAILED` - A non-fatal warning when an item fails to load during background prefetch. The application can handle this and decide how to proceed.
- `CastlabsPlayerException.TYPE_PLAYLIST_ITEM_TRANSITION_FAILED` - A fatal error when the player tries to transition to an item that failed to load. This occurs either when the application didn't handle the prefetch warning, or when direct navigation targets an item that cannot be loaded.

See Also:
  - Serialized Form

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static PlaylistException`
  `create(PlayerConfig failedConfig, int failedItemIndex, int currentItemIndex, List<PlayerConfig> playlistSnapshot, Throwable cause)`
  Creates a PlaylistException.
  `int`
  `getCurrentItemIndex()`
  Returns the index of the item that was playing when the error occurred.
  `PlayerConfig`
  `getFailedConfig()`
  Returns the configuration of the playlist item that failed to load.
  `int`
  `getFailedItemIndex()`
  Returns the index of the failed item in the playlist.
  `ArrayList<PlayerConfig>`
  `getPlaylistSnapshot()`
  Returns a snapshot of the playlist at the time of the error.

  ### Methods inherited from class java.lang.Throwable

  `addSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString`

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

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

- ## Method Details

  - ### create

    @NonNull public static PlaylistException create(@NonNull PlayerConfig failedConfig, int failedItemIndex, int currentItemIndex, @NonNull List<PlayerConfig> playlistSnapshot, @Nullable Throwable cause)
    Creates a PlaylistException.
    Parameters:
      `failedConfig` - The configuration of the item that failed to load
      `failedItemIndex` - The index of the failed item in the playlist
      `currentItemIndex` - The index of the currently playing item
      `playlistSnapshot` - A snapshot of the current playlist
      `cause` - The underlying cause of the failure
    Returns:
      A new PlaylistException instance

  - ### getFailedConfig

    @NonNull public PlayerConfig getFailedConfig()
    Returns the configuration of the playlist item that failed to load.
    Returns:
      The failed item's PlayerConfig

  - ### getFailedItemIndex

    public int getFailedItemIndex()
    Returns the index of the failed item in the playlist.
    Returns:
      The index of the failed item

  - ### getCurrentItemIndex

    public int getCurrentItemIndex()
    Returns the index of the item that was playing when the error occurred.
    Returns:
      The index of the current item

  - ### getPlaylistSnapshot

    @NonNull public ArrayList<PlayerConfig> getPlaylistSnapshot()
    Returns a snapshot of the playlist at the time of the error.

    Note: This returns a copy of the playlist to prevent modification.

    Returns:
      A list of PlayerConfig objects representing the playlist