DownloadManager

@UnstableApi
public final class DownloadManager

Manages downloads.

Normally a download manager should be accessed via a DownloadService. When a download manager is used directly instead, downloads will be initially paused and so must be resumed by calling resumeDownloads.

A download manager instance must be accessed only from the thread that created it, unless that thread does not have a Looper. In that case, it must be accessed only from the application's main thread. Registered listeners will be called on the same thread. In all cases the `Looper` of the thread from which the manager must be accessed can be queried using getApplicationLooper.

Summary

Nested types
public interface DownloadManager.Listener

Listener for DownloadManager events.

Constants
static final int

The default maximum number of parallel downloads.
static final int

The default minimum number of times a download must be retried before failing.
static final Requirements

The default requirement is that the device has network connectivity.

Public fields
boolean
int
int
int

Public constructors
DownloadManager(
    Context context,
    WritableDownloadIndex downloadIndex,
    DownloaderFactory downloaderFactory
)

Constructs a DownloadManager.
DownloadManager(
    Context context,
    DatabaseProvider databaseProvider,
    Cache cache,
    DataSource.Factory upstreamFactory,
    Executor executor
)

Constructs a DownloadManager.

Public methods
void

Adds a download defined by the given request.
void
addDownload(DownloadRequest request, int stopReason)

Adds a download defined by the given request and with the specified stop reason.
void

Adds a Listener.
Looper

Returns the Looper associated with the application thread that's used to access the manager, and on which the manager will call its Listeners.
List<Download>

Returns current downloads.
DownloadIndex

Returns the used DownloadIndex.
boolean

Returns whether downloads are currently paused.
int

Returns the maximum number of parallel downloads.
int

Returns the minimum number of times that a download will be retried.
int

Returns the requirements needed for downloads to progress that are not currently met.
Requirements

Returns the requirements needed to be met to progress.
boolean

Returns whether the manager is currently idle.
boolean

Returns whether the manager has completed initialization.
boolean

Returns whether this manager has one or more downloads that are not progressing for the sole reason that the Requirements are not met.
void

Pauses downloads.
void

Stops the downloads and releases resources.
void

Cancels all pending downloads and removes all downloaded data.
void

Cancels the download with the id and removes all downloaded data.
void

Removes a Listener.
void

Resumes downloads.
void
setMaxParallelDownloads(@IntRange(from = 1) int maxParallelDownloads)

Sets the maximum number of parallel downloads.
void
setMinRetryCount(int minRetryCount)

Sets the minimum number of times that a download will be retried.
void

Sets the requirements that need to be met for downloads to progress.
void
setStopReason(@Nullable String id, int stopReason)

Sets the stop reason for one or all downloads.

Constants

DEFAULT_MAX_PARALLEL_DOWNLOADS

public static final int DEFAULT_MAX_PARALLEL_DOWNLOADS = 3

The default maximum number of parallel downloads.

DEFAULT_MIN_RETRY_COUNT

public static final int DEFAULT_MIN_RETRY_COUNT = 5

The default minimum number of times a download must be retried before failing.

DEFAULT_REQUIREMENTS

public static final Requirements DEFAULT_REQUIREMENTS

The default requirement is that the device has network connectivity.

Public fields

downloadsPaused

public boolean downloadsPaused

maxParallelDownloads

public int maxParallelDownloads

minRetryCount

public int minRetryCount

notMetRequirements

public int notMetRequirements

Public constructors

DownloadManager

public DownloadManager(
    Context context,
    WritableDownloadIndex downloadIndex,
    DownloaderFactory downloaderFactory
)

Constructs a DownloadManager.

Parameters
Context context

Any context.
WritableDownloadIndex downloadIndex

The download index used to hold the download information.
DownloaderFactory downloaderFactory

A factory for creating Downloaders.

DownloadManager

public DownloadManager(
    Context context,
    DatabaseProvider databaseProvider,
    Cache cache,
    DataSource.Factory upstreamFactory,
    Executor executor
)

Constructs a DownloadManager.

Parameters
Context context

Any context.
DatabaseProvider databaseProvider

Provides the SQLite database in which downloads are persisted.
Cache cache

A cache to be used to store downloaded data. The cache should be configured with an CacheEvictor that will not evict downloaded content, for example .
DataSource.Factory upstreamFactory

A Factory for creating DataSources for downloading data.
Executor executor

