WorkRequest.Builder

abstract class WorkRequest.Builder<B : WorkRequest.Builder<B, *>, W : WorkRequest>


A builder for WorkRequests. There are two concrete implementations of this class: OneTimeWorkRequest.Builder and PeriodicWorkRequest.Builder.

Summary

Public functions

B
addTag(tag: String)

Adds a tag for the work.

W

Builds a WorkRequest based on this Builder.

B
@RequiresApi(value = 26)
keepResultsForAtLeast(duration: Duration)

Specifies that the results of this work should be kept for at least the specified amount of time.

B
keepResultsForAtLeast(duration: Long, timeUnit: TimeUnit)

Specifies that the results of this work should be kept for at least the specified amount of time.

B
@RequiresApi(value = 26)
setBackoffCriteria(backoffPolicy: BackoffPolicy, duration: Duration)

Sets the backoff policy and backoff delay for the work.

B
setBackoffCriteria(
    backoffPolicy: BackoffPolicy,
    backoffDelay: Long,
    timeUnit: TimeUnit
)

Sets the backoff policy and backoff delay for the work.

B

Adds constraints to the WorkRequest.

open B

Marks the WorkRequest as important to the user.

B
setId(id: UUID)

The id of the request.

open B
@RequiresApi(value = 26)
setInitialDelay(duration: Duration)

Sets an initial delay for the WorkRequest.

open B
setInitialDelay(duration: Long, timeUnit: TimeUnit)

Sets an initial delay for the WorkRequest.

B
setInputData(inputData: Data)

Adds input Data to the work.

Public functions

addTag

Added in 1.0.0
fun addTag(tag: String): B

Adds a tag for the work. You can query and cancel work by tags. Tags are particularly useful for modules or libraries to find and operate on their own work.

Parameters
tag: String

A tag for identifying the work in queries.

Returns
B

The current Builder

build

Added in 1.0.0
fun build(): W

Builds a WorkRequest based on this Builder.

Returns
W

A WorkRequest based on this Builder

keepResultsForAtLeast

Added in 1.0.0
@RequiresApi(value = 26)
fun keepResultsForAtLeast(duration: Duration): B

Specifies that the results of this work should be kept for at least the specified amount of time. After this time has elapsed, the results may be pruned at the discretion of WorkManager when this WorkRequest has reached a finished state (see WorkInfo.State.isFinished) and there are no pending dependent jobs.

When the results of a work are pruned, it becomes impossible to query for its WorkInfo.

Specifying a long duration here may adversely affect performance in terms of app storage and database query time.

Parameters
duration: Duration

The minimum duration of time to keep the results of this work

Returns
B

The current Builder

keepResultsForAtLeast

Added in 1.0.0
fun keepResultsForAtLeast(duration: Long, timeUnit: TimeUnit): B

Specifies that the results of this work should be kept for at least the specified amount of time. After this time has elapsed, the results may be pruned at the discretion of WorkManager when there are no pending dependent jobs.

When the results of a work are pruned, it becomes impossible to query for its WorkInfo.

Specifying a long duration here may adversely affect performance in terms of app storage and database query time.

Parameters
duration: Long

The minimum duration of time (in timeUnit units) to keep the results of this work

timeUnit: TimeUnit

The unit of time for duration

Returns
B

The current Builder

setBackoffCriteria

Added in 1.0.0
@RequiresApi(value = 26)
fun setBackoffCriteria(backoffPolicy: BackoffPolicy, duration: Duration): B

Sets the backoff policy and backoff delay for the work. The default values are BackoffPolicy.EXPONENTIAL and WorkRequest#DEFAULT_BACKOFF_DELAY_MILLIS, respectively. duration will be clamped between WorkRequest.MIN_BACKOFF_MILLIS and WorkRequest.MAX_BACKOFF_MILLIS.

Parameters
backoffPolicy: BackoffPolicy

The BackoffPolicy to use when increasing backoff time

duration: Duration

Time to wait before retrying the work

Returns
B

The current Builder

setBackoffCriteria

Added in 1.0.0
fun setBackoffCriteria(
    backoffPolicy: BackoffPolicy,
    backoffDelay: Long,
    timeUnit: TimeUnit
): B

Sets the backoff policy and backoff delay for the work. The default values are BackoffPolicy.EXPONENTIAL and WorkRequest#DEFAULT_BACKOFF_DELAY_MILLIS, respectively. backoffDelay will be clamped between WorkRequest.MIN_BACKOFF_MILLIS and WorkRequest.MAX_BACKOFF_MILLIS.

Parameters
backoffPolicy: BackoffPolicy

The BackoffPolicy to use when increasing backoff time

backoffDelay: Long

Time to wait before retrying the work in timeUnit units

timeUnit: TimeUnit

The TimeUnit for backoffDelay

Returns
B

The current Builder

setConstraints

Added in 1.0.0
fun setConstraints(constraints: Constraints): B

Adds constraints to the WorkRequest.

Parameters
constraints: Constraints

The constraints for the work

Returns
B

The current Builder

setExpedited

Added in 2.7.0
open fun setExpedited(policy: OutOfQuotaPolicy): B

Marks the WorkRequest as important to the user. In this case, WorkManager provides an additional signal to the OS that this work is important.

Parameters
policy: OutOfQuotaPolicy

The OutOfQuotaPolicy to be used.

setId

Added in 2.8.0
fun setId(id: UUID): B

The id of the request.

It is a useful for the creation of WorkRequest for the WorkManager.updateWork, that uses id for identifying an work that should be updated.

setInitialDelay

Added in 2.1.0
@RequiresApi(value = 26)
open fun setInitialDelay(duration: Duration): B

Sets an initial delay for the WorkRequest.

Parameters
duration: Duration

The length of the delay

Returns
B

The current Builder

Throws
kotlin.IllegalArgumentException

if the given initial delay will push the execution time past Long.MAX_VALUE and cause an overflow

setInitialDelay

Added in 2.1.0
open fun setInitialDelay(duration: Long, timeUnit: TimeUnit): B

Sets an initial delay for the WorkRequest.

Parameters
duration: Long

The length of the delay in timeUnit units

timeUnit: TimeUnit

The units of time for duration

Returns
B

The current Builder

Throws
kotlin.IllegalArgumentException

if the given initial delay will push the execution time past Long.MAX_VALUE and cause an overflow

setInputData

Added in 1.0.0
fun setInputData(inputData: Data): B

Adds input Data to the work. If a worker has prerequisites in its chain, this Data will be merged with the outputs of the prerequisites using an InputMerger.

Parameters
inputData: Data

key/value pairs that will be provided to the worker

Returns
B

The current Builder