WorkManager

abstract class 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>

<code>WorkRequest request = new OneTimeWorkRequest.Builder(FooWorker.class).build();
  workManager.enqueue(request);
  LiveData&lt;WorkInfo&gt; status = workManager.getWorkInfoByIdLiveData(request.getId());
  status.observe(...);</code>

<code>WorkRequest request = new OneTimeWorkRequest.Builder(FooWorker.class).build();
  workManager.enqueue(request);
  workManager.cancelWorkById(request.getId());</code>

<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>

A
             |
       +----------+
       |          |
       B          C
       |
    +----+
    |    |
    D    E             

<code>WorkContinuation continuation = workManager.beginWith(A);
  continuation.then(B).then(D, E).enqueue();  // A is implicitly enqueued here
  continuation.then(C).enqueue();</code>

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 WorkManager#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

@NonNull fun beginUniqueWork(
    @NonNull uniqueWorkName: String, 
    @NonNull existingWorkPolicy: ExistingWorkPolicy, 
    @No