ListenableWorker
public
abstract
class
ListenableWorker
extends Object
| java.lang.Object | |
| ↳ | androidx.work.ListenableWorker |
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
ListenableWorker.Result. After this time has expired, the worker will be signalled to stop and its
ListenableFuture will be cancelled.
Exercise caution when renaming or removing ListenableWorkers from your codebase.
Summary
Nested classes | |
|---|---|
class |
ListenableWorker.Result
The result of a |
Public constructors | |
|---|---|
ListenableWorker(Context appContext, WorkerParameters workerParams)
|
|
Public methods | |
|---|---|
final
Context
|
getApplicationContext()
Gets the application |
final
UUID
|
getId()
Gets the ID of the |
final
Data
|
getInputData()
Gets the input data. |
final
Network
|
getNetwork()
Gets the |
final
int
|
getRunAttemptCount()
Gets the current run attempt count for this work. |
final
Set<String>
|
getTags()
Gets a |
final
List<String>
|
getTriggeredContentAuthorities()
Gets the list of content authorities that caused this Worker to execute. |
final
List<Uri>
|
getTriggeredContentUris()
Gets the list of content |
final
boolean
|
isStopped()
Returns |
void
|
onStopped()
This method is invoked when this Worker has been told to stop. |
final
ListenableFuture<Void>
|
setForegroundAsync(ForegroundInfo foregroundInfo)
This specifies that the |
final
ListenableFuture<Void>
|
setProgressAsync(Data data)
Updates |
abstract
ListenableFuture<ListenableWorker.Result>
|
startWork()
Override this method to start your actual background processing. |
Inherited methods | |
|---|---|
Public constructors
ListenableWorker
public ListenableWorker (Context appContext, WorkerParameters workerParams)
| Parameters | |
|---|---|
appContext |
Context: The application Context |
workerParams |
WorkerParameters: Parameters to setup the internal state of this worker
|
Public methods
getApplicationContext
public final Context getApplicationContext ()
Gets the application Context.
| Returns | |
|---|---|
Context |
The application Context
|
getId
public final UUID getId ()
Gets the ID of the WorkRequest that created this Worker.
| Returns | |
|---|---|
UUID |
The ID of the creating WorkRequest
|
getInputData
public final 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.
| Returns | |
|---|---|
Data |
The input data for this work |
getNetwork
public final Network getNetwork ()
Gets the Network to use for this Worker. This method returns
null if there is no network needed for this work request.
| Returns | |
|---|---|
Network |
The Network specified by the OS to be used with this Worker
|
getRunAttemptCount
public final int getRunAttemptCount ()
Gets the current run attempt count for this work. Note that for periodic work, this value gets reset between periods.
| Returns | |
|---|---|
int |
The current run attempt count for this work. |
getTags
public final Set<String> getTags ()
Gets a Set of tags associated with this Worker's WorkRequest.
| Returns | |
|---|---|
Set<String> |
The Set of tags associated with this Worker's WorkRequest |
See also:
getTriggeredContentAuthorities
public final List<String> getTriggeredContentAuthorities ()
Gets the list of content authorities that caused this Worker to execute. See
JobParameters#getTriggeredContentAuthorities() for relevant JobScheduler
code.
| Returns | |
|---|---|
List<String> |
The list of content authorities that caused this Worker to execute |
getTriggeredContentUris
public final List<Uri> getTriggeredContentUris ()
Gets the list of content Uris that caused this Worker to execute. See
JobParameters#getTriggeredContentUris() for relevant JobScheduler code.
| Returns | |
|---|---|
List<Uri> |
The list of content Uris that caused this Worker to execute |
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 |
true if the work operation has been interrupted
|
onStopped
public void onStopped ()
This method is invoked when this Worker has been told to stop. At this point, the
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 ListenableFuture<Void> setForegroundAsync (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 ListenableWorker.Result.
Under the hood, WorkManager manages and runs a foreground service on your behalf to
execute this WorkRequest, showing the notification provided in
ForegroundInfo.
| Parameters | |
|---|---|
foregroundInfo |
ForegroundInfo: The ForegroundInfo |
| Returns | |
|---|---|
ListenableFuture<Void> |
A ListenableFuture which resolves after the ListenableWorker
transitions to running in the context of a foreground Service.
|
setProgressAsync
public final ListenableFuture<Void> setProgressAsync (Data data)
Updates ListenableWorker progress.
| Parameters | |
|---|---|
data |
Data: The progress Data |
| Returns | |
|---|---|
ListenableFuture<Void> |
A ListenableFuture which resolves after progress is persisted.
Cancelling this future is a no-op.
|
startWork
public abstract ListenableFuture<ListenableWorker.Result> startWork ()
Override this method to start your actual background processing. This method is called on the main thread.
A ListenableWorker is given a maximum of ten minutes to finish its execution and return a
ListenableWorker.Result. After this time has expired, the worker will be signalled to stop and its
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 ListenableFuture with the ListenableWorker.Result of the computation. If you
cancel this Future, WorkManager will treat this unit of work as failed.
|
Content and code samples on this page are subject to the licenses described in the Content License. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2020-04-01 UTC.