WorkRequest.Builder

public abstract class WorkRequest.Builder<B extends WorkRequest.Builder<@NonNull B, @NonNull ?>, W extends WorkRequest>

Known direct subclasses

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

Summary

Public methods
final @NonNull B

Adds a tag for the work.
final @NonNull W

Builds a WorkRequest based on this Builder.
final @NonNull B

Specifies that the results of this work should be kept for at least the specified amount of time.
final @NonNull B
keepResultsForAtLeast(long duration, @NonNull TimeUnit timeUnit)

Specifies that the results of this work should be kept for at least the specified amount of time.
final @NonNull B
@RequiresApi(value = 26)
setBackoffCriteria(
    @NonNull BackoffPolicy backoffPolicy,
    @NonNull Duration duration
)

Sets the backoff policy and backoff delay for the work.
final @NonNull B
setBackoffCriteria(
    @NonNull BackoffPolicy backoffPolicy,
    long backoffDelay,
    @NonNull TimeUnit timeUnit
)

Sets the backoff policy and backoff delay for the work.
final @NonNull B

Adds constraints to the WorkRequest.
@NonNull B

Marks the WorkRequest as important to the user.
final @NonNull B

Sets a unique identifier for this unit of work.
@NonNull B
@RequiresApi(value = 26)
setInitialDelay(@NonNull Duration duration)

Sets an initial delay for the WorkRequest.
@NonNull B
setInitialDelay(long duration, @NonNull TimeUnit timeUnit)

Sets an initial delay for the WorkRequest.
final @NonNull B

Adds input Data to the work.
final @NonNull B

Specifies the name of the trace span to be used by WorkManager when executing the specified WorkRequest.

Public methods

addTag

Added in 1.0.0
public final @NonNull B addTag(@NonNull String tag)

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
@NonNull String tag

A tag for identifying the work in queries.
Returns
@NonNull B

The current Builder

build

Added in 1.0.0
public final @NonNull W build()

Builds a WorkRequest based on this Builder.

Returns
@NonNull W

A WorkRequest based on this Builder

keepResultsForAtLeast

Added in 1.0.0
@RequiresApi(value = 26)
public final @NonNull B keepResultsForAtLeast(@NonNull Duration duration)

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
@NonNull Duration duration

The minimum duration of time to keep the results of this work
Returns
@NonNull B

The current Builder

keepResultsForAtLeast

Added in 1.0.0
public final @NonNull B keepResultsForAtLeast(long duration, @NonNull TimeUnit timeUnit)

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
long duration

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

The unit of time for duration
Returns
@NonNull B

The current Builder

setBackoffCriteria

Added in 1.0.0
@RequiresApi(value = 26)
public final @NonNull B setBackoffCriteria(
    @NonNull BackoffPolicy backoffPolicy,
    @NonNull Duration duration
)

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
@NonNull BackoffPolicy backoffPolicy

The BackoffPolicy to use when increasing backoff time
@NonNull Duration duration

Time to wait before retrying the work
Returns
@NonNull B

The current Builder

setBackoffCriteria

Added in 1.0.0
public final @NonNull B setBackoffCriteria(
    @NonNull BackoffPolicy backoffPolicy,
    long backoffDelay,
    @NonNull TimeUnit timeUnit
)

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
@NonNull BackoffPolicy backoffPolicy

The BackoffPolicy to use when increasing backoff time
long backoffDelay

Time to wait before retrying the work in timeUnit units
@NonNull TimeUnit timeUnit

The TimeUnit for backoffDelay
Returns
@NonNull B

The current Builder

setConstraints

Added in 1.0.0
public final @NonNull B setConstraints(@NonNull Constraints constraints)

Adds constraints to the WorkRequest.

Parameters
@NonNull Constraints constraints

The constraints for the work
Returns
@NonNull B

The current Builder

setExpedited

Added in 2.7.0
public @NonNull B setExpedited(@NonNull OutOfQuotaPolicy policy)

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
@NonNull OutOfQuotaPolicy policy

The OutOfQuotaPolicy to be used.

setId

Added in 2.8.0
public final @NonNull B setId(@NonNull UUID id)

Sets a unique identifier for this unit of work.

The id can be useful when retrieving WorkInfo by id or when trying to update an existing work. For example, using WorkManager.updateWork requires that the work has an id.

Parameters
@NonNull UUID id

The unique identifier for this unit of work.
Returns
@NonNull B

The current Builder

setInitialDelay

Added in 2.1.0
@RequiresApi(value = 26)
public @NonNull B setInitialDelay(@NonNull Duration duration)

Sets an initial delay for the WorkRequest.

Parameters
@NonNull Duration duration

The length of the delay
Returns
@NonNull 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
public @NonNull B setInitialDelay(long duration, @NonNull TimeUnit timeUnit)

Sets an initial delay for the WorkRequest.

Parameters
long duration

The length of the delay in timeUnit units
@NonNull TimeUnit timeUnit

The units of time for duration
Returns
@NonNull 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
public final @NonNull B setInputData(@NonNull Data inputData)

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
@NonNull Data inputData

key/value pairs that will be provided to the worker
Returns
@NonNull B

The current Builder

setTraceTag

Added in 2.10.0
public final @NonNull B setTraceTag(@NonNull String traceTag)

Specifies the name of the trace span to be used by WorkManager when executing the specified WorkRequest.

WorkManager uses the simple name of the ListenableWorker class truncated to a 127 character string, as the traceTag by default.

You should override the traceTag, when you are using ListenableWorker delegation via a WorkerFactory.

Parameters
@NonNull String traceTag

The name of the trace tag
Returns
@NonNull B

The current Builder