The WorkManager API makes it easy to specify deferrable, asynchronous tasks and when they should run. These APIs let you create a task and hand it off to WorkManager to run immediately or at an appropriate time. See the reference docs for more information.
Declaring dependencies
To add a dependency on WorkManager, you must add the Google Maven repository to your project. Read Google's Maven repository for more information.
Add the dependencies for the artifacts you need in the build.gradle
file for
your app or module:
dependencies {
def work_version = "1.0.0-rc01"
implementation "android.arch.work:work-runtime:$work_version" // For Kotlin+Coroutines use work-runtime-ktx
// optional - RxJava2 support
implementation "android.arch.work:work-rxjava2:$work_version"
// optional - Test helpers
androidTestImplementation "android.arch.work:work-testing:$work_version"
}
For information on using Kotlin extensions, see ktx documentation.
For more information about dependencies, see Add Build Dependencies.
Version 1.0.0-rc01
February 14, 2019
This is a release candidate for WorkManager's 1.0.0 stable release. This release contains one bug fix.
Bug Fixes
- The AlarmManager based implementation now correctly respects
flex
windows for PeriodicWorkRequsts. b/124274584
Version 1.0.0-beta05
February 6, 2019
This release contains some bug fixes.
Bug Fixes
- Fixed a case where
JobScheduler.getPendingJob(...)
was used on API 23. b/123893059 - Fixed a
NullPointerException
on devices running Android 5.1 (API level 22) or lower. b/123835104
Version 1.0.0-beta04
February 4, 2019
This release contains some bug fixes.
Bug Fixes
- Improved scheduling of PeriodicWork for the AlarmManager based implementation.
- Fixed a case where WorkManager failed to correctly track constraints when using the AlarmManager based implementation. b/123379508
- Fixed a case when WorkManager failed to retry work on process death when using the AlarmManager based implementation. b/123329850
- Fixed a case which would cause WorkManager to leak Wakelocks when using the AlarmManager based implementation.
Version 1.0.0-beta03
January 25, 2019
This release contains some bug fixes.
Bug Fixes
- We introduced a regression
1.0.0-beta02
that was causing work to not execute properly in some situations. b/123211993 - Fixed a case where work wasn't properly honoring backoff timing. b/122881597
- Fixed a
ConcurrentModificationException
on devices running Android 5.1 (API or) or lower. This is a continuation of the fix in1.0.0-beta02
. b/121345393 - Added
exported=false
for some components in our manifest that were missing this annotation. - Included information about how WorkManager interacts with the OS in the package-level documentation.
Version 1.0.0-beta02
January 15, 2019
This release contains some bug fixes.
Bug Fixes
- Fixed an edge case where periodic work could run more than once per interval on devices running Android 6.0 (API level 23). b/121998363
- Fixed a
ConcurrentModificationException
on devices running Android 5.1 (API level 22) or lower. b/121345393 - Fixed erroneous execution of work when Constraints aren't met on devices running Android 5.1 (API level 22) or lower. b/122578012
- Optimized work completion handling to be faster in some edge cases. b/122358129
- Added a change to address potential race conditions among multiple instances
of
LiveData
that WorkManager uses. - Moved to use
Room
dependency1.1.1
instead of1.1.1-rc01
; these versions are identical. b/122578011
Version 1.0.0-beta01
December 19, 2018
This release contains no API changes; moving forward, WorkManager is expected to stay API stable until the next version unless there is a critical problem. This release contains some bug fixes.
Bug Fixes
- Previously-cancelled children of successfully completed parent work will no longer run. b/120811767
- Properly initialized logging classes (primarily surfaced during tests).
Version 1.0.0-alpha13
December 12, 2018
This release contains a minor API change that will be helpful for some Kotlin users.
API Changes
androidx.work.Result
has been moved to be an inner class ofListenableWorker
. This prevents refactoring conflicts with Kotlin's top-levelResult
class. This is a breaking API change. b/120564418
Breaking API Changes
androidx.work.Result
has been moved to be an inner class ofListenableWorker
.
Version 1.0.0-alpha12
December 5, 2018
This release contains some breaking API changes; please see the Breaking API Changes section below. This version is likely to be released as our first beta. alpha12
also contains extensive documentation updates.
API Changes
- A new artifact,
work-rxjava2
, introducesRxWorker
. This is aListenableWorker
that expects aSingle<Payload>
. - Support for Firebase JobDispatcher has been removed because of its impending deprecation. This means that the
work-firebase
artifact will no longer be updated as we head into beta. We will be looking into adding an alternative in the future. - Combined
Payload
intoResult
.Result
is now a "sealed class" with three concrete implementations, which you can obtain viaResult.success()
(orResult.success(Data)
),Result.failure()
(orResult.failure(Data)
), andResult.retry()
. YourListenableFuture
s now resultResult
instead ofPayload
.Worker
s don't have getter and setter methods for outputData
. This is a breaking change. - Added
Constraints.Builder.setTriggerContentMaxDelay(long, TimeUnit)
andConstraints.Builder.setTriggerContentUpdateDelay(long, TimeUnit)
and variants to better support slow triggering content URIs. b/119919774 - Added
WorkRequest.Builder.setBackoffCriteria(BackoffPolicy, Duration)
variant. This method requires API 26. - Added
Operation.await()
andListenableFuture.await()
Kotlin extension methods. - Renamed
Operation.getException()
toOperation.getThrowable()
. This is a breaking change. - The
ContentUriTriggers
class and methods referencing it are no longer available for public usage. This is a breaking change. - Removed the rest of the varargs methods in
WorkManager
,WorkContinuation
, andOneTimeWorkRequest
to streamline the API. To fix any build problems, you can wrap your existing varargs withArrays.asList(...)
. We still include single-argument versions of each method. This is a breaking change. - Removed
WorkContinuation.combine(OneTimeWorkRequest, *)
variants. They were presenting a confusing API; the existingcombine
methods are more understandable. This is a breaking change.
Bug Fixes
- Pre-Marshmallow implementations are now more reliable in recovering from process death of an already-executing task.
LiveData
that is observed viaobserveForever
is tracked via WorkManager. This is a backport of a Room library fix. b/74477406Data.Builder.build()
now throws an exception if the serialized object exceeds its maximum size. This previously would only happen on a background thread where you couldn't properly handle it.- Further distinguished stopped vs. cancelled work;
getWorkInfoById()
will return aWorkInfo
with theCANCELLED
State
duringListenableWorker.onStopped()
. - Treat
null
Result
s as failures inListenableWorker
. b/120362353 - Speculative fix for Shield Tablets running API 24 that sometimes threw an
IllegalArgumentException
. b/119484416
Breaking API Changes
- Support for Firebase JobDispatcher has been removed because of its impending deprecation. This means that the
work-firebase
artifact will no longer be updated as we head into beta. We will be looking into adding an alternative in the future. - Combined
Payload
intoResult
.Result
is now a "sealed class" with three concrete implementations, which you can obtain viaResult.success()
(orResult.success(Data)
),Result.failure()
(orResult.failure(Data)
), andResult.retry()
. YourListenableFuture
s now resultResult
instead ofPayload
.Worker
s don't have getter and setter methods for outputData
. - Added
Operation.await()
andListenableFuture.await()
Kotlin extension methods. - Renamed
Operation.getException()
toOperation.getThrowable()
. - The
ContentUriTriggers
class and methods referencing it are no longer available for public usage. - Removed the rest of the varargs methods in
WorkManager
,WorkContinuation
, andOneTimeWorkRequest
to streamline the API. To fix any build problems, you can wrap your existing varargs withArrays.asList(...)
. We still include single-argument versions of each method. - Removed
WorkContinuation.combine(OneTimeWorkRequest, *)
variants. They were presenting a confusing API; the existingcombine
methods are more understandable.
Version 1.0.0-alpha11
November 8, 2018
This release contains many changes that will become stable API at beta
.
There are breaking API changes in this release; please see the Breaking API Changes section below.
API Changes
work-runtime-ktx
introduces a newCoroutineWorker
.WorkStatus
has been renamed toWorkInfo
. All correspondinggetStatus
method variants have been renamed to the correspondinggetWorkInfo
variants. This is a breaking change.ListenableWorker.onStopped()
no longer accepts has a boolean argument representing if theWorkRequest
was cancelled.WorkManager
no longer makes this distinction. This is a breaking change.androidx.work.test
package has been renamed toandroidx.work.testing
package. This is a breaking change.- Setters on
Constraints
are no longer a part of the public API. This is a breaking change. WorkerParameters.getTriggeredContentUris()
andWorkerParameters.getTriggeredContentAuthorities()
previously returned arrays. Now these methods return Collections. This is a breaking change.ListenableWorker.onStartWork()
is renamed toListenableWorker.startWork()
. This is a breaking change.- The constructor for
WorkStatus
is no longer a part of the public API. This is a breaking change. Configuration.getMaxJobSchedulerID()
andConfiguration.getMinJobSchedulerID()
are renamed toConfiguration.getMinJobSchedulerId()
andConfiguration.getMaxJobSchedulerId()
respectively. This is a breaking change.- Added a lot of
@NonNull
annotations to the public API to improve ergonomics of the API. - Add
WorkManager.enqueueUniqueWork()
API to enqueue uniqueOneTimeWorkRequest
s without having to create aWorkContinuation
. - All variants of
enqueue
andcancel
methods onWorkManager
now return a newOperation
type. This is a breaking change. - All variants of
enqueue
no longer accept varargs forWorkRequest
s. This is a breaking change. Use Collections instead. You can useArrays.asList()
to modify existing code. We did this to reduce the API surface and method count. - Attempting to
initialize
WorkManager
more than once per process will now result in anIllegalStateException
. This is a breaking change.
Bug Fixes
WorkRequest.Builder
s in thework-runtime-ktx
artifact now useListenableWorker
s. Fixes b/117666259- Ensure the next run time for
PeriodicWork
is in the future. Fixes b/118204399 - Remove potential disk I/O when using WorkManager on app startup. Fixes b/117796731
- Fix a race condition in
WorkConstraintsTracker
. Fixes android-workmanager/issues/56
Breaking API Changes
WorkStatus
has been renamed toWorkInfo
. All correspondinggetStatus
method variants have been renamed to the correspondinggetWorkInfo
variants.ListenableWorker.onStopped()
no longer accepts has a boolean argument representing if theWorkRequest
was cancelled.WorkManager
no longer makes this distinction.androidx.work.test
package has been renamed toandroidx.work.testing
package.- Setters on
Constraints
are no longer a part of the public API. WorkerParameters.getTriggeredContentUris()
andWorkerParameters.getTriggeredContentAuthorities()
previously returned arrays. Now these methods return Collections.ListenableWorker.onStartWork()
is renamed toListenableWorker.startWork()
.- The constructor for
WorkStatus
is no longer a part of the public API. Configuration.getMaxJobSchedulerID()
andConfiguration.getMinJobSchedulerID()
are renamed toConfiguration.getMinJobSchedulerId()
andConfiguration.getMaxJobSchedulerId()
respectively.- All variants of
enqueue
andcancel
methods onWorkManager
now return a newOperation
type. - All variants of
enqueue
no longer accept varargs forWorkRequest
s. - Attempting to
initialize
WorkManager
more than once per process will now result in anIllegalStateException
.
Version 1.0.0-alpha10
October 11, 2018
This release supports developer-controlled asynchronous work. There are breaking API changes in this release; please see the Breaking API Changes section below.
We anticipate that WorkManager is entering the final phases of its alpha period. We expect to be API stable in beta, so please take some time to file your feedback on our issue tracker.
API Changes
- Removed all previously
deprecated
methods and classes, notably the defaultWorker
constructor. This is a breaking API change. - Renamed
NonBlockingWorker
toListenableWorker
, which is now an unhidden public class and ready for usage.ListenableWorker
provides access to one abstract method,ListenableFuture<Payload> onStartWork()
which is called on the main thread. It is up to you to start and process work asynchronously. When finished, you should update theListenableFuture
appropriately. Reference implementations ofListenableFuture
s are provided in theFutures
package inalpha02
(see below theWorkManager
section).Worker
extendsListenableWorker
and still operates as before, with an abstractResult doWork()
method.- Shuffled some methods and members from
Worker
toListenableWorker
. - We shall soon provide reference implementations for
ListenableWorker
s that use Kotlin coroutines (once the stable versions are released) and RxJava2.
- The interface
WorkerFactory
and the concrete implementationDefaultWorkerFactory
have been merged into an abstract class calledWorkerFactory
. The implementation ensures that the default reflection-based behavior is called as a last-ditch effort for any user-createdWorkerFactory
instances. This is a breaking change. - Removed
WorkManager.synchronous()
andWorkContinuation.synchronous()
and all related methods. AddedListenableFuture<Void>
as the return type of many methods in the API. This is a breaking API change.- You can now synchronously get and observe by using
ListenableFuture
s. For example,WorkManager.enqueue()
used to returnvoid
; it now returns aListenableFuture<Void>
. You can callListenableFuture.addListener(Runnable, Executor)
orListenableFuture.get()
to run code once the operation is complete. - Note that these
ListenableFuture
s do not tell you if the operation succeeded or failed; only that they finished. You will still need to chain WorkManager methods to find out this information. - We ignore
cancel()
calls on these objects, as they are confusing and hard to reason about (are you cancelling the operation or the resulting work?). This is within theFuture
s contract. - To maintain parity with the synchronous
getStatus*
methods, we have providedListenableFuture
variants, and renamed the existing ones that returnedLiveData
to explicitly have "LiveData" as part of the name (for example,getStatusesByIdLiveData(UUID)
). This is a breaking API change.
- You can now synchronously get and observe by using
Bug Fixes
- Fixed the known issue from alpha09 regarding duplicate
androidx-annotations.pro
files. You may remove the workaround from the previous release notes by deletingexclude 'META-INF/proguard/androidx-annotations.pro'
from your gradle file. - Added proguard configurations to keep new
Worker
constructor. b/116296569 - Fix potential
NullPointerException
in a race condition where work wasREPLACE
d. b/116253486 and b/116677275 WorkContinuation.combine()
now accepts one or moreWorkContinuation
s instead of two or more. b/117266752
Breaking API Changes
- Removed all previously
deprecated
methods and classes, notably the defaultWorker
constructor. - The interface
WorkerFactory
and the concrete implementationDefaultWorkerFactory
have been merged into an abstract class calledWorkerFactory
. - Removed
WorkManager.synchronous()
andWorkContinuation.synchronous()
. WorkManager.getStatus*()
methods now returnListenableFuture
s.WorkManager.getStatus*LiveData()
returnLiveData
s.
Version 1.0.0-alpha09
September 19, 2018
Known Issue
If you run into the following issue: "More than one file was found with OS independent path 'META-INF/proguard/androidx-annotations.pro'", please put the following in your gradle file as a temporary workaround while we fix the issue in alpha10:
android {
packagingOptions {
exclude 'META-INF/proguard/androidx-annotations.pro'
}
}
Bug Fixes
- Added another fix that was needed for the "100 jobs" error. b/115560696
- Added some fixes for foreign key constraint errors due to race conditions. b/114705286
- Delegated
ConstraintTrackingWorker.onStopped(boolean)
calls to the underlyingWorker
. b/114125093 - Enforce correct minimum backoff delay for Firebase JobDispatcher. b/113304626
- Improved threading guarantees internal to the library.
- Correct potential issue with deduping of
LiveData
internally.
API Changes
- You can now create your own
Worker
instances at runtime by specifying aWorkerFactory
as part of theWorkManager.Configuration
. The fallback factory isDefaultWorkerFactory
, which matches behavior of previous versions of WorkManager.- The default constructors for
Worker
andNonBlockingWorker
are now marked as deprecated. Please use the new constructor (Worker(Context, WorkerParameters)
) and callsuper(Context, WorkerParameters)
; future versions of WorkManager will remove the default constructor.
- The default constructors for
- We have started using the new
ListenableFuture
artifact internally (free of Guava dependencies). We will introduce ListenableFutures to the API in upcoming releases. This change will support the eventual unhiding ofNonBlockingWorker
. - Add ability to trigger timed work in
TestDriver
viaTestDriver.setInitialDelayMet(UUID)
andTestDriver.setPeriodDelayMet(UUID)
. b/113360060
Breaking Changes
- The default
Worker
andNonBlockingWorker
constructors are deprecated. Please migrate to the new constructor ASAP. Future versions will remove the default constructor.
Version 1.0.0-alpha08
August 27, 2018
Bug Fixes
- Explicitly labelled WorkManager components as direct boot unaware so they don't fire up during direct boot. In the future, we will provide a version of WorkManager that is direct boot-aware. b/112665532
- Fixed an issue where retried work was not running. b/112604021
- Fixed periodic work not executing repeatedly (related to the above issue). b/112859683
- Honored backoff policies when the app process is already running.
- Corrected exception messages in
Data
to indicate the limit is 10KB. - Lowered maximum value of
Configuration.setMaxSchedulerLimit(int)
to 50 to account for some latency inJobScheduler
processing completion. b/112817355
Version 1.0.0-alpha07
August 16, 2018
Bug Fixes
- Fixed a potential SQL query with negative limits that could return an unbounded number of results.
- Work that has finished execution now correctly cancels all pending copies of that work in other Schedulers. This led to exceeding the
JobScheduler
jobs limit. b/111569265 - Fixed a
ConcurrentModificationException
inConstraintTracker
. b/112272753 - Changed return type annotations of
Data.getBooleanArray(String)
andData.getIntArray(String)
to@Nullable
instead of@NonNull
. b/112275229
API Changes
Worker
now extends a new class,NonBlockingWorker
. This does not affect any current usage. In the future,NonBlockingWorker
will become a fully supported entity for custom threading solutions.- Changed return type annotations of
Data.getBooleanArray(String)
andData.getIntArray(String)
to@Nullable
instead of@NonNull
. b/112275229 - Kotlin extensions: deprecated
Map.toWorkData()
and added a top-levelworkDataOf(vararg Pair<String, Any?>)
to be more consistent with existing APIs.
Version 1.0.0-alpha06
August 1, 2018
Bug Fixes
- Prevent a database lock when scheduling work. b/111801342
- Fix a bug which causes
PeriodicWork
to not run on schedule when in Doze mode. b/111469837 - Fix a race condition when tracking constraints which causes
WorkManager
to crash. googlecodelabs/android-workmanager/issues/56 - Create unique
WorkRequest
s when usingWorkRequest.Builder#build()
. b/111408337 - Enable the use of
RescheduleReceiver
only when there areWorkRequest
s that need it. b/111765853
Version 1.0.0-alpha05
July 24, 2018
API Changes
WorkManager.getInstance()
is now annotated with@NonNull
instead of@Nullable
. Instead, if the singleton isn't properly initialized in cases of manual initialization, the method will throw anIllegalStateException
. This is a breaking API change.- Added a new API,
Configuration.Builder.setMinimumLoggingLevel(int)
, which can control WorkManager verbosity. By default, WorkManager logsLog.INFO
and above. - Changed signature of
Data.getString()
so it no longer takes a default value (it is implicitlynull
). This is a breaking API change. - Marked some methods needed only for internal usage as
@hide
. This includes theConstraints
constructor,Data.toByteArray()
, andData.fromByteArray(byte[])
. This is a breaking API change.
Bug Fixes
- WorkManager no longer executes work during known cases of auto-backup. This could have resulted in a crash. b/110564377
- Fixed double-scheduling of
PeriodicWorkRequest
s when usingJobScheduler
. b/110798652 - Fixed an issue with
PeriodicWorkRequest
s not executing correctly after device doze. b/111469837 - Fixed an issue with initial delays when using Firebase JobDispatcher. b/111141023
- Fixed some potential race conditions and timing issues.
- Correctly freed up
BroadcastReceiver
s that were no longer needed. - Optimized rescheduling performance when apps restart after being force closed.
- Allowed
TestScheduler.setAllConstraintsMet(UUID)
to be called before or after enqueuing the givenWorkRequest
. b/111238024
Breaking Changes
WorkManager.getInstance()
is now annotated with@NonNull
instead of@Nullable
.- Changed signature of
Data.getString()
so it no longer takes a default value (it is implicitlynull
). - Marked some methods needed only for internal usage as
@hide
. This includes theConstraints
constructor,Data.toByteArray()
, andData.fromByteArray(byte[])
.
Version 1.0.0-alpha04
June 26, 2018
Bug Fixes
PeriodicWorkRequest
s are now correctly rescheduled when using theAlarmManager
based implementation.- Fixed a potential ANR when rescheduling all workers after a force stop or a reboot. b/110507716
- Added nullability annotations to various WorkManager APIs. b/110344065
- Log uncaught exceptions that occur during Worker execution. b/109900862
- Allowed destructive database migrations in case you decide to roll back to an older version of WorkManager. b/74633270
- Fixed a migration crash if creating duplicate implicit tags. This is a very rare issue that occurred only if you used the same implicit tag format yourself.
Version 1.0.0-alpha03
June 19, 2018
Bug Fixes
Fixed a race condition in the
AlarmManager
based implementation. b/80346526.Fixed duplicate jobs when using
JobScheduler
after a device reboot.Jobs with Content URI triggers now persist across reboots. b/80234744
Documentation updates. b/109827628, b/109758949, b/80230748
Fixed a crash when re-enqueuing a
WorkRequest
. b/109572353.Fixed Kotlin compiler warnings when using the
work-runtime-ktx
dependency.WorkManager now uses
Room
version1.1.1-rc1
.
API Changes
- Added
getStatusesSync()
, the synchronous version ofWorkContinuation.getStatuses()
. Worker
has the ability to distinguish between user-initiated cancellation and temporary os-requested stopping.Worker.isStopped()
returnstrue
if any kind of stop has been requested.Worker.isCancelled()
returnstrue
when the work has been explicitly cancelled. b/79632247- Add support for JobParameters#getNetwork() on API 28. This is exposed via
Worker.getNetwork()
. - Added
Configuration.Builder.setMaxSchedulerLimit(int maxSchedulerLimit)
so you can enforce how many jobs can be sent toJobScheduler
orAlarmManager
. This helps preventWorkManager
from taking all your availableJobScheduler
slots. - Added
Configuration.setJobSchedulerJobIdRange(int minJobSchedulerId, int maxJobSchedulerId)
which helps define a range ofJobScheduler
job ids safe forWorkManager
to use. b/79996760 Worker.getRunAttemptCount()
returns the current run count for a givenWorker
. b/79716516WorkManager.enqueueUniquePeriodicWork(String uniqueWorkName, ExistingPeriodicWorkPolicy existingPeriodicWorkPolicy, PeriodicWorkRequest periodicWork)
allows you to enqueue a uniquePeriodicWorkRequest
s. b/79600647WorkManager.cancelAllWork()
cancels allWorker
s. Libraries that depend onWorkManager
can query when this method was called last by usingWorkManager.getLastCancelAllTimeMillis()
for additional cleanup of internal state.- Added
WorkManager.pruneWork()
to remove completed jobs from the internal database. b/79950952, b/109710758
Behavior Changes
- Added an implicit tag for all
WorkRequest
s, which is the fully qualified class name for theWorker
. This allows the ability to removeWorkRequest
s withouttag
s or when theid
is not available. b/109572351
Breaking Changes
- Renamed
Worker.WorkerResult
toWorker.Result
. Worker.onStopped
now has an additionalisCancelled
parameter which is set totrue
when theWorker
has explicitly been cancelled.
Version 1.0.0-alpha02
May 24, 2018
Bug Fixes
- Fixed a
NullPointerException
onState.isFinished()
. b/79550068 - Fixed an issue which caused
Worker
s to be rescheduled onApplication.onCreate()
. b/79660657 - Fixed an issue where you could schedule more work than is allowed by the OS. b/79497378
- Moved cleanup of wake locks associated with
Worker
s to the background thread. - The
AlarmManager
implementation now correctly cleans up when all pending work is complete. - Fixed cleanup SQL queries which affected non-English locales. b/80065360
- Added support for
float
s inData
. b/79443878 Data.Builder.putAll()
now returns an instance of theBuilder
. b/79699162- More javadoc and fixes in documentation. b/79691663
API Changes
Worker
s can react to being stopped.Worker.isStopped()
can be used to check if aWorker
has been stopped.Worker.onStopped()
can be used to perform lightweight cleanup operations.Worker.getTags()
API returns aSet
of tags associated with theWorker
.- Added
javax.time.Duration
overloads for APIs which take a combination of duration andTimeUnit
s. This is guarded by@RequiresApi(26)
. WorkManager
extensions have moved from theandroidx.work.ktx
package to theandroix.work
package. The old extensions are deprecated and will be removed in a future version.Configuration.withExecutor()
is deprecated. UseConfiguration.setExecutor()
instead.
Version 1.0.0-alpha01
May 8, 2018
WorkManager simplifies scheduling and execution of
guaranteed, constraint-aware background work. This initial release is 1.0.0-alpha01
.