Google is committed to advancing racial equity for Black communities. See how.

RemoteWorkManager

abstract class RemoteWorkManager
kotlin.Any
   ↳ androidx.work.multiprocess.RemoteWorkManager

A subset of androidx.work.WorkManager APIs that are available for apps that use multiple processes.

Summary

Public methods
RemoteWorkContinuation
beginUniqueWork(@NonNull uniqueWorkName: String, @NonNull existingWorkPolicy: ExistingWorkPolicy, @NonNull work: OneTimeWorkRequest)

This method allows you to begin unique chains of work for situations where you only want one chain with a given name to be active at a time.

abstract RemoteWorkContinuation
beginUniqueWork(@NonNull uniqueWorkName: String, @NonNull existingWorkPolicy: ExistingWorkPolicy, @NonNull work: MutableList<OneTimeWorkRequest!>)

This method allows you to begin unique chains of work for situations where you only want one chain with a given name to be active at a time.

RemoteWorkContinuation
beginWith(@NonNull work: OneTimeWorkRequest)

Begins a chain with one or more OneTimeWorkRequests, which can be enqueued together in the future using RemoteWorkContinuation#enqueue().

abstract RemoteWorkContinuation

Begins a chain with one or more OneTimeWorkRequests, which can be enqueued together in the future using RemoteWorkContinuation#enqueue().

abstract ListenableFuture<Void!>

Cancels all unfinished work.

abstract ListenableFuture<Void!>
cancelAllWorkByTag(@NonNull tag: String)

Cancels all unfinished work with the given tag.

abstract ListenableFuture<Void!>
cancelUniqueWork(@NonNull uniqueWorkName: String)

Cancels all unfinished work in the work chain with the given name.

abstract ListenableFuture<Void!>
cancelWorkById(@NonNull id: UUID)

Cancels work with the given id if it isn't finished.

abstract ListenableFuture<Void!>
enqueue(@NonNull request: WorkRequest)

Enqueues one item for background processing.

abstract ListenableFuture<Void!>
enqueue(@NonNull requests: MutableList<WorkRequest!>)

Enqueues one or more items for background processing.

abstract ListenableFuture<Void!>
enqueueUniquePeriodicWork(@NonNull uniqueWorkName: String, @NonNull existingPeriodicWorkPolicy: ExistingPeriodicWorkPolicy, @NonNull periodicWork: PeriodicWorkRequest)

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

ListenableFuture<Void!>
enqueueUniqueWork(@NonNull uniqueWorkName: String, @NonNull existingWorkPolicy: ExistingWorkPolicy, @NonNull work: OneTimeWorkRequest)

This method allows you to enqueue work requests to a uniquely-named RemoteWorkContinuation, where only one continuation of a particular name can be active at a time.

abstract ListenableFuture<Void!>
enqueueUniqueWork(@NonNull uniqueWorkName: String, @NonNull existingWorkPolicy: ExistingWorkPolicy, @NonNull work: MutableList<OneTimeWorkRequest!>)

This method allows you to enqueue work requests to a uniquely-named RemoteWorkContinuation, where only one continuation of a particular name can be active at a time.

open static RemoteWorkManager
getInstance(@NonNull context: Context)

Gets the instance of RemoteWorkManager which provides a subset of WorkManager APIs that are safe to use for apps that use multiple processes.

abstract ListenableFuture<MutableList<WorkInfo!>!>
getWorkInfos(@NonNull workQuery: WorkQuery)

Gets the ListenableFuture of the List of WorkInfo for all work referenced by the WorkQuery specification.

Public methods

beginUniqueWork

@NonNull fun beginUniqueWork(
    @NonNull uniqueWorkName: String,
    @NonNull existingWorkPolicy: ExistingWorkPolicy,
    @NonNull work: OneTimeWorkRequest
): RemoteWorkContinuation

This method allows you to begin unique chains of work for situations where you only want one chain with a given name to 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.

The uniqueWorkName uniquely identifies this set of work.

If this method determines that new work should be enqueued and run, all records of previous work with uniqueWorkName will be pruned. If this method determines that new work should NOT be run, then the entire chain will be considered a no-op.

If any work in the chain fails or is cancelled, all of its dependent work inherits that state and will never run. This is particularly important if you are using APPEND as your ExistingWorkPolicy.

