RemoteWorkManager

abstract class RemoteWorkManager


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

Summary

Public functions

abstract RemoteWorkContinuation
beginUniqueWork(
    uniqueWorkName: String,
    existingWorkPolicy: ExistingWorkPolicy,
    work: (Mutable)List<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
beginUniqueWork(
    uniqueWorkName: String,
    existingWorkPolicy: ExistingWorkPolicy,
    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

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

RemoteWorkContinuation

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

abstract ListenableFuture<Void!>

Cancels all unfinished work.

abstract ListenableFuture<Void!>

Cancels all unfinished work with the given tag.

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

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

abstract ListenableFuture<Void!>

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

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

Enqueues one item for background processing.

abstract ListenableFuture<Void!>

Enqueues one or more items for background processing.

abstract ListenableFuture<Void!>
enqueueUniquePeriodicWork(
    uniqueWorkName: String,
    existingPeriodicWorkPolicy: ExistingPeriodicWorkPolicy,
    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.

abstract ListenableFuture<Void!>
enqueueUniqueWork(
    uniqueWorkName: String,
    existingWorkPolicy: ExistingWorkPolicy,
    work: (Mutable)List<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.

ListenableFuture<Void!>
enqueueUniqueWork(
    uniqueWorkName: String,
    existingWorkPolicy: ExistingWorkPolicy,
    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.

java-static RemoteWorkManager
getInstance(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<(Mutable)List<WorkInfo!>!>
getWorkInfos(workQuery: WorkQuery)

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

Public functions

beginUniqueWork

Added in 2.5.0
abstract fun beginUniqueWork(
    uniqueWorkName: String,
    existingWorkPolicy: ExistingWorkPolicy,
    work: (Mutable)List<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: (Mutable)List<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.

Returns
RemoteWorkContinuation

A RemoteWorkContinuation that allows further chaining

beginUniqueWork

Added in 2.5.0
fun beginUniqueWork(
    uniqueWorkName: String,
    existingWorkPolicy: ExistingWorkPolicy,
    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.

Returns
RemoteWorkContinuation

A RemoteWorkContinuation that allows further chaining

beginWith

Added in 2.5.0
abstract fun beginWith(work: (Mutable)List<OneTimeWorkRequest!>): RemoteWorkContinuation

Begins a chain with one or more OneTimeWorkRequests, which can be enqueued together in the future using 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: (Mutable)List<OneTimeWorkRequest!>

One or more OneTimeWorkRequest to start a chain of work

Returns
RemoteWorkContinuation

A RemoteWorkContinuation that allows for further chaining of dependent OneTimeWorkRequest

beginWith

Added in 2.5.0
fun beginWith(work: OneTimeWorkRequest): RemoteWorkContinuation

Begins a chain with one or more OneTimeWorkRequests, which can be enqueued together in the future using 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

Returns
RemoteWorkContinuation

A RemoteWorkContinuation that allows for further chaining of dependent OneTimeWorkRequest

cancelAllWork

Added in 2.5.0
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, onStopped will be invoked for any affected workers.

Returns
ListenableFuture<Void!>

A ListenableFuture that can be used to determine when the cancelAllWork has completed

cancelAllWorkByTag

Added in 2.5.0
abstract fun cancelAllWorkByTag(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, onStopped will be invoked for any affected workers.

Parameters
tag: String

The tag used to identify the work

Returns
ListenableFuture<Void!>

An ListenableFuture that can be used to determine when the cancelAllWorkByTag has completed

cancelUniqueWork

Added in 2.5.0
abstract fun cancelUniqueWork(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, onStopped will be invoked for any affected workers.

Parameters
uniqueWorkName: String

The unique name used to identify the chain of work

Returns
ListenableFuture<Void!>

A ListenableFuture that can be used to determine when the cancelUniqueWork has completed

cancelWorkById

Added in 2.5.0
abstract fun cancelWorkById(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, onStopped will be invoked for any affected workers.

Parameters
id: UUID

The id of the work

Returns
ListenableFuture<Void!>

A ListenableFuture that can be used to determine when the cancelWorkById has completed

enqueue

Added in 2.5.0
abstract fun enqueue(request: WorkRequest): ListenableFuture<Void!>

Enqueues one item for background processing.

Parameters
request: WorkRequest

The WorkRequest to enqueue

Returns
ListenableFuture<Void!>

A ListenableFuture that can be used to determine when the enqueue has completed

enqueue

Added in 2.5.0
abstract fun enqueue(requests: (Mutable)List<WorkRequest!>): ListenableFuture<Void!>

Enqueues one or more items for background processing.

Parameters
requests: (Mutable)List<WorkRequest!>

One or more WorkRequest to enqueue

Returns
ListenableFuture<Void!>

A ListenableFuture that can be used to determine when the enqueue has completed

enqueueUniquePeriodicWork

Added in 2.5.0
abstract fun enqueueUniquePeriodicWork(
    uniqueWorkName: String,
    existingPeriodicWorkPolicy: ExistingPeriodicWorkPolicy,
    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.

Returns
ListenableFuture<Void!>

An ListenableFuture that can be used to determine when the enqueue has completed

enqueueUniqueWork

Added in 2.5.0
abstract fun enqueueUniqueWork(
    uniqueWorkName: String,
    existingWorkPolicy: ExistingWorkPolicy,
    work: (Mutable)List<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: (Mutable)List<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.

Returns
ListenableFuture<Void!>

A ListenableFuture that can be used to determine when the enqueue has completed

enqueueUniqueWork

Added in 2.5.0
fun enqueueUniqueWork(
    uniqueWorkName: String,
    existingWorkPolicy: ExistingWorkPolicy,
    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.

Returns
ListenableFuture<Void!>

A ListenableFuture that can be used to determine when the enqueue has completed

getInstance

Added in 2.5.0
java-static fun getInstance(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.

Returns
RemoteWorkManager

The instance of RemoteWorkManager.

getWorkInfos

Added in 2.5.0
abstract fun getWorkInfos(workQuery: WorkQuery): ListenableFuture<(Mutable)List<WorkInfo!>!>

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

Parameters
workQuery: WorkQuery

The work query specification

Returns
ListenableFuture<(Mutable)List<WorkInfo!>!>

A ListenableFuture of the List of WorkInfo for work referenced by this WorkQuery.