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` |

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static boolean` | `DEBUG` | Use this to enable debug log output * @param provider Notification provider
    `static int` | `DEFAULT_DOWNLOADER_THREADS_PRIORITY` | Default priority value for downloader threads.
    `static long` | `DEFAULT_METADATA_PERSIST_INTERVAL_MS` | Default interval in ms the download metadata is persisted into the storage.
    `static int` | `DEFAULT_NUM_PARALLEL_DOWNLOADS` | Default number of parallel chunk downloads permitted
    `static int` | `STORAGE_LOW_MODE_PAUSE` | Downloads will be put to `Download.STATE_IDLE` when a `MessageHandler.ACTION_DOWNLOAD_STORAGE_LOW` event is triggered.
    `static 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

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `String` | `getId()` |
    `long` | `getStorageLowThreshold​(long totalBytes)` | Returns the storage low threshold in bytes
    `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 Detail

    - #### 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

      Use this to enable debug log output * @param provider Notification provider

  - ### Constructor Detail

    - #### 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 Detail

    - #### 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

    - #### getId

          @NonNull
          public String getId()

      Specified by:
        `getId` in class `Plugin`