WorkManager
abstract class WorkManager
kotlin.Any | |
↳ | androidx.work.WorkManager |
WorkManager is a library used to enqueue deferrable work that is guaranteed to execute sometime after its Constraints
are met. WorkManager allows observation of work status and the ability to create complex chains of work.
WorkManager uses an underlying job dispatching service when available based on the following criteria:
- Uses JobScheduler for API 23+
- Uses a custom AlarmManager + BroadcastReceiver implementation for API 14-22
All work must be done in a ListenableWorker
class. A simple implementation, Worker
, is recommended as the starting point for most developers. With the optional dependencies, you can also use CoroutineWorker
or RxWorker
. All background work is given a maximum of ten minutes to finish its execution. After this time has expired, the worker will be signalled to stop.
There are two types of work supported by WorkManager: OneTimeWorkRequest
and PeriodicWorkRequest
. You can enqueue requests using WorkManager as follows:
<code>WorkManager workManager = WorkManager.getInstance(Context); workManager.enqueue(new OneTimeWorkRequest.Builder(FooWorker.class).build());</code>A
WorkRequest
has an associated id that can be used for lookups and observation as follows:
<code>WorkRequest request = new OneTimeWorkRequest.Builder(FooWorker.class).build(); workManager.enqueue(request); LiveData<WorkInfo> status = workManager.getWorkInfoByIdLiveData(request.getId()); status.observe(...);</code>You can also use the id for cancellation:
<code>WorkRequest request = new OneTimeWorkRequest.Builder(FooWorker.class).build(); workManager.enqueue(request); workManager.cancelWorkById(request.getId());</code>You can chain work as follows:
<code>WorkRequest request1 = new OneTimeWorkRequest.Builder(FooWorker.class).build(); WorkRequest request2 = new OneTimeWorkRequest.Builder(BarWorker.class).build(); WorkRequest request3 = new OneTimeWorkRequest.Builder(BazWorker.class).build(); workManager.beginWith(request1, request2).then(request3).enqueue();</code>Each call to
beginWith(OneTimeWorkRequest)
or beginWith(List)
returns a WorkContinuation
upon which you can call WorkContinuation#then(OneTimeWorkRequest)
or WorkContinuation#then(List)
to chain further work. This allows for creation of complex chains of work. For example, to create a chain like this:
A | +----------+ | | B C | +----+ | | D Eyou would enqueue them as follows:
<code>WorkContinuation continuation = workManager.beginWith(A); continuation.then(B).then(D, E).enqueue(); // A is implicitly enqueued here continuation.then(C).enqueue();</code>Work is eligible for execution when all of its prerequisites are complete. If any of its prerequisites fail or are cancelled, the work will never run.
WorkRequests can accept Constraints
, inputs (see Data
), and backoff criteria. WorkRequests can be tagged with human-readable Strings (see WorkRequest.Builder#addTag(String)
), and chains of work can be given a uniquely-identifiable name (see beginUniqueWork(String, ExistingWorkPolicy, OneTimeWorkRequest)
).
By default, WorkManager auto-initializes itself using a built-in ContentProvider
. ContentProviders are created and run before the Application
object, so this allows the WorkManager singleton to be setup before your code can run in most cases. This is suitable for most developers. However, you can provide a custom Configuration
by using Configuration.Provider
or WorkManager#initialize(android.content.Context, androidx.work.Configuration)
.
Renaming and Removing ListenableWorker Classes
Exercise caution in renaming classes derived from ListenableWorker
s. WorkManager stores the class name in its internal database when the WorkRequest
is enqueued so it can later create an instance of that worker when constraints are met. Unless otherwise specified in the WorkManager Configuration
, this is done in the default WorkerFactory
which tries to reflectively create the ListenableWorker object. Therefore, renaming or removing these classes is dangerous - if there is pending work with the given class, it will fail permanently if the class cannot be found. If you are using a custom WorkerFactory, make sure you properly handle cases where the class is not found so that your code does not crash.
In case it is desirable to rename a class, implement a custom WorkerFactory that instantiates the right ListenableWorker for the old class name.
Summary
Public methods | |
---|---|
WorkContinuation |
beginUniqueWork(@NonNull uniqueWorkName: String, @NonNull existingWorkPolicy: ExistingWorkPolicy, @NonNull work: OneTimeWorkRequest) This method allows you to begin unique chains of work for situations where you only want one chain with a given name to be active at a time. |
abstract WorkContinuation |
beginUniqueWork(@NonNull uniqueWorkName: String, @NonNull existingWorkPolicy: ExistingWorkPolicy, @NonNull work: MutableList<OneTimeWorkRequest!>) This method allows you to begin unique chains of work for situations where you only want one chain with a given name to be active at a time. |
WorkContinuation |
beginWith(@NonNull work: OneTimeWorkRequest) Begins a chain with one or more |
abstract WorkContinuation |
beginWith(@NonNull work: MutableList<OneTimeWorkRequest!>) Begins a chain with one or more |
abstract Operation |
Cancels all unfinished work. |
abstract Operation |
cancelAllWorkByTag(@NonNull tag: String) Cancels all unfinished work with the given tag. |
abstract Operation |
cancelUniqueWork(@NonNull uniqueWorkName: String) Cancels all unfinished work in the work chain with the given name. |
abstract Operation |
cancelWorkById(@NonNull id: UUID) Cancels work with the given id if it isn't finished. |
abstract PendingIntent |
createCancelPendingIntent(@NonNull id: UUID) Creates a |
Operation |
enqueue(@NonNull workRequest: WorkRequest) Enqueues one item for background processing. |
abstract Operation |
enqueue(@NonNull requests: MutableList<out WorkRequest!>) Enqueues one or more items for background processing. |
abstract Operation |
enqueueUniquePeriodicWork(@NonNull uniqueWorkName: String, @NonNull existingPeriodicWorkPolicy: ExistingPeriodicWorkPolicy, @NonNull periodicWork: PeriodicWorkRequest) This method allows you to enqueue a uniquely-named |
open Operation |
enqueueUniqueWork(@NonNull uniqueWorkName: String, @NonNull existingWorkPolicy: ExistingWorkPolicy, @NonNull work: OneTimeWorkRequest) This method allows you to enqueue |
abstract Operation |
enqueueUniqueWork(@NonNull uniqueWorkName: String, @NonNull existingWorkPolicy: ExistingWorkPolicy, @NonNull work: MutableList<OneTimeWorkRequest!>) This method allows you to enqueue |
open static WorkManager |
Retrieves the |
open static WorkManager |
getInstance(@NonNull context: Context) Retrieves the |
abstract ListenableFuture<Long!> |
Gets a |
abstract LiveData<Long!> |
Gets a |
abstract ListenableFuture<WorkInfo!> |
getWorkInfoById(@NonNull id: UUID) Gets a |
abstract LiveData<WorkInfo!> |
getWorkInfoByIdLiveData(@NonNull id: UUID) |
abstract ListenableFuture<MutableList<WorkInfo!>!> |
getWorkInfos(@NonNull workQuery: WorkQuery) Gets the |
abstract ListenableFuture<MutableList<WorkInfo!>!> |
getWorkInfosByTag(@NonNull tag: String) Gets a |
abstract LiveData<MutableList<WorkInfo!>!> |
getWorkInfosByTagLiveData(@NonNull tag: String) Gets a |
abstract ListenableFuture<MutableList<WorkInfo!>!> |
getWorkInfosForUniqueWork(@NonNull uniqueWorkName: String) Gets a |
abstract LiveData<MutableList<WorkInfo!>!> |
getWorkInfosForUniqueWorkLiveData(@NonNull uniqueWorkName: String) Gets a |
abstract LiveData<MutableList<WorkInfo!>!> |
getWorkInfosLiveData(@NonNull workQuery: WorkQuery) Gets the |
open static Unit |
initialize(@NonNull context: Context, @NonNull configuration: Configuration) Used to do a one-time initialization of the |
abstract Operation |
Prunes all eligible finished work from the internal database. |
Public methods
beginUniqueWork
@NonNull fun beginUniqueWork(
@NonNull uniqueWorkName: String,
@NonNull existingWorkPolicy: ExistingWorkPolicy,
@No