Save the date! Android Dev Summit is coming to Mountain View, CA on November 7-8, 2018.

SynchronousWorkManager

public interface SynchronousWorkManager

androidx.work.SynchronousWorkManager


Blocking methods for WorkManager operations. These methods are expected to be called from a background thread.

Summary

Public methods

abstract void cancelAllWorkByTagSync(String tag)

Cancels all unfinished work with the given tag in a synchronous fashion.

abstract void cancelAllWorkSync()

Cancels all unfinished work in a synchronous fashion.

abstract void cancelUniqueWorkSync(String uniqueWorkName)

Cancels all unfinished work in the work chain with the given name in a synchronous fashion.

abstract void cancelWorkByIdSync(UUID id)

Cancels work with the given id in a synchronous fashion if it isn't finished.

abstract void enqueueSync(WorkRequest... workRequest)

Enqueues one or more WorkRequest in a synchronous fashion.

abstract void enqueueSync(List<? extends WorkRequest> workRequest)

Enqueues the List of WorkRequest in a synchronous fashion.

abstract void enqueueUniquePeriodicWorkSync(String uniqueWorkName, ExistingPeriodicWorkPolicy existingPeriodicWorkPolicy, PeriodicWorkRequest periodicWork)

This method allows you to synchronously enqueue a uniquely-named PeriodicWorkRequest, where only one PeriodicWorkRequest of a particular name can be active at a time.

abstract long getLastCancelAllTimeMillisSync()

Gets the timestamp of the last time all work was cancelled in a synchronous fashion.

abstract WorkStatus getStatusByIdSync(UUID id)

Gets the WorkStatus of a given work id in a synchronous fashion.

abstract List<WorkStatus> getStatusesByTagSync(String tag)

Gets the WorkStatus for all work with a given tag in a synchronous fashion.

abstract List<WorkStatus> getStatusesForUniqueWorkSync(String uniqueWorkName)

Gets the WorkStatus for all work for the chain of work with a given unique name in a synchronous fashion.

abstract void pruneWorkSync()

Prunes all eligible finished work from the internal database in a synchronous fashion.

Public methods

cancelAllWorkByTagSync

public abstract void cancelAllWorkByTagSync (String tag)

Cancels all unfinished work with the given tag in a synchronous fashion. Note that cancellation is dependent on timing (for example, the work could have completed in a different thread just as you issue this call). Use getStatusByIdSync(UUID) to find out the actual state of the work after this call. This method is expected to be called from a background thread.

Parameters
tag String: The tag used to identify the work

cancelAllWorkSync

public abstract void cancelAllWorkSync ()

Cancels all unfinished work in a synchronous fashion. Use this method with extreme caution! By invoking it, you will potentially affect other modules or libraries in your codebase. It is strongly recommended that you use one of the other cancellation methods at your disposal.

cancelUniqueWorkSync

public abstract void cancelUniqueWorkSync (String uniqueWorkName)

Cancels all unfinished work in the work chain with the given name in a synchronous fashion. Note that cancellation is dependent on timing (for example, the work could have completed in a different thread just as you issue this call). Use getStatusByIdSync(UUID) to find out the actual state of the work after this call. This method is expected to be called from a background thread.

Parameters
uniqueWorkName String: The unique name used to identify the chain of work

cancelWorkByIdSync

public abstract void cancelWorkByIdSync (UUID id)

Cancels work with the given id in a synchronous fashion if it isn't finished. Note that cancellation is dependent on timing (for example, the work could have completed in a different thread just as you issue this call). Use getStatusByIdSync(UUID) to find out the actual state of the work after this call. This method is expected to be called from a background thread.

Parameters
id UUID: The id of the work

enqueueSync

public abstract void enqueueSync (WorkRequest... workRequest)

Enqueues one or more WorkRequest in a synchronous fashion. This method is expected to be called from a background thread and, upon successful execution, you can rely on that the work has been enqueued.

Parameters
workRequest WorkRequest: The Array of WorkRequest

enqueueSync

public abstract void enqueueSync (List<? extends WorkRequest> workRequest)

Enqueues the List of WorkRequest in a synchronous fashion. This method is expected to be called from a background thread and, upon successful execution, you can rely on that the work has been enqueued.

Parameters
workRequest List: The List of WorkRequest

enqueueUniquePeriodicWorkSync

public abstract void enqueueUniquePeriodicWorkSync (String uniqueWorkName, 
                ExistingPeriodicWorkPolicy existingPeriodicWorkPolicy, 
                PeriodicWorkRequest periodicWork)

This method allows you to synchronously enqueue a uniquely-named PeriodicWorkRequest, where only one PeriodicWorkRequest of a particular name can be active at a time. For example, you may only want one sync operation to be active. If there is one pending, you can choose to let it run or replace it with your new work. This method is expected to be called from a background thread. The uniqueWorkName uniquely identifies this PeriodicWorkRequest.

Parameters
uniqueWorkName String: A unique name which for this operation

existingPeriodicWorkPolicy ExistingPeriodicWorkPolicy: An ExistingPeriodicWorkPolicy

periodicWork PeriodicWorkRequest: A PeriodicWorkRequest to enqueue. REPLACE ensures that if there is pending work labelled with uniqueWorkName, it will be cancelled and the new work will run. KEEP will run the new PeriodicWorkRequest only if there is no pending work labelled with uniqueWorkName.

getLastCancelAllTimeMillisSync

public abstract long getLastCancelAllTimeMillisSync ()

Gets the timestamp of the last time all work was cancelled in a synchronous fashion. This method is intended for use by library and module developers who have dependent data in their own repository that must be updated or deleted in case someone cancels their work without their prior knowledge.

Returns
long The timestamp in milliseconds when a method that cancelled all work was last invoked; this timestamp may be 0L if this never occurred.

getStatusByIdSync

public abstract WorkStatus getStatusByIdSync (UUID id)

Gets the WorkStatus of a given work id in a synchronous fashion. This method is expected to be called from a background thread.

Parameters
id UUID: The id of the work

Returns
WorkStatus A WorkStatus associated with id, or null if id is not known to WorkManager

getStatusesByTagSync

public abstract List<WorkStatus> getStatusesByTagSync (String tag)

Gets the WorkStatus for all work with a given tag in a synchronous fashion. This method is expected to be called from a background thread.

Parameters
tag String: The tag of the work

Returns
List<WorkStatus> A list of WorkStatus for work tagged with tag

getStatusesForUniqueWorkSync

public abstract List<WorkStatus> getStatusesForUniqueWorkSync (String uniqueWorkName)

Gets the WorkStatus for all work for the chain of work with a given unique name in a synchronous fashion. This method is expected to be called from a background thread.

Parameters
uniqueWorkName String: The unique name used to identify the chain of work

Returns
List<WorkStatus> A list of WorkStatus for work in the chain named uniqueWorkName

pruneWorkSync

public abstract void pruneWorkSync ()

Prunes all eligible finished work from the internal database in a synchronous fashion. Eligible work must be finished (State.SUCCEEDED, State.FAILED, or State.CANCELLED), with zero unfinished dependents.

Use this method with caution; by invoking it, you (and any modules and libraries in your codebase) will no longer be able to observe the WorkStatus of the pruned work. You do not normally need to call this method - WorkManager takes care to auto-prune its work after a sane period of time. This method also ignores the WorkRequest.Builder.keepResultsForAtLeast(long, TimeUnit) policy.