ListenableWorker
abstract class ListenableWorker
kotlin.Any | |
↳ | 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 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 | |
---|---|
abstract |
The result of a |
Public constructors | |
---|---|
<init>(@NonNull appContext: Context, @NonNull workerParams: WorkerParameters) |
Public methods | |
---|---|
Context |
Gets the application |
UUID |
getId() Gets the ID of the |
Data |
Gets the input data. |
Network? |
Gets the |
Int |
Gets the current run attempt count for this work. |
MutableSet<String!> |
getTags() Gets a |
MutableList<String!> |
Gets the list of content authorities that caused this Worker to execute. |
MutableList<Uri!> |
Gets the list of content |
Boolean |
Returns |
open Unit |
This method is invoked when this Worker has been told to stop. |
ListenableFuture<Void!> |
setForegroundAsync(@NonNull foregroundInfo: ForegroundInfo) This specifies that the |
ListenableFuture<Void!> |
setProgressAsync(@NonNull data: Data) Updates |
abstract ListenableFuture<ListenableWorker.Result!> |
Override this method to start your actual background processing. |
Public constructors
<init>
ListenableWorker(
@NonNull appContext: Context,
@NonNull workerParams: WorkerParameters)
Parameters | |
---|---|
appContext |
Context: The application Context |
workerParams |
WorkerParameters: Parameters to setup the internal state of this worker |
Public methods
getApplicationContext
@NonNull fun getApplicationContext(): Context
Gets the application android.content.Context
.
Return | |
---|---|
Context |
The application android.content.Context |
getId
@NonNull fun getId(): UUID
Gets the ID of the WorkRequest
that created this Worker.
Return | |
---|---|
UUID |
The ID of the creating WorkRequest |
getInputData
@NonNull 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
.
Return | |
---|---|
Data |
The input data for this work |
getNetwork
@RequiresApi(28) @Nullable 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.
Return | |
---|---|
Network? |
The android.net.Network specified by the OS to be used with this Worker |
getRunAttemptCount
@IntRange(0) fun getRunAttemptCount(): Int
Gets the current run attempt count for this work. Note that for periodic work, this value gets reset between periods.
Return | |
---|---|
Int |
The current run attempt count for this work. |
getTags
@NonNull fun getTags(): MutableSet<String!>
Gets a java.util.Set
of tags associated with this Worker's WorkRequest
.
Return | |
---|---|
MutableSet<String!> |
The java.util.Set of tags associated with this Worker's WorkRequest |
See Also
getTriggeredContentAuthorities
@RequiresApi(24) @NonNull fun getTriggeredContentAuthorities(): MutableList<String!>
Gets the list of content authorities that caused this Worker to execute. See JobParameters#getTriggeredContentAuthorities()
for relevant JobScheduler
code.
Return | |
---|---|
MutableList<String!> |
The list of content authorities that caused this Worker to execute |
getTriggeredContentUris
@RequiresApi(24) @NonNull fun getTriggeredContentUris(): MutableList<Uri!>
Gets the list of content android.net.Uri
s that caused this Worker to execute. See JobParameters#getTriggeredContentUris()
for relevant JobScheduler
code.
Return | |
---|---|
MutableList<Uri!> |
The list of content android.net.Uri s that caused this Worker to execute |
isStopped
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.
Return | |
---|---|
Boolean |
true if the work operation has been interrupted |
onStopped
open fun onStopped(): Unit
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
@NonNull fun setForegroundAsync(@NonNull 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
.
Parameters | |
---|---|
foregroundInfo |
ForegroundInfo: The ForegroundInfo |
Return | |
---|---|
ListenableFuture<Void!> |
A ListenableFuture which resolves after the ListenableWorker transitions to running in the context of a foreground android.app.Service . |
setProgressAsync
@NonNull fun setProgressAsync(@NonNull data: Data): ListenableFuture<Void!>
Updates ListenableWorker
progress.
Parameters | |
---|---|
data |
Data: The progress Data |
Return | |
---|---|
ListenableFuture<Void!> |
A ListenableFuture which resolves after progress is persisted. Cancelling this future is a no-op. |
startWork
@MainThread @NonNull 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 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 ListenableFuture
will be cancelled.
The future will also be cancelled if this worker is stopped for any reason (see onStopped()
).
Return | |
---|---|
ListenableFuture<ListenableWorker.Result!> |
A ListenableFuture with the Result of the computation. If you cancel this Future, WorkManager will treat this unit of work as failed. |