Class DownloadService

    • Constructor Detail

      • DownloadService

        protected DownloadService​(int foregroundNotificationId,
                                  long foregroundNotificationUpdateInterval)
        Creates a DownloadService.
        Parameters:
        foregroundNotificationId - The notification id for the foreground notification, or FOREGROUND_NOTIFICATION_ID_NONE if the service should only ever run in the background.
        foregroundNotificationUpdateInterval - The maximum interval between updates to the foreground notification, in milliseconds. Ignored if foregroundNotificationId is FOREGROUND_NOTIFICATION_ID_NONE.
      • DownloadService

        protected DownloadService​(int foregroundNotificationId,
                                  long foregroundNotificationUpdateInterval,
                                  @Nullable
                                  String channelId,
                                  @StringRes
                                  int channelNameResourceId,
                                  @StringRes
                                  int channelDescriptionResourceId)
        Creates a DownloadService.
        Parameters:
        foregroundNotificationId - The notification id for the foreground notification, or FOREGROUND_NOTIFICATION_ID_NONE if the service should only ever run in the background.
        foregroundNotificationUpdateInterval - The maximum interval between updates to the foreground notification, in milliseconds. Ignored if foregroundNotificationId is FOREGROUND_NOTIFICATION_ID_NONE.
        channelId - An id for a low priority notification channel to create, or null if the app will take care of creating a notification channel if needed. If specified, must be unique per package. The value may be truncated if it's too long. Ignored if foregroundNotificationId is FOREGROUND_NOTIFICATION_ID_NONE.
        channelNameResourceId - A string resource identifier for the user visible name of the notification channel. The recommended maximum length is 40 characters. The value may be truncated if it's too long. Ignored if channelId is null or if foregroundNotificationId is FOREGROUND_NOTIFICATION_ID_NONE.
        channelDescriptionResourceId - A string resource identifier for the user visible description of the notification channel, or 0 if no description is provided. The recommended maximum length is 300 characters. The value may be truncated if it is too long. Ignored if channelId is null or if foregroundNotificationId is FOREGROUND_NOTIFICATION_ID_NONE.
    • Method Detail

      • buildAddDownloadIntent

        public static Intent buildAddDownloadIntent​(Context context,
                                                    Class<? extends DownloadService> clazz,
                                                    DownloadRequest downloadRequest,
                                                    boolean foreground)
        Builds an Intent for adding a new download.
        Parameters:
        context - A Context.
        clazz - The concrete download service being targeted by the intent.
        downloadRequest - The request to be executed.
        foreground - Whether this intent will be used to start the service in the foreground.
        Returns:
        The created intent.
      • buildAddDownloadIntent

        public static Intent buildAddDownloadIntent​(Context context,
                                                    Class<? extends DownloadService> clazz,
                                                    DownloadRequest downloadRequest,
                                                    int stopReason,
                                                    boolean foreground)
        Builds an Intent for adding a new download.
        Parameters:
        context - A Context.
        clazz - The concrete download service being targeted by the intent.
        downloadRequest - The request to be executed.
        stopReason - An initial stop reason for the download, or Download.STOP_REASON_NONE if the download should be started.
        foreground - Whether this intent will be used to start the service in the foreground.
        Returns:
        The created intent.
      • buildRemoveDownloadIntent

        public static Intent buildRemoveDownloadIntent​(Context context,
                                                       Class<? extends DownloadService> clazz,
                                                       String id,
                                                       boolean foreground)
        Builds an Intent for removing the download with the id.
        Parameters:
        context - A Context.
        clazz - The concrete download service being targeted by the intent.
        id - The content id.
        foreground - Whether this intent will be used to start the service in the foreground.
        Returns:
        The created intent.
      • buildRemoveAllDownloadsIntent

        public static Intent buildRemoveAllDownloadsIntent​(Context context,
                                                           Class<? extends DownloadService> clazz,
                                                           boolean foreground)
        Builds an Intent for removing all downloads.
        Parameters:
        context - A Context.
        clazz - The concrete download service being targeted by the intent.
        foreground - Whether this intent will be used to start the service in the foreground.
        Returns:
        The created intent.
      • buildResumeDownloadsIntent

        public static Intent buildResumeDownloadsIntent​(Context context,
                                                        Class<? extends DownloadService> clazz,
                                                        boolean foreground)
        Builds an Intent for resuming all downloads.
        Parameters:
        context - A Context.
        clazz - The concrete download service being targeted by the intent.
        foreground - Whether this intent will be used to start the service in the foreground.
        Returns:
        The created intent.
      • buildPauseDownloadsIntent

        public static Intent buildPauseDownloadsIntent​(Context context,
                                                       Class<? extends DownloadService> clazz,
                                                       boolean foreground)
        Builds an Intent to pause all downloads.
        Parameters:
        context - A Context.
        clazz - The concrete download service being targeted by the intent.
        foreground - Whether this intent will be used to start the service in the foreground.
        Returns:
        The created intent.
      • buildSetStopReasonIntent

        public static Intent buildSetStopReasonIntent​(Context context,
                                                      Class<? extends DownloadService> clazz,
                                                      @Nullable
                                                      String id,
                                                      int stopReason,
                                                      boolean foreground)
        Builds an Intent for setting the stop reason for one or all downloads. To clear the stop reason, pass Download.STOP_REASON_NONE.
        Parameters:
        context - A Context.
        clazz - The concrete download service being targeted by the intent.
        id - The content id, or null to set the stop reason for all downloads.
        stopReason - An application defined stop reason.
        foreground - Whether this intent will be used to start the service in the foreground.
        Returns:
        The created intent.
      • buildSetRequirementsIntent

        public static Intent buildSetRequirementsIntent​(Context context,
                                                        Class<? extends DownloadService> clazz,
                                                        Requirements requirements,
                                                        boolean foreground)
        Builds an Intent for setting the requirements that need to be met for downloads to progress.
        Parameters:
        context - A Context.
        clazz - The concrete download service being targeted by the intent.
        requirements - A Requirements.
        foreground - Whether this intent will be used to start the service in the foreground.
        Returns:
        The created intent.
      • sendAddDownload

        public static void sendAddDownload​(Context context,
                                           Class<? extends DownloadService> clazz,
                                           DownloadRequest downloadRequest,
                                           boolean foreground)
        Starts the service if not started already and adds a new download.
        Parameters:
        context - A Context.
        clazz - The concrete download service to be started.
        downloadRequest - The request to be executed.
        foreground - Whether the service is started in the foreground.
      • sendAddDownload

        public static void sendAddDownload​(Context context,
                                           Class<? extends DownloadService> clazz,
                                           DownloadRequest downloadRequest,
                                           int stopReason,
                                           boolean foreground)
        Starts the service if not started already and adds a new download.
        Parameters:
        context - A Context.
        clazz - The concrete download service to be started.
        downloadRequest - The request to be executed.
        stopReason - An initial stop reason for the download, or Download.STOP_REASON_NONE if the download should be started.
        foreground - Whether the service is started in the foreground.
      • sendRemoveDownload

        public static void sendRemoveDownload​(Context context,
                                              Class<? extends DownloadService> clazz,
                                              String id,
                                              boolean foreground)
        Starts the service if not started already and removes a download.
        Parameters:
        context - A Context.
        clazz - The concrete download service to be started.
        id - The content id.
        foreground - Whether the service is started in the foreground.
      • sendRemoveAllDownloads

        public static void sendRemoveAllDownloads​(Context context,
                                                  Class<? extends DownloadService> clazz,
                                                  boolean foreground)
        Starts the service if not started already and removes all downloads.
        Parameters:
        context - A Context.
        clazz - The concrete download service to be started.
        foreground - Whether the service is started in the foreground.
      • sendResumeDownloads

        public static void sendResumeDownloads​(Context context,
                                               Class<? extends DownloadService> clazz,
                                               boolean foreground)
        Starts the service if not started already and resumes all downloads.
        Parameters:
        context - A Context.
        clazz - The concrete download service to be started.
        foreground - Whether the service is started in the foreground.
      • sendPauseDownloads

        public static void sendPauseDownloads​(Context context,
                                              Class<? extends DownloadService> clazz,
                                              boolean foreground)
        Starts the service if not started already and pauses all downloads.
        Parameters:
        context - A Context.
        clazz - The concrete download service to be started.
        foreground - Whether the service is started in the foreground.
      • sendSetStopReason

        public static void sendSetStopReason​(Context context,
                                             Class<? extends DownloadService> clazz,
                                             @Nullable
                                             String id,
                                             int stopReason,
                                             boolean foreground)
        Starts the service if not started already and sets the stop reason for one or all downloads. To clear stop reason, pass Download.STOP_REASON_NONE.
        Parameters:
        context - A Context.
        clazz - The concrete download service to be started.
        id - The content id, or null to set the stop reason for all downloads.
        stopReason - An application defined stop reason.
        foreground - Whether the service is started in the foreground.
      • sendSetRequirements

        public static void sendSetRequirements​(Context context,
                                               Class<? extends DownloadService> clazz,
                                               Requirements requirements,
                                               boolean foreground)
        Starts the service if not started already and sets the requirements that need to be met for downloads to progress.
        Parameters:
        context - A Context.
        clazz - The concrete download service to be started.
        requirements - A Requirements.
        foreground - Whether the service is started in the foreground.
      • startForeground

        public static void startForeground​(Context context,
                                           Class<? extends DownloadService> clazz)
        Starts the service in the foreground without adding a new download request. If there are any not finished downloads and the requirements are met, the service resumes downloading. Otherwise it stops immediately.
        Parameters:
        context - A Context.
        clazz - The concrete download service to be started.
        See Also:
        start(Context, Class)
      • onStartCommand

        public int onStartCommand​(@Nullable
                                  Intent intent,
                                  int flags,
                                  int startId)
        Overrides:
        onStartCommand in class Service
      • getDownloadManager

        protected abstract DownloadManager getDownloadManager()
        Returns a DownloadManager to be used to downloaded content. Called only once in the life cycle of the process.
      • getScheduler

        @Nullable
        protected abstract Scheduler getScheduler()
        Returns a Scheduler to restart the service when requirements allowing downloads to take place are met. If null, the service will only be restarted if the process is still in memory when the requirements are met.

        This method is not called for services whose foregroundNotificationId is set to FOREGROUND_NOTIFICATION_ID_NONE. Such services will only be restarted if the process is still in memory and considered non-idle, meaning that it's either in the foreground or was backgrounded within the last few minutes.

      • getForegroundNotification

        protected abstract Notification getForegroundNotification​(List<Download> downloads)
        Returns a notification to be displayed when this service running in the foreground.

        Download services that do not wish to run in the foreground should be created by setting the foregroundNotificationId constructor argument to FOREGROUND_NOTIFICATION_ID_NONE. This method is not called for such services, meaning it can be implemented to throw UnsupportedOperationException.

        Parameters:
        downloads - The current downloads.
        Returns:
        The foreground notification to display.
      • invalidateForegroundNotification

        protected final void invalidateForegroundNotification()
        Invalidates the current foreground notification and causes getForegroundNotification(List) to be invoked again if the service isn't stopped.