ListenableWorker

abstract class ListenableWorker

Known direct subclasses
CoroutineWorker

A ListenableWorker implementation that provides interop with Kotlin Coroutines.

RemoteListenableWorker

Is an implementation of a ListenableWorker that can bind to a remote process.

RxWorker

RxJava2 interoperability Worker implementation.

RxWorker

RxJava3 interoperability Worker implementation.

Worker

A class that performs work synchronously on a background thread provided by WorkManager.

Known indirect subclasses
RemoteCoroutineWorker

An implementation of RemoteListenableWorker that can bind to a remote process.

WorkManagerScheduler.SchedulerWorker

A Worker that starts the target service if the requirements are met.


A class that can perform work asynchronously in WorkManager. For most cases, we recommend using Worker, which offers a simple synchronous API that is executed on a pre-specified background thread.

ListenableWorker classes are instantiated at runtime by the WorkerFactory specified in the Configuration. The startWork method is called on the main thread.

In case the work is preempted and later restarted for any reason, a new instance of ListenableWorker is created. This means that startWork is called exactly once per ListenableWorker instance. A new ListenableWorker is created if a unit of work needs to be rerun.

A ListenableWorker is given a maximum of ten minutes to finish its execution and return a Result. After this time has expired, the worker will be signalled to stop and its com.google.common.util.concurrent.ListenableFuture will be cancelled.

Exercise caution when renaming or removing ListenableWorkers from your codebase.

Summary

Nested types

The result of a ListenableWorker's computation.

Public constructors

ListenableWorker(appContext: Context, workerParams: WorkerParameters)

Public functions

Context

Gets the application android.content.Context.

ListenableFuture<ForegroundInfo!>

Return an instance of ForegroundInfo if the WorkRequest is important to the user.

UUID

Gets the ID of the WorkRequest that created this Worker.

Data

Gets the input data.

Network?
@RequiresApi(value = 28)
getNetwork()

Gets the android.net.Network to use for this Worker.

@IntRange(from = 0) Int

Gets the current run attempt count for this work.

Int

Returns a reason why this worker has been stopped.

(Mutable)Set<String!>

Gets a java.util.Set of tags associated with this Worker's WorkRequest.

(Mutable)List<String!>

Gets the list of content authorities that caused this Worker to execute.

(Mutable)List<Uri!>

Gets the list of content android.net.Uris that caused this Worker to execute.

Boolean

Returns true if this Worker has been told to stop.

Unit

This method is invoked when this Worker has been told to stop.

ListenableFuture<Void!>

This specifies that the WorkRequest is long-running or otherwise important.

ListenableFuture<Void!>

Updates ListenableWorker progress.

abstract ListenableFuture<ListenableWorker.Result!>

Override this method to start your actual background processing.

Public constructors

ListenableWorker

Added in 1.0.0
ListenableWorker(appContext: Context, workerParams: WorkerParameters)
Parameters
appContext: Context

The application Context

workerParams: WorkerParameters

Parameters to setup the internal state of this worker

Public functions

getApplicationContext

Added in 1.0.0
fun getApplicationContext(): Context

Gets the application android.content.Context.

Returns
Context

The application android.content.Context

getForegroundInfoAsync

Added in 2.7.0
fun getForegroundInfoAsync(): ListenableFuture<ForegroundInfo!>

Return an instance of ForegroundInfo if the WorkRequest is important to the user. In this case, WorkManager provides a signal to the OS that the process should be kept alive while this work is executing.

Prior to Android S, WorkManager manages and runs a foreground service on your behalf to execute the WorkRequest, showing the notification provided in the ForegroundInfo. To update this notification subsequently, the application can use android.app.NotificationManager.

Starting in Android S and above, WorkManager manages this WorkRequest using an immediate job.

Returns
ListenableFuture<ForegroundInfo!>

A com.google.common.util.concurrent.ListenableFuture of ForegroundInfo instance if the WorkRequest is marked immediate. For more information look at setExpedited.

getId

Added in 1.0.0
fun getId(): UUID

Gets the ID of the WorkRequest that created this Worker.

Returns
UUID

The ID of the creating WorkRequest

getInputData

Added in 1.0.0
fun getInputData(): Data

Gets the input data. Note that in the case that there are multiple prerequisites for this Worker, the input data has been run through an InputMerger.

Returns
Data

The input data for this work

See also
setInputMerger

getNetwork

Added in 1.0.0
@RequiresApi(value = 28)
fun getNetwork(): Network?

Gets the android.net.Network to use for this Worker. This method returns null if there is no network needed for this work request.

Returns
Network?

The android.net.Network specified by the OS to be used with this Worker

