ListenableWorker
public abstract class ListenableWorker
CoroutineWorker |
A |
RemoteListenableDelegatingWorker |
A worker which can delegate to an instance of RemoteListenableWorker but importantly only constructs an instance of the RemoteListenableWorker in the remote process. |
RemoteListenableWorker |
Is an implementation of a |
RxWorker |
RxJava2 interoperability Worker implementation. |
RxWorker |
RxJava3 interoperability Worker implementation. |
Worker |
A class that performs work synchronously on a background thread provided by |
RemoteCoroutineWorker |
An implementation of |
WorkManagerScheduler.SchedulerWorker |
A |
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 |
|---|
public abstract class ListenableWorker.ResultThe result of a |
Public constructors |
|---|
ListenableWorker( |
Public methods |
|
|---|---|
final @NonNull Context |
Gets the application |
@NonNull ListenableFuture<ForegroundInfo> |
Return an instance of |
final @NonNull UUID |
getId()Gets the ID of the |
final @NonNull Data |
Gets the input data. |
final @Nullable Network |
@RequiresApi(value = 28)Gets the |
final @IntRange(from = 0) int |
Gets the current run attempt count for this work. |
final int |
@RequiresApi(value = 31)Returns a reason why this worker has been stopped. |
final @NonNull Set<String> |
getTags()Gets a |
final @NonNull List<String> |
@RequiresApi(value = 24)Gets the list of content authorities that caused this Worker to execute. |
final @NonNull List<Uri> |
@RequiresApi(value = 24)Gets the list of content |
final boolean |
Returns |
void |
This method is invoked when this Worker has been told to stop. |
final @NonNull ListenableFuture<Void> |
setForegroundAsync(@NonNull ForegroundInfo foregroundInfo)This specifies that the |
@NonNull ListenableFuture<Void> |
setProgressAsync(@NonNull Data data)Updates |
abstract @NonNull ListenableFuture<ListenableWorker.Result> |
Override this method to start your actual background processing. |
Public constructors
ListenableWorker
public ListenableWorker(
@NonNull Context appContext,
@NonNull WorkerParameters workerParams
)
| Parameters | |
|---|---|
@NonNull Context appContext |
The application |
@NonNull WorkerParameters workerParams |
Parameters to setup the internal state of this worker |
Public methods
getApplicationContext
public final @NonNull Context getApplicationContext()
Gets the application android.content.Context.
| Returns | |
|---|---|
@NonNull Context |
The application |
getForegroundInfoAsync
public @NonNull ListenableFuture<ForegroundInfo> getForegroundInfoAsync()
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 | |
|---|---|
@NonNull ListenableFuture<ForegroundInfo> |
A |
getId
public final @NonNull UUID getId()
Gets the ID of the WorkRequest that created this Worker.
| Returns | |
|---|---|
@NonNull UUID |
The ID of the creating |
getInputData
public final @NonNull Data getInputData()
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.
| See also | |
|---|---|
setInputMerger |
getNetwork
@RequiresApi(value = 28)
public final @Nullable Network getNetwork()
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 | |
|---|---|
@Nullable Network |
The |
getRunAttemptCount
public final @IntRange(from = 0) int getRunAttemptCount()
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
@RequiresApi(value = 31)
public final int getStopReason()
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
public final @NonNull Set<String> getTags()
Gets a java.util.Set of tags associated with this Worker's WorkRequest.
| Returns | |
|---|---|
@NonNull Set<String> |
The |
| See also | |
|---|---|
addTag |
getTriggeredContentAuthorities
@RequiresApi(value = 24)
public final @NonNull List<String> getTriggeredContentAuthorities()
Gets the list of content authorities that caused this Worker to execute. See JobParameters#getTriggeredContentAuthorities() for relevant JobScheduler code.
getTriggeredContentUris
@RequiresApi(value = 24)
public final @NonNull List<Uri> getTriggeredContentUris()
Gets the list of content android.net.Uris that caused this Worker to execute. See JobParameters#getTriggeredContentUris() for relevant JobScheduler code.
| Returns | |
|---|---|
@NonNull List<Uri> |
The list of content |
| See also | |
|---|---|
addContentUriTrigger |
isStopped
public final boolean isStopped()
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 |
|
onStopped
public void onStopped()
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
public final @NonNull ListenableFuture<Void> setForegroundAsync(@NonNull ForegroundInfo foregroundInfo)
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 | |
|---|---|
@NonNull ForegroundInfo foregroundInfo |
The |
| Returns | |
|---|---|
@NonNull ListenableFuture<Void> |
A |
setProgressAsync
public @NonNull ListenableFuture<Void> setProgressAsync(@NonNull Data data)
Updates ListenableWorker progress.
| Returns | |
|---|---|
@NonNull ListenableFuture<Void> |
A |
startWork
@MainThread
public abstract @NonNull ListenableFuture<ListenableWorker.Result> startWork()
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 | |
|---|---|
@NonNull ListenableFuture<ListenableWorker.Result> |
A |