Platform Android Studio Google Play Android Jetpack Docs News

WorkManager

abstract class WorkManager
kotlin.Any
   ↳ androidx.work.WorkManager

WorkManager is a library used to enqueue work that is guaranteed to execute 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+
  • For API 14-22
    • If using Firebase JobDispatcher in the app and the optional Firebase dependency, uses Firebase JobDispatcher
    • Otherwise, uses a custom AlarmManager + BroadcastReceiver implementation

All work must have a corresponding Worker to perform the computations. Work is performed in the background thread.

There are two types of work supported by WorkManager: OneTimeWorkRequest and PeriodicWorkRequest. You can enqueue requests using WorkManager as follows: 

 WorkManager workManager = WorkManager.getInstance(); workManager.enqueue(new OneTimeWorkRequest.Builder(FooWorker.class).build());
A WorkRequest has an associated id that can be used for lookups and observation as follows: 
 WorkRequest request = new OneTimeWorkRequest.Builder(FooWorker.class).build(); workManager.enqueue(request); LiveData<WorkStatus> status = workManager.getStatusById(request.getId()); status.observe(...);
You can also use the id for cancellation: 
 WorkRequest request = new OneTimeWorkRequest.Builder(FooWorker.class).build(); workManager.enqueue(request); workManager.cancelWorkById(request.getId());
You can chain work as follows: 
 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();
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 E
you would enqueue them as follows: 
 WorkContinuation continuation = workManager.beginWith(A); continuation.then(B).then(D, E).enqueue(); // A is implicitly enqueued here continuation.then(C).enqueue();
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 runs its operations on a background thread. If you are already running on a background thread and have need for synchronous (blocking) calls to WorkManager, use #synchronous() to access such methods.

Summary

Public methods
Unit
enqueue(vararg workRequest: WorkRequest!)

Enqueues one or more items for background processing.
abstract Unit
enqueue(baseWork: MutableList<out WorkRequest!>)

Enqueues one or more items for background processing.
abstract Unit

Cancels all unfinished work with the given tag.
WorkContinuation!

Begins a chain of OneTimeWorkRequest, which can be enqueued together in the future using WorkContinuation#enqueue().
abstract WorkContinuation!

Begins a chain of OneTimeWorkRequest, which can be enqueued together in the future using WorkContinuation#enqueue().
abstract LiveData!