An Executor used to download data. Passing Runnable::run will cause each download task to download data on its own thread. Passing an Executor that uses multiple threads will speed up download tasks that can be split into smaller parts for parallel execution.

Public methods

addDownload

public void addDownload(DownloadRequest request)

Adds a download defined by the given request.

Parameters
DownloadRequest request

The download request.

addDownload

public void addDownload(DownloadRequest request, int stopReason)

Adds a download defined by the given request and with the specified stop reason.

Parameters
DownloadRequest request

The download request.
int stopReason

An initial stop reason for the download, or STOP_REASON_NONE if the download should be started.

addListener

public void addListener(DownloadManager.Listener listener)

Adds a Listener.

Parameters
DownloadManager.Listener listener

The listener to be added.

getApplicationLooper

public Looper getApplicationLooper()

Returns the Looper associated with the application thread that's used to access the manager, and on which the manager will call its Listeners.

getCurrentDownloads

public List<Download> getCurrentDownloads()

Returns current downloads. Downloads that are in terminal states (i.e. completed or failed) are not included. To query all downloads including those in terminal states, use getDownloadIndex instead.

getDownloadIndex

public DownloadIndex getDownloadIndex()

Returns the used DownloadIndex.

getDownloadsPaused

public boolean getDownloadsPaused()

Returns whether downloads are currently paused.

getMaxParallelDownloads

public int getMaxParallelDownloads()

Returns the maximum number of parallel downloads.

getMinRetryCount

public int getMinRetryCount()

Returns the minimum number of times that a download will be retried. A download will fail if the specified number of retries is exceeded without any progress being made.

getNotMetRequirements

@Requirements.RequirementFlags
public int getNotMetRequirements()

Returns the requirements needed for downloads to progress that are not currently met.

Returns
int

The not met Requirements.RequirementFlags, or 0 if all requirements are met.

getRequirements

public Requirements getRequirements()

Returns the requirements needed to be met to progress.

isIdle

public boolean isIdle()

Returns whether the manager is currently idle. The manager is idle if all downloads are in a terminal state (i.e. completed or failed), or if no progress can be made (e.g. because the download requirements are not met).

isInitialized

public boolean isInitialized()

Returns whether the manager has completed initialization.

isWaitingForRequirements

public boolean isWaitingForRequirements()

Returns whether this manager has one or more downloads that are not progressing for the sole reason that the Requirements are not met. This is true if:

pauseDownloads

public void pauseDownloads()

Pauses downloads. Downloads that would otherwise be making progress will transition to STATE_QUEUED.

release

public void release()

Stops the downloads and releases resources. Waits until the downloads are persisted to the download index. The manager must not be accessed after this method has been called.

removeAllDownloads

public void removeAllDownloads()

Cancels all pending downloads and removes all downloaded data.

removeDownload

public void removeDownload(String id)

Cancels the download with the id and removes all downloaded data.

Parameters
String id

The unique content id of the download to be started.

removeListener

public void removeListener(DownloadManager.Listener listener)

Removes a Listener.

Parameters
DownloadManager.Listener listener

The listener to be removed.

resumeDownloads

public void resumeDownloads()

Resumes downloads.

If the Requirements are met up to maxParallelDownloads will be started, excluding those with non-zero stopReasons.

setMaxParallelDownloads

public void setMaxParallelDownloads(@IntRange(from = 1) int maxParallelDownloads)

Sets the maximum number of parallel downloads.

Parameters
@IntRange(from = 1) int maxParallelDownloads

The maximum number of parallel downloads. Must be greater than 0.

setMinRetryCount

public void setMinRetryCount(int minRetryCount)

Sets the minimum number of times that a download will be retried. A download will fail if the specified number of retries is exceeded without any progress being made.

Parameters
int minRetryCount

The minimum number of times that a download will be retried.

setRequirements

public void setRequirements(Requirements requirements)

Sets the requirements that need to be met for downloads to progress.

Parameters
Requirements requirements

A Requirements.

setStopReason

public void setStopReason(@Nullable String id, int stopReason)

Sets the stop reason for one or all downloads. To clear the stop reason, pass STOP_REASON_NONE.

Parameters
@Nullable String id

The content id of the download to update, or null to set the stop reason for all downloads.
int stopReason

The stop reason, or STOP_REASON_NONE.