Parameters
uniqueWorkName String: A unique name which for this chain of work
existingWorkPolicy ExistingWorkPolicy: An ExistingWorkPolicy
work OneTimeWorkRequest: The OneTimeWorkRequest 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 sequence of work only if there is no pending work labelled with uniqueWorkName. APPEND will create a new sequence of work if there is no existing work with uniqueWorkName; otherwise, work will be added as a child of all leaf nodes labelled with uniqueWorkName.
Return
RemoteWorkContinuation A RemoteWorkContinuation that allows further chaining

beginUniqueWork

@NonNull abstract fun beginUniqueWork(
    @NonNull uniqueWorkName: String,
    @NonNull existingWorkPolicy: ExistingWorkPolicy,
    @NonNull work: MutableList<OneTimeWorkRequest!>
): RemoteWorkContinuation

This method allows you to begin unique chains of work for situations where you only want one chain with a given name to 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.

The uniqueWorkName uniquely identifies this set of work.

If this method determines that new work should be enqueued and run, all records of previous work with uniqueWorkName will be pruned. If this method determines that new work should NOT be run, then the entire chain will be considered a no-op.

If any work in the chain fails or is cancelled, all of its dependent work inherits that state and will never run. This is particularly important if you are using APPEND as your ExistingWorkPolicy.

Parameters
uniqueWorkName String: A unique name which for this chain of work
existingWorkPolicy ExistingWorkPolicy: An ExistingWorkPolicy; see below for more information
work MutableList<OneTimeWorkRequest!>: One or more OneTimeWorkRequest 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 sequence of work only if there is no pending work labelled with uniqueWorkName. APPEND will create a new sequence of work if there is no existing work with uniqueWorkName; otherwise, work will be added as a child of all leaf nodes labelled with uniqueWorkName.
Return
RemoteWorkContinuation A RemoteWorkContinuation that allows further chaining

beginWith

@NonNull fun beginWith(@NonNull work: OneTimeWorkRequest): RemoteWorkContinuation

Begins a chain with one or more OneTimeWorkRequests, which can be enqueued together in the future using RemoteWorkContinuation#enqueue().

If any work in the chain fails or is cancelled, all of its dependent work inherits that state and will never run.

Parameters
work OneTimeWorkRequest: One or more OneTimeWorkRequest to start a chain of work
Return
RemoteWorkContinuation A RemoteWorkContinuation that allows for further chaining of dependent OneTimeWorkRequest

beginWith

@NonNull abstract fun beginWith(@NonNull work: MutableList<OneTimeWorkRequest!>): RemoteWorkContinuation

Begins a chain with one or more OneTimeWorkRequests, which can be enqueued together in the future using RemoteWorkContinuation#enqueue().

If any work in the chain fails or is cancelled, all of its dependent work inherits that state and will never run.

Parameters
work MutableList<OneTimeWorkRequest!>: One or more OneTimeWorkRequest to start a chain of work
Return
RemoteWorkContinuation A RemoteWorkContinuation that allows for further chaining of dependent OneTimeWorkRequest

cancelAllWork

@NonNull abstract fun cancelAllWork(): ListenableFuture<Void!>

Cancels all unfinished work. 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.

Upon cancellation, ListenableWorker#onStopped() will be invoked for any affected workers.

Return
ListenableFuture<Void!> A ListenableFuture that can be used to determine when the cancelAllWork has completed

cancelAllWorkByTag

@NonNull abstract fun cancelAllWorkByTag(@NonNull tag: String): ListenableFuture<Void!>

Cancels all unfinished work with the given tag. Note that cancellation is a best-effort policy and work that is already executing may continue to run. Upon cancellation, ListenableWorker#onStopped() will be invoked for any affected workers.

Parameters
tag String: The tag used to identify the work
Return
ListenableFuture<Void!> An ListenableFuture that can be used to determine when the cancelAllWorkByTag has completed

cancelUniqueWork

@NonNull abstract fun cancelUniqueWork(@NonNull uniqueWorkName: String): ListenableFuture<Void!>

Cancels all unfinished work in the work chain with the given name. Note that cancellation is a best-effort policy and work that is already executing may continue to run. Upon cancellation, ListenableWorker#onStopped() will be invoked for any affected workers.

Parameters
uniqueWorkName String: The unique name used to identify the chain of work
Return
ListenableFuture<Void!> A ListenableFuture that can be used to determine when the cancelUniqueWork has completed

cancelWorkById

