Package com.castlabs.sdk.downloader

# Class DownloaderPlugin

java.lang.Object
com.castlabs.android.Plugin
com.castlabs.sdk.downloader.DownloaderPlugin

public class DownloaderPlugin extends Plugin
This plugin integrates the offline downloader plugin with the castLabs Player SDK. You have to register the plugin before you initialize the SDK:

      public class MyApp extends Application {
         @Override
          public void onCreate() {
              super.onCreate();

              PlayerSDK.register(new DownloaderPlugin(notificationProvider));
              PlayerSDK.init(getApplicationContext());
          }
     }

Since version 4.1.5, the disk space threshold that determines when a `MessageHandler.ACTION_DOWNLOAD_STORAGE_LOW` is raised and downloads are paused is configurable. You can use `setStorageLowThreshold(int, long)` to set custom thresholds. By default the minimum of 5% of total storage space and 500 MB is used. These are the values that are also used by default for Android System notifications for low storage space although the values can vary for different vendors.

The values van be configured before you register the plugin, for example:

      public class MyApp extends Application {
         @Override
          public void onCreate() {
              super.onCreate();

              DownloaderPlugin downloaderPlugin = new DownloaderPlugin(notificationProvider);
              downloaderPlugin.setStorageLowThreshold(5, 500 * 1024 * 1024)
              PlayerSDK.register(downloaderPlugin);
              PlayerSDK.init(getApplicationContext());
          }
     }

You can also set the values at runtime after the plugin was registered by getting the registered plugin instance back from the SDK:

       DownloaderPlugin downloaderPlugin = PlayerSDK.getPlugin(DownloaderPlugin.class);
       downloaderPlugin.setStorageLowThreshold(5, 500 * 1024 * 1024)

Version 4.1.5 also introduced an new storage mode which can be set through a constructor parameter. `STORAGE_LOW_MODE_PAUSE` is the default and is the same behaviour as before. In that mode, the service will put all ongoing (loading or queued) downloads into idle state when not enough disk space is available while downloading. You have to actively resume the now paused downloads.

The new mode `STORAGE_LOW_MODE_QUEUED` can be used to stop downloads but keeps them in the queued state when a storage low event occurs. The benefit of this mode is that downloads will be resumed automatically when a more storage is available. The downside is that the service will keep running in foreground mode. The storage_ok event is triggered when a download is deleted and enough storage is available or when the system triggers a storage ok event. Please note that the latter might take some time to be triggered by the system and this is also the reason why the service keeps running since we need the service to listen for such events. You can also use `DownloadServiceBinder.resumeQueuedDownloads()` to actively resume downloads.

Since:
  3.3.0
See Also:
  - `DownloadNotificationProvider`

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static @interface`
  `DownloaderPlugin.StorageLowMode`
  Annotation for the storage low mode

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static boolean`
  `DEBUG`
  Flag to enable debug log output
  `static final int`
  `DEFAULT_DOWNLOADER_THREADS_PRIORITY`
  Default priority value for downloader threads.
  `static final long`
  `DEFAULT_METADATA_PERSIST_INTERVAL_MS`
  Default interval in ms the download metadata is persisted into the storage.
  `static final int`
  `DEFAULT_NUM_PARALLEL_DOWNLOADS`
  Default number of parallel chunk downloads permitted
  `static final int`
  `STORAGE_LOW_MODE_PAUSE`
  Downloads will be put to `Download.STATE_IDLE` when a `MessageHandler.ACTION_DOWNLOAD_STORAGE_LOW` event is triggered.
  `static final int`
  `STORAGE_LOW_MODE_QUEUED`
  Downloads will be put to `Download.STATE_QUEUED` when a `MessageHandler.ACTION_DOWNLOAD_STORAGE_LOW` event is triggered.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DownloaderPlugin(DownloadNotificationProvider provider)`
  Creates a new instance with support for 10 parallel segment downloads.
  `DownloaderPlugin(DownloadNotificationProvider provider, int numParallelDownloads)`
  Creates a new instance.
  `DownloaderPlugin(DownloadNotificationProvider provider, int numParallelDownloads, int storageLowMode)`
  Creates a new instance.
  `DownloaderPlugin(DownloadNotificationProvider provider, int numParallelDownloads, int storageLowMode, int downloaderThreadsPriority, long metadataPersistIntervalMs)`
  Creates a new instance.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static void`
  `addRequestModifier(RequestModifier modifier)`
  Adds a request modifier that will be used to modify network requests made by the Downloader.
  `static void`
  `addRequestModifier(RequestModifier modifier, RequestModifierFilter filter)`
  Adds a request modifier that will be used to modify network requests made by the Downloader.
  `static void`
  `addResponseModifier(ResponseModifier modifier)`
  Adds a response modifier that will be used to modify network responses received by the Downloader.
  `static void`
  `addResponseModifier(ResponseModifier modifier, ResponseModifierFilter filter)`
  Adds a response modifier that will be used to modify network responses received by the Downloader.
  `static void`
  `clearRequestModifiers()`
  Clears all request modifiers.
  `static void`
  `clearResponseModifiers()`
  Clears all response modifiers.
  `String`
  `getId()`
  Returns the unique identifier for this plugin.
  `static List<RequestModifier>`
  `getRequestModifiers()`
  Gets all currently configured request modifiers.
  `static List<ResponseModifier>`
  `getResponseModifiers()`
  Gets all currently configured response modifiers.
  `long`
  `getStorageLowThreshold(long totalBytes)`
  Returns the storage low threshold in bytes
  `static void`
  `removeRequestModifier(RequestModifier modifier)`
  Removes a previously added request modifier.
  `static void`
  `removeResponseModifier(ResponseModifier modifier)`
  Removes a previously added response modifier.
  `void`
  `setStorageLowThreshold(int percentage, long bytes)`
  Sets the threshold values that define when downloads are aborted due to not enough disk space.

  ### Methods inherited from class com.castlabs.android.Plugin

  `init, onRemotePlay`

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

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

