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:

  • Field Details

  • 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

    • getId

      @NonNull public String getId()
      Specified by:
      getId in class Plugin