@NonNull abstract fun cancelWorkById(@NonNull id: UUID): ListenableFuture<Void!>

Cancels work with the given id if it isn't finished. Note that cancellation is a best-effort policy and work that is already executing may continue to run. Upon cancellation, ListenableWorker#onStopped() will be invoked for any affected workers.

Parameters
id UUID: The id of the work
Return
ListenableFuture<Void!> A ListenableFuture that can be used to determine when the cancelWorkById has completed

enqueue

@NonNull abstract fun enqueue(@NonNull request: WorkRequest): ListenableFuture<Void!>

Enqueues one item for background processing.

Parameters
request WorkRequest: The WorkRequest to enqueue
Return
ListenableFuture<Void!> A ListenableFuture that can be used to determine when the enqueue has completed

enqueue

@NonNull abstract fun enqueue(@NonNull requests: MutableList<WorkRequest!>): ListenableFuture<Void!>

Enqueues one or more items for background processing.

Parameters
requests MutableList<WorkRequest!>: One or more WorkRequest to enqueue
Return
ListenableFuture<Void!> A ListenableFuture that can be used to determine when the enqueue has completed

enqueueUniquePeriodicWork

@NonNull abstract fun enqueueUniquePeriodicWork(
    @NonNull uniqueWorkName: String,
    @NonNull existingPeriodicWorkPolicy: ExistingPeriodicWorkPolicy,
    @NonNull periodicWork: PeriodicWorkRequest
): ListenableFuture<Void!>

This method allows you to 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.

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.
Return
ListenableFuture<Void!> An ListenableFuture that can be used to determine when the enqueue has completed

enqueueUniqueWork

@NonNull fun enqueueUniqueWork(
    @NonNull uniqueWorkName: String,
    @NonNull existingWorkPolicy: ExistingWorkPolicy,
    @NonNull work: OneTimeWorkRequest
): ListenableFuture<Void!>

This method allows you to enqueue work requests to a uniquely-named RemoteWorkContinuation, where only one continuation 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.

The uniqueWorkName uniquely identifies this RemoteWorkContinuation.

Parameters
uniqueWorkName String: A unique name which for this operation
existingWorkPolicy ExistingWorkPolicy: An ExistingWorkPolicy; see below for more information
work OneTimeWorkRequest: The OneTimeWorkRequests 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 OneTimeWorkRequests only if there is no pending work labelled with uniqueWorkName. APPEND will append the OneTimeWorkRequests as leaf nodes labelled with uniqueWorkName.
Return
ListenableFuture<Void!> A ListenableFuture that can be used to determine when the enqueue has completed

enqueueUniqueWork

@NonNull abstract fun enqueueUniqueWork(
    @NonNull uniqueWorkName: String,
    @NonNull existingWorkPolicy: ExistingWorkPolicy,
    @NonNull work: MutableList<OneTimeWorkRequest!>
): ListenableFuture<Void!>

This method allows you to enqueue work requests to a uniquely-named RemoteWorkContinuation, where only one continuation 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.

The uniqueWorkName uniquely identifies this RemoteWorkContinuation.

Parameters
uniqueWorkName String: A unique name which for this operation
existingWorkPolicy ExistingWorkPolicy: An ExistingWorkPolicy
work MutableList<OneTimeWorkRequest!>: OneTimeWorkRequests 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 OneTimeWorkRequests only if there is no pending work labelled with uniqueWorkName. APPEND will append the OneTimeWorkRequests as leaf nodes labelled with uniqueWorkName.
Return
ListenableFuture<Void!> A ListenableFuture that can be used to determine when the enqueue has completed

getInstance

@NonNull open static fun getInstance(@NonNull context: Context): RemoteWorkManager

Gets the instance of RemoteWorkManager which provides a subset of WorkManager APIs that are safe to use for apps that use multiple processes.

Parameters
context Context: The application context.
Return
RemoteWorkManager The instance of RemoteWorkManager.

getWorkInfos

@NonNull abstract fun getWorkInfos(@NonNull workQuery: WorkQuery): ListenableFuture<MutableList<WorkInfo!>!>

Gets the ListenableFuture of the List of WorkInfo for all work referenced by the WorkQuery specification.

Parameters
workQuery WorkQuery: The work query specification
Return
ListenableFuture<MutableList<WorkInfo!>!> A ListenableFuture of the List of WorkInfo for work referenced by this WorkQuery.