PeriodicWorkRequest.Builder

class PeriodicWorkRequest.Builder : WorkRequest.Builder


Builder for PeriodicWorkRequests.

Summary

Public constructors

@RequiresApi(value = 26)
Builder(workerClass: Class<ListenableWorker>, repeatInterval: Duration)

Creates a PeriodicWorkRequest to run periodically once every interval period.

@RequiresApi(value = 26)
Builder(
    workerClass: Class<ListenableWorker?>,
    repeatInterval: Duration,
    flexInterval: Duration
)

Creates a PeriodicWorkRequest to run periodically once within the flex period of every interval period.

Builder(
    workerClass: Class<ListenableWorker?>,
    repeatInterval: Long,
    repeatIntervalTimeUnit: TimeUnit
)

Creates a PeriodicWorkRequest to run periodically once every interval period.

Builder(
    workerClass: Class<ListenableWorker?>,
    repeatInterval: Long,
    repeatIntervalTimeUnit: TimeUnit,
    flexInterval: Long,
    flexIntervalTimeUnit: TimeUnit
)

Creates a PeriodicWorkRequest to run periodically once within the flex period of every interval period.

Public functions

PeriodicWorkRequest.Builder

Clears any override set by setNextScheduleTimeOverride.

PeriodicWorkRequest.Builder
setNextScheduleTimeOverride(nextScheduleTimeOverrideMillis: Long)

Overrides the next time this work is scheduled to run.

Inherited functions

From androidx.work.WorkRequest.Builder
PeriodicWorkRequest.Builder
addTag(tag: String)

Adds a tag for the work.

PeriodicWorkRequest

Builds a WorkRequest based on this Builder.

PeriodicWorkRequest.Builder
@RequiresApi(value = 26)
keepResultsForAtLeast(duration: Duration)

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

PeriodicWorkRequest.Builder
keepResultsForAtLeast(duration: Long, timeUnit: TimeUnit)

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

PeriodicWorkRequest.Builder
@RequiresApi(value = 26)
setBackoffCriteria(backoffPolicy: BackoffPolicy, duration: Duration)

Sets the backoff policy and backoff delay for the work.

PeriodicWorkRequest.Builder
setBackoffCriteria(
    backoffPolicy: BackoffPolicy,
    backoffDelay: Long,
    timeUnit: TimeUnit
)

Sets the backoff policy and backoff delay for the work.

PeriodicWorkRequest.Builder

Adds constraints to the WorkRequest.

open PeriodicWorkRequest.Builder

Marks the WorkRequest as important to the user.

PeriodicWorkRequest.Builder
setId(id: UUID)

The id of the request.

open PeriodicWorkRequest.Builder
@RequiresApi(value = 26)
setInitialDelay(duration: Duration)

Sets an initial delay for the WorkRequest.

open PeriodicWorkRequest.Builder
setInitialDelay(duration: Long, timeUnit: TimeUnit)

Sets an initial delay for the WorkRequest.

PeriodicWorkRequest.Builder
setInputData(inputData: Data)

Adds input Data to the work.

Public constructors

Builder

Added in 1.0.0
@RequiresApi(value = 26)
Builder(workerClass: Class<ListenableWorker>, repeatInterval: Duration)

