lightbulb_outline Please take our October 2018 developer survey. Start survey

ListenableWorker

public abstract class ListenableWorker
extends Object

java.lang.Object
   ↳ androidx.work.ListenableWorker


The basic object that performs work. Worker classes are instantiated at runtime by the WorkerFactory specified in the Configuration. The onStartWork() method is called on the background thread. In case the work is preempted and later restarted for any reason, a new instance of ListenableWorker is created. This means that onStartWork is called exactly once per ListenableWorker instance.

Summary

Nested classes

class ListenableWorker.Payload

The payload of an ListenableWorker.onStartWork() computation that contains both the result and the output data. 

enum ListenableWorker.Result

The result of the Worker's computation. 

Public constructors

ListenableWorker(Context appContext, WorkerParameters workerParams)

Public methods

final Context getApplicationContext()

Gets the application Context.

final UUID getId()

Gets the ID of the WorkRequest that created this Worker.

final Data getInputData()

Gets the input data.

final Network getNetwork()

Gets the Network to use for this Worker.

final int getRunAttemptCount()

Gets the current run attempt count for this work.

final Set<String> getTags()

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

final String[] getTriggeredContentAuthorities()

Gets the array of content authorities that caused this Worker to execute

final Uri[] getTriggeredContentUris()

Gets the array of content Uris that caused this Worker to execute

final boolean isCancelled()

Returns true if this Worker has been told to stop and explicitly informed that it is cancelled and will never execute again.

final boolean isStopped()

Returns true if this Worker has been told to stop.

abstract ListenableFuture<ListenableWorker.Payload> onStartWork()

Override this method to start your actual background processing.

void onStopped(boolean cancelled)

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

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.

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

getTriggeredContentAuthorities

public final String[] getTriggeredContentAuthorities ()

Gets the array of content authorities that caused this Worker to execute

Returns
String[] The array of content authorities that caused this Worker to execute

getTriggeredContentUris

public final Uri[] getTriggeredContentUris ()

Gets the array of content Uris that caused this Worker to execute

Returns
Uri[] The array of content Uris that caused this Worker to execute

isCancelled

public final boolean isCancelled ()

Returns true if this Worker has been told to stop and explicitly informed that it is cancelled and will never execute again. If isStopped() returns true but this method returns false, that means the system has decided to preempt the task.

Note that it is almost never sufficient to check only this method; its value is only meaningful when isStopped() returns true.

Returns
boolean true if this work operation has been cancelled

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.

Returns
boolean true if the work operation has been interrupted

onStartWork

public abstract ListenableFuture<ListenableWorker.Payload> onStartWork ()

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

Returns
ListenableFuture<ListenableWorker.Payload> A ListenableFuture with the ListenableWorker.Payload of the computation. If you cancel this Future, WorkManager will treat this unit of work as failed.

onStopped

public void onStopped (boolean cancelled)

This method is invoked when this Worker has been told to stop. 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.

Parameters
cancelled boolean: If true, the work has been explicitly cancelled