Gets a LiveData of the WorkStatus for a given work id.
WorkContinuation!
beginUniqueWork(uniqueWorkName: String, existingWorkPolicy: ExistingWorkPolicy, vararg 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(uniqueWorkName: String, existingWorkPolicy: ExistingWorkPolicy, 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.
abstract Unit
cancelUniqueWork(uniqueWorkName: String)

Cancels all unfinished work in the work chain with the given name.
abstract LiveData!

Gets a LiveData of the WorkStatus for all work in a work chain with a given unique name.
abstract SynchronousWorkManager!

Gets an object that gives access to synchronous methods.
abstract Unit

Cancels work with the given id if it isn't finished.
abstract LiveData!

Gets a LiveData of the WorkStatus for all work for a given tag.
open static WorkManager!

Retrieves the default singleton instance of WorkManager.
open static Unit
initialize(context: Context, configuration: Configuration)

Used to do a one-time initialization of the WorkManager singleton with the default configuration.

Public methods

enqueue

fun enqueue(vararg workRequest: WorkRequest!): Unit

Enqueues one or more items for background processing.

Parameters
workRequest WorkRequest!: One or more WorkRequest to enqueue

enqueue

abstract fun enqueue(baseWork: MutableList<out WorkRequest!>): Unit

Enqueues one or more items for background processing.

Parameters
baseWork MutableList<out WorkRequest!>: One or more WorkRequest to enqueue

cancelAllWorkByTag

abstract fun cancelAllWorkByTag(tag: String): Unit

Cancels all unfinished work with the given tag. Note that cancellation is a best-effort policy and work that is already executing may continue to run.

Parameters
tag String: The tag used to identify the work

beginWith

fun beginWith(vararg work: OneTimeWorkRequest!): WorkContinuation!

Begins a chain of OneTimeWorkRequest, which can be enqueued together in the future using WorkContinuation#enqueue().

Parameters
work OneTimeWorkRequest!: One or more OneTimeWorkRequest to start a chain of work
Return
WorkContinuation!: A WorkContinuation that allows for further chaining of dependent OneTimeWorkRequest

beginWith

abstract fun beginWith(work: MutableList<OneTimeWorkRequest!>): WorkContinuation!

Begins a chain of OneTimeWorkRequest, which can be enqueued together in the future using WorkContinuation#enqueue().

Parameters
work MutableList<OneTimeWorkRequest!>: One or more OneTimeWorkRequest to start a chain of work
Return
WorkContinuation!: A WorkContinuation that allows for further chaining of dependent OneTimeWorkRequest

getStatusById

abstract fun getStatusById(id: UUID): LiveData!

Gets a LiveData of the WorkStatus for a given work id.

Parameters
id UUID: The id of the work
Return
LiveData!: A LiveData of the WorkStatus associated with id

beginUniqueWork

fun beginUniqueWork(uniqueWorkName: String, existingWorkPolicy: ExistingWorkPolicy, vararg work: OneTimeWorkRequest!): WorkContinuation!

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. For example, you may only want one sync operation to be active. If there is one pending, you can choose to let it run or replace it with your new work. The name uniquely identifies this set of work. If this method determines that new work should be enqueued and run, all records of previous work with name will be pruned. If this method determines that new work should NOT be run, then the entire chain will be considered a no-op.

Parameters
uniqueWorkName String: A unique name which for this chain of work
existingWorkPolicy String: An ExistingWorkPolicy.
work String: One or more OneTimeWorkRequest to enqueue. REPLACE ensures that if there is pending work labelled with name, it will be cancelled and the new work will run. KEEP will run the new sequence of work only if there is no pending work labelled with name. APPEND will create a new sequence of work if there is no existing work with name; otherwise, work will be added as a child of all leaf nodes labelled with name.
Return
WorkContinuation!: A WorkContinuation that allows further chaining

beginUniqueWork

abstract fun beginUniqueWork(uniqueWorkName: String, existingWorkPolicy: ExistingWorkPolicy, work: MutableList<OneTimeWorkRequest!>): WorkContinuation!

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. For example, you may only want one sync operation to be active. If there is one pending, you can choose to let it run or replace it with your new work. The name uniquely identifies this set of work. If this method determines that new work should be enqueued and run, all records of previous work with name will be pruned. If this method determines that new work should NOT be run, then the entire chain will be considered a no-op.

Parameters
uniqueWorkName String: A unique name which for this chain of work
existingWorkPolicy String: An ExistingWorkPolicy.
work String: One or more OneTimeWorkRequest to enqueue. REPLACE ensures that if there is pending work labelled with name, it will be cancelled and the new work will run. KEEP will run the new sequence of work only if there is no pending work labelled with name. APPEND will create a new sequence of work if there is no existing work with name; otherwise, work will be added as a child of all leaf nodes labelled with name.
Return
WorkContinuation!: A WorkContinuation that allows further chaining

cancelUniqueWork

abstract fun cancelUniqueWork(uniqueWorkName: String): Unit

Cancels all unfinished work in the work chain with the given name. Note that cancellation is a best-effort policy and work that is already executing may continue to run.

Parameters
uniqueWorkName String: The unique name used to identify the chain of work

getStatusesForUniqueWork

abstract fun getStatusesForUniqueWork(uniqueWorkName: String): LiveData!

Gets a LiveData of the WorkStatus for all work in a work chain with a given unique name.

Parameters
uniqueWorkName String: The unique name used to identify the chain of work
Return
LiveData!: A LiveData of the WorkStatus for work in the chain named uniqueWorkName

synchronous

abstract fun synchronous(): SynchronousWorkManager!

Gets an object that gives access to synchronous methods.

Return
SynchronousWorkManager!: A SynchronousWorkManager object, which gives access to synchronous methods

cancelWorkById

abstract fun cancelWorkById(id: UUID): Unit

Cancels work with the given id if it isn't finished. Note that cancellation is a best-effort policy and work that is already executing may continue to run.

Parameters
id UUID: The id of the work

getStatusesByTag

abstract fun getStatusesByTag(tag: String): LiveData!

Gets a LiveData of the WorkStatus for all work for a given tag.

Parameters
tag String: The tag of the work
Return
LiveData!: A LiveData list of WorkStatus for work tagged with tag

getInstance

open static fun getInstance(): WorkManager!

Retrieves the default singleton instance of WorkManager.

Return
WorkManager!: The singleton instance of WorkManager

initialize

open static fun initialize(context: Context, configuration: Configuration): Unit

Used to do a one-time initialization of the WorkManager singleton with the default configuration.

Parameters
context Context: A Context object for configuration purposes. Internally, this class will call Context#getApplicationContext(), so you may safely pass in any Context without risking a memory leak.
configuration Context: The Configuration for used to set up WorkManager.