WorkManager

public abstract class WorkManager
extends Object

java.lang.Object
   ↳ 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:

 WorkManager workManager = WorkManager.getInstance(Context);
 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 status = workManager.getWorkInfoByIdLiveData(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();
 
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)).

Initializing WorkManager

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 initialize(android.content.Context, androidx.work.Configuration).

Renaming and Removing ListenableWorker Classes

Exercise caution in renaming classes derived from ListenableWorkers. 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

abstract WorkContinuation beginUniqueWork(String uniqueWorkName, ExistingWorkPolicy existingWorkPolicy, List<OneTimeWorkRequest> work)

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.

final WorkContinuation beginUniqueWork(String uniqueWorkName, ExistingWorkPolicy existingWorkPolicy, OneTimeWorkRequest work)

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.

final WorkContinuation beginWith(OneTimeWorkRequest work)

Begins a chain with one or more OneTimeWorkRequests, which can be enqueued together in the future using WorkContinuation.enqueue().

abstract WorkContinuation beginWith(List<OneTimeWorkRequest> work)

Begins a chain with one or more OneTimeWorkRequests, which can be enqueued together in the future using WorkContinuation.enqueue().

abstract Operation cancelAllWork()

Cancels all unfinished work.

abstract Operation cancelAllWorkByTag(String tag)

Cancels all unfinished work with the given tag.

abstract Operation cancelUniqueWork(String uniqueWorkName)

Cancels all unfinished work in the work chain with the given name.

abstract Operation cancelWorkById(UUID id)

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

abstract PendingIntent createCancelPendingIntent(UUID id)

Creates a PendingIntent which can be used to cancel a WorkRequest with the given id.

final Operation enqueue(WorkRequest workRequest)

Enqueues one item for background processing.

abstract Operation enqueue(List<? extends WorkRequest> requests)

Enqueues one or more items for background processing.

abstract Operation enqueueUniquePeriodicWork(String uniqueWorkName, ExistingPeriodicWorkPolicy existingPeriodicWorkPolicy, PeriodicWorkRequest periodicWork)

This method allows you to enqueue a uniquely-named PeriodicWorkRequest, where only one PeriodicWorkRequest of a particular name can be active at a time.

abstract Operation enqueueUniqueWork(String uniqueWorkName, ExistingWorkPolicy existingWorkPolicy, List<OneTimeWorkRequest> work)

This method allows you to enqueue work requests to a uniquely-named WorkContinuation, where only one continuation of a particular name can be active at a time.

Operation enqueueUniqueWork(String uniqueWorkName, ExistingWorkPolicy existingWorkPolicy, OneTimeWorkRequest work)

This method allows you to enqueue work requests to a uniquely-named WorkContinuation, where only one continuation of a particular name can be active at a time.

static WorkManager getInstance()

This method is deprecated. Call getInstance(Context) instead.

static WorkManager getInstance(Context context)

Retrieves the default singleton instance of WorkManager.

abstract ListenableFuture<Long> getLastCancelAllTimeMillis()

Gets a ListenableFuture of the last time all work was cancelled.

abstract LiveData<Long> getLastCancelAllTimeMillisLiveData()

Gets a LiveData of the last time all work was cancelled.

abstract ListenableFuture<WorkInfo> getWorkInfoById(UUID id)

Gets a ListenableFuture of the WorkInfo for a given work id.

abstract LiveData<WorkInfo> getWorkInfoByIdLiveData(UUID id)

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

abstract ListenableFuture<List<WorkInfo>> getWorkInfos(WorkQuery workQuery)

Gets the ListenableFuture of the List of WorkInfo for all work referenced by the WorkQuery specification.

abstract ListenableFuture<List<WorkInfo>> getWorkInfosByTag(String tag)

Gets a ListenableFuture of the WorkInfo for all work for a given tag.

abstract LiveData<List<WorkInfo>> getWorkInfosByTagLiveData(String tag)

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

abstract ListenableFuture<List<WorkInfo>> getWorkInfosForUniqueWork(String uniqueWorkName)

Gets a ListenableFuture of the WorkInfo for all work in a work chain with a given unique name.

abstract LiveData<List<WorkInfo>> getWorkInfosForUniqueWorkLiveData(String uniqueWorkName)

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

abstract LiveData<List<WorkInfo>> getWorkInfosLiveData(WorkQuery workQuery)

Gets the LiveData of the List of WorkInfo for all work referenced by the WorkQuery specification.

static void initialize(Context context, Configuration configuration)

Used to do a one-time initialization of the WorkManager singleton with a custom Configuration.

abstract Operation pruneWork()

Prunes all eligible finished work from the internal database.

