WorkManager the recommended library for persistent work.
Scheduled work is 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
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.
WorkManager workManager = WorkManager.getInstance(Context); workManager.enqueue(new OneTimeWorkRequest.Builder(FooWorker.class).build());A
WorkRequesthas an associated id that can be used for lookups and observation as follows:
WorkRequest request = new OneTimeWorkRequest.Builder(FooWorker.class).build(); workManager.enqueue(request); LiveDataYou can also use the id for cancellation:
status = workManager.getWorkInfoByIdLiveData(request.getId()); status.observe(...);
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
WorkContinuationupon which you can call
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:
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
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
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
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
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.
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.