- ## Field Details

  - ### STORAGE_LOW_MODE_PAUSE

    public static final int STORAGE_LOW_MODE_PAUSE
    Downloads will be put to `Download.STATE_IDLE` when a `MessageHandler.ACTION_DOWNLOAD_STORAGE_LOW` event is triggered. In this mode, the service will stop once all downloads are in `Download.STATE_IDLE` state and you have to actively resume downloads.
    See Also:
      - Constant Field Values

  - ### STORAGE_LOW_MODE_QUEUED

    public static final int STORAGE_LOW_MODE_QUEUED
    Downloads will be put to `Download.STATE_QUEUED` when a `MessageHandler.ACTION_DOWNLOAD_STORAGE_LOW` event is triggered. In this mode, the service will keep running and wait for a `MessageHandler.ACTION_DOWNLOAD_STORAGE_OK` event and automatically resume downloads. You can also use `DownloadServiceBinder.resumeQueuedDownloads()` to actively resume downloads.
    See Also:
      - Constant Field Values

  - ### DEFAULT_NUM_PARALLEL_DOWNLOADS

    public static final int DEFAULT_NUM_PARALLEL_DOWNLOADS
    Default number of parallel chunk downloads permitted
    See Also:
      - Constant Field Values

  - ### DEFAULT_DOWNLOADER_THREADS_PRIORITY

    public static final int DEFAULT_DOWNLOADER_THREADS_PRIORITY
    Default priority value for downloader threads. Value is `Thread.NORM_PRIORITY`.
    See Also:
      - Constant Field Values

  - ### DEFAULT_METADATA_PERSIST_INTERVAL_MS

    public static final long DEFAULT_METADATA_PERSIST_INTERVAL_MS
    Default interval in ms the download metadata is persisted into the storage. Value is `10 * 1000` The value can be customized in `DownloaderPlugin(DownloadNotificationProvider, int, int, int, long)`
    See Also:
      - Constant Field Values

  - ### DEBUG

    public static boolean DEBUG
    Flag to enable debug log output

