Package com.castlabs.sdk.downloader

## Class DownloadNotificationProvider

- java.lang.Object
- - com.castlabs.sdk.downloader.DownloadNotificationProvider

-     public abstract class DownloadNotificationProvider
      extends Object

  Class to provide the `DownloaderPlugin` with the required info related to notifications for the foreground Downloader service. Starting in Android O, background execution limits have been imposed. Standard `Service`s may not be run in background anymore. This can be overcome using a Foreground Service instead. In order for a Service to become a Foreground Service, a persistent `Notification` must be shown for as long as such Service is a Foreground Service. For the sake of consistency, the `DownloaderPlugin` will always run its service in foreground mode, regardless of the Android API version. The only abstract method in this class is `getNotification(DownloadServiceBinder, Context)`. This method must be overridden and return the Notification to show while a Download is ongoing. The most common use case for this notification is to show the download progress of the Downloads. There are also two additional methods that can be overridden for further customisation:
  - `onDownloadEvent(DownloadServiceBinder, Intent)`: This method will be called whenever the `DownloadService` fires a new event. The provided Intent will one of the actions defined in `MessageHandler`. The default implementation for this method returns `true`.
  - `shouldKeepNotification(DownloadServiceBinder)`: once there are no more ongoing downloads, and the Service is (automatically) demoted to background, this method will be invoked to decide whether to automatically clean the persistent Notification or not. The default implementation returns `true`.
  Since:
    4.1.0

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `DownloadNotificationProvider​(int notificationId)` |

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `abstract Notification` | `getNotification​(DownloadServiceBinder downloadServiceBinder, Context context)` | Build and provide a notification.
    `int` | `getNotificationId()` | Returns the notification id provided in the constructor.
    `boolean` | `onDownloadEvent​(DownloadServiceBinder downloadServiceBinder, Intent intent)` | Called whenever a new Download event is fired.
    `boolean` | `shouldKeepNotification​(DownloadServiceBinder downloadServiceBinder)` | Whether the persistent notification should be cleared or not.

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

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

- - ### Constructor Detail

    - #### DownloadNotificationProvider

          public DownloadNotificationProvider​(int notificationId)

      Parameters:
        `notificationId` - Notification id to bind to the persistent notification. Must be greater than 0.

  - ### Method Detail

    - #### getNotificationId

          public final int getNotificationId()

      Returns the notification id provided in the constructor.
      Returns:
        the notification id

    - #### getNotification

          @NonNull
          public abstract Notification getNotification​(@NonNull
                                                       DownloadServiceBinder downloadServiceBinder,
                                                       @NonNull
                                                       Context context)

      Build and provide a notification. This notification will be tied to the `DownloadService` whenever it is in foreground mode, aka. when there's at least one active Download.
      Parameters:
        `downloadServiceBinder` - binder instance to get Download-related info
        `context` - the application context.
      Returns:
        the Notification to show

    - #### onDownloadEvent

          public boolean onDownloadEvent​(@NonNull
                                         DownloadServiceBinder downloadServiceBinder,
                                         @NonNull
                                         Intent intent)

      Called whenever a new Download event is fired. The event Intent is forwarded to this method. The Intent actions will be one from the `MessageHandler`.

      You must return `true` *only* if you want the notification to be updated/posted. To avoid posting a notification for some download events, just return `false` in those cases. For example, to avoid showing a notification when a Download is deleted:

           	public boolean onDownloadEvent(@NonNull DownloadServiceBinder downloadServiceBinder, @NonNull Intent intent) {
           		String action = intent.getAction();
           		switch (action) {
           			case MessageHandler.ACTION_DOWNLOAD_DELETED:
           				return false;
           			default:
           				return super.onDownloadEvent(downloadServiceBinder, intent);
           		}
           	}

      Parameters:
        `downloadServiceBinder` - binder instance to get Download-related info
        `intent` - Intent having the Download event info
      Returns:
        true if the notification should be updated. In that case, `getNotification(DownloadServiceBinder, Context)` will be called right after. Default implementation returns `true`.

    - #### shouldKeepNotification

          public boolean shouldKeepNotification​(@NonNull
                                                DownloadServiceBinder downloadServiceBinder)

      Whether the persistent notification should be cleared or not.

      This is called whenever the `DownloadService` transitions out of foreground mode, and thus the notification is no longer enforced. If `true` is returned it's the clients responsibility to dismiss the notification, or at least build the notification calling `Notification.Builder.setOngoing(boolean)` with `false` so it can be discarded by the user.

      Parameters:
        `downloadServiceBinder` - binder instance to get Download-related info
      Returns:
        Whether the persistent notification should be cleared or not on service transition to background mode. Default implementation returns `true`.