Creates a PeriodicWorkRequest to run periodically once every interval period. The PeriodicWorkRequest is guaranteed to run exactly one time during this interval (subject to OS battery optimizations, such as doze mode). The repeat interval must be greater than or equal to PeriodicWorkRequest.MIN_PERIODIC_INTERVAL_MILLIS. It may run immediately, at the end of the period, or any time in between so long as the other conditions are satisfied at the time. The run time of the PeriodicWorkRequest can be restricted to a flex period within an interval (see #Builder(Class, Duration, Duration)).

Parameters
workerClass: Class<ListenableWorker>

The ListenableWorker class to run for this work

repeatInterval: Duration

The repeat interval

Builder

Added in 1.0.0
@RequiresApi(value = 26)
Builder(
    workerClass: Class<ListenableWorker?>,
    repeatInterval: Duration,
    flexInterval: Duration
)

Creates a PeriodicWorkRequest to run periodically once within the flex period of every interval period. See diagram below. The flex period begins at repeatInterval - flexInterval to the end of the interval. The repeat interval must be greater than or equal to PeriodicWorkRequest.MIN_PERIODIC_INTERVAL_MILLIS and the flex interval must be greater than or equal to PeriodicWorkRequest.MIN_PERIODIC_FLEX_MILLIS.

[_____before flex_____|_____flex_____][_____before flex_____|_____flex_____]...
[___cannot run work___|_can run work_][___cannot run work___|_can run work_]...
\____________________________________/\____________________________________/...
interval 1 interval 2 ...(repeat)
Parameters
workerClass: Class<ListenableWorker?>

The ListenableWorker class to run for this work

repeatInterval: Duration

The repeat interval

flexInterval: Duration

The duration in for which this work repeats from the end of the repeatInterval

Builder

Added in 1.0.0
Builder(
    workerClass: Class<ListenableWorker?>,
    repeatInterval: Long,
    repeatIntervalTimeUnit: TimeUnit
)

Creates a PeriodicWorkRequest to run periodically once every interval period. The PeriodicWorkRequest is guaranteed to run exactly one time during this interval (subject to OS battery optimizations, such as doze mode). The repeat interval must be greater than or equal to PeriodicWorkRequest.MIN_PERIODIC_INTERVAL_MILLIS. It may run immediately, at the end of the period, or any time in between so long as the other conditions are satisfied at the time. The run time of the PeriodicWorkRequest can be restricted to a flex period within an interval (see #Builder(Class, long, TimeUnit, long, TimeUnit)).

Parameters
workerClass: Class<ListenableWorker?>

The ListenableWorker class to run for this work

repeatInterval: Long

The repeat interval in repeatIntervalTimeUnit units

repeatIntervalTimeUnit: TimeUnit

The TimeUnit for repeatInterval

Builder

Added in 1.0.0
Builder(
    workerClass: Class<ListenableWorker?>,
    repeatInterval: Long,
    repeatIntervalTimeUnit: TimeUnit,
    flexInterval: Long,
    flexIntervalTimeUnit: TimeUnit
)

Creates a PeriodicWorkRequest to run periodically once within the flex period of every interval period. See diagram below. The flex period begins at repeatInterval - flexInterval to the end of the interval. The repeat interval must be greater than or equal to PeriodicWorkRequest.MIN_PERIODIC_INTERVAL_MILLIS and the flex interval must be greater than or equal to PeriodicWorkRequest.MIN_PERIODIC_FLEX_MILLIS.

[_____before flex_____|_____flex_____][_____before flex_____|_____flex_____]...
[___cannot run work___|_can run work_][___cannot run work___|_can run work_]...
\____________________________________/\____________________________________/...
interval 1 interval 2 ...(repeat)
Parameters
workerClass: Class<ListenableWorker?>

The ListenableWorker class to run for this work

repeatInterval: Long

The repeat interval in repeatIntervalTimeUnit units

repeatIntervalTimeUnit: TimeUnit

The TimeUnit for repeatInterval

flexInterval: Long

The duration in flexIntervalTimeUnit units for which this work repeats from the end of the repeatInterval

flexIntervalTimeUnit: TimeUnit

The TimeUnit for flexInterval

Public functions

clearNextScheduleTimeOverride

Added in 2.9.0
fun clearNextScheduleTimeOverride(): PeriodicWorkRequest.Builder

Clears any override set by setNextScheduleTimeOverride.

When an override is cleared, the next schedule is based on the previous enqueue time or run time of the Work and the result of that previous run. Eg. if the previous run returned ListenableWorker.Result.Retry at some time=T, and the next run was set by override, then clearing that override will return the schedule to T+backoffInterval if using linear backoff.

Override may be cleared while a Worker is running. The worker will schedule the next run based on its result type and interval.

setNextScheduleTimeOverride

Added in 2.9.0
fun setNextScheduleTimeOverride(nextScheduleTimeOverrideMillis: Long): PeriodicWorkRequest.Builder

Overrides the next time this work is scheduled to run.

Calling this method sets a specific time at which the work will be scheduled to run next, overriding the normal interval, flex, initial delay, and backoff.

This allows dynamic calculation of the next Periodic work schedule, which can be used to implement advanced features like adaptive refresh times, custom retry behavior, or making a newsfeed worker run before the user wakes up every morning without drift. ExistingPeriodicWorkPolicy.UPDATE should be used with these techniques to avoid cancelling a currently-running worker while scheduling the next one.

This method only sets the single next Work schedule. After that Work finishes, the override will be cleared and the Work will be scheduled normally according to the interval or backoff. The override can be cleared by setting clearNextScheduleTimeOverride on a work update request. Otherwise, the override time will persist after unrelated invocations of WorkManager.updateWork.

This method can be used from outside or inside a Worker.startWork method. If the Worker is currently running, then it will override the next time the Work starts, even if the current Worker returns ListenableWorker.Result.Retry. This behavior can be used to customize the backoff behavior of a Worker by catching Exceptions in startWork and using this method to schedule a retry.

MIN_PERIODIC_INTERVAL_MILLIS is enforced on this method to prevent infinite loops. If a previous run time occurred less than the minimum period before the override time, then the override schedule will be delayed to preserve the minimum spacing. This restriction does not apply to the very first run of periodic work, which may be instant.

Work will almost never run at this exact time in the real world. This method assigns the scheduled run time accurately, but cannot guarantee an actual run time. Actual Work run times are dependent on many factors like the underlying system scheduler, doze and power saving modes of the OS, and meeting any configured constraints. This is expected and is not considered a bug.

Parameters
nextScheduleTimeOverrideMillis: Long

The time, in System.currentTimeMillis time, to schedule this work next. If this is in the past, work may run immediately.