- ## Constructor Details

  - ### DownloaderPlugin

    public DownloaderPlugin(DownloadNotificationProvider provider)
    Creates a new instance with support for 10 parallel segment downloads.
    Parameters:
      `provider` - an Implementation of `DownloadNotificationProvider`

  - ### DownloaderPlugin

    public DownloaderPlugin(DownloadNotificationProvider provider, int numParallelDownloads)
    Creates a new instance.

    Use this to configure the number of parallel segment downloads. Please note that this controls the number of parallel downloaded segments and tracks, but will not cause `Download` instances to be handled in parallel.

    The assets are downloaded in sequence: after the first one is completely downloaded or paused or canceled, the next download is started.

    The download service will use storage mode `STORAGE_LOW_MODE_PAUSE`.

    Parameters:
      `provider` - an Implementation of `DownloadNotificationProvider`
      `numParallelDownloads` - Number of permitted parallel segment downloads. These segments are from one specific asset. It does not represent the number of parallel assets (movies) downloads, which is always one.

  - ### DownloaderPlugin

    public DownloaderPlugin(DownloadNotificationProvider provider, int numParallelDownloads, int storageLowMode, int downloaderThreadsPriority, long metadataPersistIntervalMs)
    Creates a new instance.

    Use this to configure the number of parallel segment downloads. Please note that this controls the number of parallel downloaded segments and tracks, but will not cause `Download` instances to be handled in parallel.

    The assets are downloaded in sequence: after the first one is completely downloaded or paused or canceled, the next download is started.

    Parameters:
      `provider` - an Implementation of `DownloadNotificationProvider`
      `numParallelDownloads` - Number of permitted parallel segment downloads. These segments are from one specific asset. It does not represent the number of parallel assets (movies) downloads, which is always one.
      `storageLowMode` - The storage low mode that will be used
      `downloaderThreadsPriority` - The priority that will be assigned to the downloader threads. Should be a positive value between `Thread.MIN_PRIORITY` and `Thread.MAX_PRIORITY`. The default value is `DEFAULT_DOWNLOADER_THREADS_PRIORITY`.
      `metadataPersistIntervalMs` - The interval in milliseconds when the metadata is persisted into the storage, default is `DEFAULT_METADATA_PERSIST_INTERVAL_MS`

  - ### DownloaderPlugin

    public DownloaderPlugin(DownloadNotificationProvider provider, int numParallelDownloads, int storageLowMode)
    Creates a new instance.

    Use this to configure the number of parallel segment downloads. Please note that this controls the number of parallel downloaded segments and tracks, but will not cause `Download` instances to be handled in parallel.

    The assets are downloaded in sequence: after the first one is completely downloaded or paused or canceled, the next download is started.

    Parameters:
      `provider` - an Implementation of `DownloadNotificationProvider`
      `numParallelDownloads` - Number of permitted parallel segment downloads. These segments are from one specific asset. It does not represent the number of parallel assets (movies) downloads, which is always one.
      `storageLowMode` - The storage low mode that will be used

- ## Method Details

  - ### setStorageLowThreshold

    public void setStorageLowThreshold(int percentage, long bytes)
    Sets the threshold values that define when downloads are aborted due to not enough disk space. The values here specify the threshold in percent (between 0 and 100) as well as in bytes. The actual threshold is the minimum of the two values.
    Parameters:
      `percentage` - The lower bound as percentage of total space between 0 and 100
      `bytes` - The lower bound in bytes (must be > 100
    Throws:
      `IllegalArgumentException` - if the values are not valid

  - ### getStorageLowThreshold

    public long getStorageLowThreshold(long totalBytes)
    Returns the storage low threshold in bytes
    Parameters:
      `totalBytes` - The total bytes available for the file system the threshold is applied to
    Returns:
      The Storage Low threshold

  - ### addRequestModifier

    public static void addRequestModifier(@NonNull RequestModifier modifier)
    Adds a request modifier that will be used to modify network requests made by the Downloader.
    Parameters:
      `modifier` - The request modifier to add

  - ### addRequestModifier

    public static void addRequestModifier(@NonNull RequestModifier modifier, @Nullable RequestModifierFilter filter)
    Adds a request modifier that will be used to modify network requests made by the Downloader.
    Parameters:
      `modifier` - The request modifier to add
      `filter` - Optional filter restricting when this modifier executes

  - ### removeRequestModifier

    public static void removeRequestModifier(@NonNull RequestModifier modifier)
    Removes a previously added request modifier.
    Parameters:
      `modifier` - The request modifier to remove

  - ### getRequestModifiers

    @NonNull public static List<RequestModifier> getRequestModifiers()
    Gets all currently configured request modifiers.
    Returns:
      The list of request modifiers

  - ### clearRequestModifiers

    public static void clearRequestModifiers()
    Clears all request modifiers.

  - ### addResponseModifier

    public static void addResponseModifier(@NonNull ResponseModifier modifier)
    Adds a response modifier that will be used to modify network responses received by the Downloader.
    Parameters:
      `modifier` - The response modifier to add

  - ### addResponseModifier

    public static void addResponseModifier(@NonNull ResponseModifier modifier, @Nullable ResponseModifierFilter filter)
    Adds a response modifier that will be used to modify network responses received by the Downloader.
    Parameters:
      `modifier` - The response modifier to add
      `filter` - Optional filter restricting when this modifier executes

  - ### removeResponseModifier

    public static void removeResponseModifier(@NonNull ResponseModifier modifier)
    Removes a previously added response modifier.
    Parameters:
      `modifier` - The response modifier to remove

  - ### getResponseModifiers

    @NonNull public static List<ResponseModifier> getResponseModifiers()
    Gets all currently configured response modifiers.
    Returns:
      The list of response modifiers

  - ### clearResponseModifiers

    public static void clearResponseModifiers()
    Clears all response modifiers.

  - ### getId

    @NonNull public String getId()
    Returns the unique identifier for this plugin.
    Specified by:
      `getId` in class `Plugin`
    Returns:
      The plugin identifier