Inherited methods

Public methods

beginUniqueWork

public abstract WorkContinuation beginUniqueWork (String uniqueWorkName, 
                ExistingWorkPolicy existingWorkPolicy, 
                List<OneTimeWorkRequest> work)

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 uniqueWorkName uniquely identifies this set of work.

If this method determines that new work should be enqueued and run, all records of previous work with uniqueWorkName will be pruned. If this method determines that new work should NOT be run, then the entire chain will be considered a no-op.

If any work in the chain fails or is cancelled, all of its dependent work inherits that state and will never run. This is particularly important if you are using APPEND as your ExistingWorkPolicy.

Parameters
uniqueWorkName String: A unique name which for this chain of work

existingWorkPolicy ExistingWorkPolicy: An ExistingWorkPolicy; see below for more information

work List: One or more OneTimeWorkRequest to enqueue. REPLACE ensures that if there is pending work labelled with uniqueWorkName, 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 uniqueWorkName. APPEND will create a new sequence of work if there is no existing work with uniqueWorkName; otherwise, work will be added as a child of all leaf nodes labelled with uniqueWorkName.

Returns
WorkContinuation A WorkContinuation that allows further chaining

beginUniqueWork

public final WorkContinuation beginUniqueWork (String uniqueWorkName, 
                ExistingWorkPolicy existingWorkPolicy, 
                OneTimeWorkRequest work)

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 uniqueWorkName uniquely identifies this set of work.

If this method determines that new work should be enqueued and run, all records of previous work with uniqueWorkName will be pruned. If this method determines that new work should NOT be run, then the entire chain will be considered a no-op.

If any work in the chain fails or is cancelled, all of its dependent work inherits that state and will never run. This is particularly important if you are using APPEND as your ExistingWorkPolicy.

Parameters
uniqueWorkName String: A unique name which for this chain of work

existingWorkPolicy ExistingWorkPolicy: An ExistingWorkPolicy

work OneTimeWorkRequest: The OneTimeWorkRequest to enqueue. REPLACE ensures that if there is pending work labelled with uniqueWorkName, 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 uniqueWorkName. APPEND will create a new sequence of work if there is no existing work with uniqueWorkName; otherwise, work will be added as a child of all leaf nodes labelled with uniqueWorkName.

Returns
WorkContinuation A WorkContinuation that allows further chaining

beginWith

public final WorkContinuation beginWith (OneTimeWorkRequest work)

Begins a chain with one or more OneTimeWorkRequests, which can be enqueued together in the future using WorkContinuation.enqueue().

If any work in the chain fails or is cancelled, all of its dependent work inherits that state and will never run.

Parameters
work OneTimeWorkRequest: One or more OneTimeWorkRequest to start a chain of work

Returns
WorkContinuation A WorkContinuation that allows for further chaining of dependent OneTimeWorkRequest

beginWith

public abstract WorkContinuation beginWith (List<OneTimeWorkRequest> work)

Begins a chain with one or more OneTimeWorkRequests, which can be enqueued together in the future using WorkContinuation.enqueue().

If any work in the chain fails or is cancelled, all of its dependent work inherits that state and will never run.

Parameters
work List: One or more OneTimeWorkRequest to start a chain of work

Returns
WorkContinuation A WorkContinuation that allows for further chaining of dependent OneTimeWorkRequest

cancelAllWork

public abstract Operation cancelAllWork ()

Cancels all unfinished work. Use this method with extreme caution! By invoking it, you will potentially affect other modules or libraries in your codebase. It is strongly recommended that you use one of the other cancellation methods at your disposal.

Upon cancellation, ListenableWorker.onStopped() will be invoked for any affected workers.

Returns
Operation An Operation that can be used to determine when the cancelAllWork has completed

cancelAllWorkByTag

public abstract Operation cancelAllWorkByTag (String tag)

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. Upon cancellation, ListenableWorker.onStopped() will be invoked for any affected workers.

Parameters
tag String: The tag used to identify the work

Returns
Operation An Operation that can be used to determine when the cancelAllWorkByTag has completed

cancelUniqueWork

public abstract Operation cancelUniqueWork (String uniqueWorkName)

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. Upon cancellation, ListenableWorker.onStopped() will be invoked for any affected workers.

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

Returns
Operation An Operation that can be used to determine when the cancelUniqueWork has completed

cancelWorkById

public abstract Operation cancelWorkById (UUID id)

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. Upon cancellation, ListenableWorker.onStopped() will be invoked for any affected workers.

Parameters
id UUID: The id of the work

Returns
Operation An Operation that can be used to determine when the cancelWorkById has completed

createCancelPendingIntent

public abstract PendingIntent create