getRunAttemptCount

Added in 1.0.0
fun getRunAttemptCount(): @IntRange(from = 0) Int

Gets the current run attempt count for this work. Note that for periodic work, this value gets reset between periods.

Returns
@IntRange(from = 0) Int

The current run attempt count for this work.

getStopReason

Added in 2.9.0
@StopReason
@RequiresApi(value = 31)
fun getStopReason(): Int

Returns a reason why this worker has been stopped. Return values match values of JobParameters.STOP_REASON_* constants, e.g. STOP_REASON_CONSTRAINT_CHARGING or STOP_REASON_UNKNOWN

If a worker hasn't been stopped, STOP_REASON_NOT_STOPPED is returned.

getTags

Added in 1.0.0
fun getTags(): (Mutable)Set<String!>

Gets a java.util.Set of tags associated with this Worker's WorkRequest.

Returns
(Mutable)Set<String!>

The java.util.Set of tags associated with this Worker's WorkRequest

See also
addTag

getTriggeredContentAuthorities

Added in 1.0.0
@RequiresApi(value = 24)
fun getTriggeredContentAuthorities(): (Mutable)List<String!>

Gets the list of content authorities that caused this Worker to execute. See JobParameters#getTriggeredContentAuthorities() for relevant JobScheduler code.

Returns
(Mutable)List<String!>

The list of content authorities that caused this Worker to execute

getTriggeredContentUris

Added in 1.0.0
@RequiresApi(value = 24)
fun getTriggeredContentUris(): (Mutable)List<Uri!>

Gets the list of content android.net.Uris that caused this Worker to execute. See JobParameters#getTriggeredContentUris() for relevant JobScheduler code.

Returns
(Mutable)List<Uri!>

The list of content android.net.Uris that caused this Worker to execute

isStopped

Added in 1.0.0
fun isStopped(): Boolean

Returns true if this Worker has been told to stop. This could be because of an explicit cancellation signal by the user, or because the system has decided to preempt the task. In these cases, the results of the work will be ignored by WorkManager and it is safe to stop the computation. WorkManager will retry the work at a later time if necessary.

Returns
Boolean

true if the work operation has been interrupted

onStopped

Added in 1.0.0
fun onStopped(): Unit

This method is invoked when this Worker has been told to stop. At this point, the com.google.common.util.concurrent.ListenableFuture returned by the instance of startWork is also cancelled. This could happen due to an explicit cancellation signal by the user, or because the system has decided to preempt the task. In these cases, the results of the work will be ignored by WorkManager. All processing in this method should be lightweight - there are no contractual guarantees about which thread will invoke this call, so this should not be a long-running or blocking operation.

setForegroundAsync

Added in 2.3.0
fun setForegroundAsync(foregroundInfo: ForegroundInfo): ListenableFuture<Void!>

This specifies that the WorkRequest is long-running or otherwise important. In this case, WorkManager provides a signal to the OS that the process should be kept alive if possible while this work is executing.

Calls to setForegroundAsync *must* complete before a ListenableWorker signals completion by returning a Result.

Under the hood, WorkManager manages and runs a foreground service on your behalf to execute this WorkRequest, showing the notification provided in ForegroundInfo.

Calling setForegroundAsync will fail with an IllegalStateException when the process is subject to foreground service restrictions. Consider using setExpedited and getForegroundInfoAsync instead.

Parameters
foregroundInfo: ForegroundInfo

The ForegroundInfo

Returns
ListenableFuture<Void!>

A com.google.common.util.concurrent.ListenableFuture which resolves after the ListenableWorker transitions to running in the context of a foreground android.app.Service.

setProgressAsync

Added in 2.3.0
fun setProgressAsync(data: Data): ListenableFuture<Void!>

Updates ListenableWorker progress.

Parameters
data: Data

The progress Data

Returns
ListenableFuture<Void!>

A com.google.common.util.concurrent.ListenableFuture which resolves after progress is persisted. Cancelling this future is a no-op.

startWork

Added in 1.0.0
@MainThread
abstract fun startWork(): ListenableFuture<ListenableWorker.Result!>

Override this method to start your actual background processing. This method is called on the main thread.

A ListenableWorker has a well defined execution window to to finish its execution and return a Result. After this time has expired, the worker will be signalled to stop and its com.google.common.util.concurrent.ListenableFuture will be cancelled.

The future will also be cancelled if this worker is stopped for any reason (see onStopped).

Returns
ListenableFuture<ListenableWorker.Result!>

A com.google.common.util.concurrent.ListenableFuture with the Result of the computation. If you cancel this Future, WorkManager will treat this unit of work as failed.