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)`
  Constructs a new DownloadNotificationProvider with the given notification id.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `abstract Notification`
  `getNotification(DownloadServiceBinder downloadServiceBinder, Context context)`
  Build and provide a notification.
  `final 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 Details

  - ### DownloadNotificationProvider

    public DownloadNotificationProvider(int notificationId)
    Constructs a new DownloadNotificationProvider with the given notification id.
    Parameters:
      `notificationId` - Notification id to bind to the persistent notification. Must be greater than 0.

- ## Method Details

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