Configuration.Builder

public final class Configuration.Builder

A Builder for Configurations.

Summary

Public constructors

Creates a new Configuration.Builder.

Public methods
final @NonNull Configuration

Builds a Configuration object.
final @NonNull Configuration.Builder

Sets a Clock for WorkManager to calculate schedules and perform book-keeping.
final @NonNull Configuration.Builder
setContentUriTriggerWorkersLimit(int contentUriTriggerWorkersLimit)

Specifies the maximum number of Workers with Constraints.contentUriTriggers that could be enqueued simultaneously.
final @NonNull Configuration.Builder

Designates the primary process that WorkManager should schedule work in.
final @NonNull Configuration.Builder

Specifies a custom Executor to run Worker.doWork.
final @NonNull Configuration.Builder

Specifies a Consumer<Throwable> that can be used to intercept exceptions caused when trying to initialize {@link WorkManager}, that usually happens when WorkManager cannot access its internal datastore.
final @NonNull Configuration.Builder

Specifies a custom InputMergerFactory for WorkManager.
final @NonNull Configuration.Builder
setJobSchedulerJobIdRange(int minJobSchedulerId, int maxJobSchedulerId)

Specifies the range of android.app.job.JobInfo IDs that can be used by WorkManager.
final @NonNull Configuration.Builder

Regulates whether WorkManager should automatically set android.app.job.JobInfo.Builder.setImportantWhileForeground for workers that are eligible to run immediately.
final @NonNull Configuration.Builder
setMaxSchedulerLimit(int maxSchedulerLimit)

Specifies the maximum number of system requests made by WorkManager when using android.app.job.JobScheduler or android.app.AlarmManager.
final @NonNull Configuration.Builder
setMinimumLoggingLevel(int loggingLevel)

Specifies the minimum logging level, corresponding to the constants found in android.util.Log.
final @NonNull Configuration.Builder

Specifies the RunnableScheduler to be used by WorkManager.
final @NonNull Configuration.Builder
setSchedulingExceptionHandler(
    @NonNull Consumer<@NonNull Throwable> schedulingExceptionHandler
)

Specifies a Consumer<Throwable> that can be used to intercept exceptions caused when trying to schedule WorkRequests.
final @NonNull Configuration.Builder

Specifies a Executor which will be used by WorkManager for all its internal book-keeping.
final @NonNull Configuration.Builder

Specifies a custom CoroutineContext to run CoroutineWorker.doWork.
final @NonNull Configuration.Builder

Specifies a WorkerExceptionHandler that can be used to intercept exceptions caused when trying to execute ListenableWorkers.
final @NonNull Configuration.Builder

Specifies a custom WorkerFactory for WorkManager.
final @NonNull Configuration.Builder

Specifies a WorkerExceptionHandler that can be used to intercept exceptions caused when trying to initialize ListenableWorkers.

Public constructors

Builder

Added in 1.0.0
public Builder()

Creates a new Configuration.Builder.

Public methods

build

Added in 1.0.0
public final @NonNull Configuration build()

Builds a Configuration object.

Returns
@NonNull Configuration

A Configuration object with this Builder's parameters.

setClock

Added in 2.9.0
public final @NonNull Configuration.Builder setClock(@NonNull Clock clock)

Sets a Clock for WorkManager to calculate schedules and perform book-keeping.

This should only be overridden for testing. It must return the same value as System.currentTimeMillis in production code.

Parameters
@NonNull Clock clock

The Clock to use
Returns
@NonNull Configuration.Builder

This Builder instance

setContentUriTriggerWorkersLimit

Added in 2.9.0
public final @NonNull Configuration.Builder setContentUriTriggerWorkersLimit(int contentUriTriggerWorkersLimit)

Specifies the maximum number of Workers with Constraints.contentUriTriggers that could be enqueued simultaneously.

Unlike the other workers Workers with Constraints.contentUriTriggers must immediately occupy slots in JobScheduler to avoid missing updates, thus they are separated in its own category.

setDefaultProcessName

Added in 2.5.0
public final @NonNull Configuration.Builder setDefaultProcessName(@NonNull String processName)

Designates the primary process that WorkManager should schedule work in.

Parameters
@NonNull String processName

The String process name.
Returns
@NonNull Configuration.Builder

This Builder instance

setExecutor

Added in 1.0.0
public final @NonNull Configuration.Builder setExecutor(@NonNull Executor executor)

Specifies a custom Executor to run Worker.doWork.

If setWorkerCoroutineContext wasn't called then the executor will be used as CoroutineDispatcher to run CoroutineWorker as well.

Parameters
@NonNull Executor executor

An Executor for running Workers
Returns
@NonNull Configuration.Builder

This Builder instance

setInitializationExceptionHandler

Added in 2.8.0
public final @NonNull Configuration.Builder setInitializationExceptionHandler(
    @NonNull Consumer<@NonNull Throwable> exceptionHandler
)

Specifies a Consumer<Throwable> that can be used to intercept exceptions caused when trying to initialize {@link WorkManager}, that usually happens when WorkManager cannot access its internal datastore.

This exception handler will be invoked on a thread bound to Configuration.taskExecutor.

Parameters
@NonNull Consumer<@NonNull Throwable> exceptionHandler

an instance to handle exceptions
Returns
@NonNull Configuration.Builder

This Builder instance

setInputMergerFactory

Added in 2.3.0
public final @NonNull Configuration.Builder setInputMergerFactory(@NonNull InputMergerFactory inputMergerFactory)

Specifies a custom InputMergerFactory for WorkManager.

Parameters
@NonNull InputMergerFactory inputMergerFactory

A InputMergerFactory for creating InputMergers
Returns
@NonNull Configuration.Builder

This Builder instance

setJobSchedulerJobIdRange

Added in 1.0.0
public final @NonNull Configuration.Builder setJobSchedulerJobIdRange(int minJobSchedulerId, int maxJobSchedulerId)

Specifies the range of android.app.job.JobInfo IDs that can be used by WorkManager. WorkManager needs a range of at least 1000 IDs.

JobScheduler uses integers as identifiers for jobs, and WorkManager delegates to JobScheduler on certain API levels. In order to not clash job codes used in the rest of your app, you can use this method to tell WorkManager the valid range of job IDs that it can use.

The default values are 0 and Integer#MAX_VALUE.

Parameters
int minJobSchedulerId

The first valid android.app.job.JobInfo ID (inclusive).
int maxJobSchedulerId

The last valid android.app.job.JobInfo ID (inclusive).
Returns
@NonNull Configuration.Builder

This Builder instance
Throws
kotlin.IllegalArgumentException

when the size of the range is less than 1000

setMarkingJobsAsImportantWhileForeground

Added in 2.10.0
@ExperimentalConfigurationApi
public final @NonNull Configuration.Builder setMarkingJobsAsImportantWhileForeground(boolean markAsImportant)

Regulates whether WorkManager should automatically set android.app.job.JobInfo.Builder.setImportantWhileForeground for workers that are eligible to run immediately.

It will have effects only on API levels >= 23.

Parameters
boolean markAsImportant

whether to mark jobs as important
Returns
@NonNull Configuration.Builder

This Builder instance

setMaxSchedulerLimit

Added in 1.0.0
public final @NonNull Configuration.Builder setMaxSchedulerLimit(int maxSchedulerLimit)

Specifies the maximum number of system requests made by WorkManager when using android.app.job.JobScheduler or android.app.AlarmManager.

By default, WorkManager might schedule a large number of alarms or JobScheduler jobs. If your app uses JobScheduler or AlarmManager directly, this might exhaust the OS-enforced limit on the number of jobs or alarms an app is allowed to schedule. To help manage this situation, you can use this method to reduce the number of underlying jobs and alarms that WorkManager might schedule.

When the application exceeds this limit, WorkManager maintains an internal queue of WorkRequests, and schedules them when slots become free.

WorkManager requires a minimum of Configuration.MIN_SCHEDULER_LIMIT slots; this is also the default value. The total number of slots also cannot exceed 50.

Parameters
int maxSchedulerLimit

The total number of jobs which can be enqueued by WorkManager when using android.app.job.JobScheduler.
Returns
@NonNull Configuration.Builder

This Builder instance
Throws
kotlin.IllegalArgumentException

if maxSchedulerLimit is less than Configuration.MIN_SCHEDULER_LIMIT

setMinimumLoggingLevel

Added in 1.0.0
public final @NonNull Configuration.Builder setMinimumLoggingLevel(int loggingLevel)

Specifies the minimum logging level, corresponding to the constants found in android.util.Log. For example, specifying android.util.Log.VERBOSE will log everything, whereas specifying android.util.Log.ERROR will only log errors and assertions.The default value is android.util.Log.INFO.

Parameters
int loggingLevel

The minimum logging level, corresponding to the constants found in android.util.Log
Returns
@NonNull Configuration.Builder

This Builder instance

setRunnableScheduler

Added in 2.4.0
public final @NonNull Configuration.Builder setRunnableScheduler(@NonNull RunnableScheduler runnableScheduler)

Specifies the RunnableScheduler to be used by WorkManager.

This is used by the in-process scheduler to keep track of timed work.

Parameters
@NonNull RunnableScheduler runnableScheduler

The RunnableScheduler to be used
Returns
@NonNull Configuration.Builder

This Builder instance

setSchedulingExceptionHandler

Added in 2.8.0
public final @NonNull Configuration.Builder setSchedulingExceptionHandler(
    @NonNull Consumer<@NonNull Throwable> schedulingExceptionHandler
)

Specifies a Consumer<Throwable> that can be used to intercept exceptions caused when trying to schedule WorkRequests.

It allows the application to handle a Throwable throwable typically caused when trying to schedule WorkRequests.

This exception handler will be invoked on a thread bound to Configuration.taskExecutor.

Parameters
@NonNull Consumer<@NonNull Throwable> schedulingExceptionHandler

an instance to handle exceptions
Returns
@NonNull Configuration.Builder

This Builder instance

setTaskExecutor

Added in 2.1.0
public final @NonNull Configuration.Builder setTaskExecutor(@NonNull Executor taskExecutor)

Specifies a Executor which will be used by WorkManager for all its internal book-keeping.

For best performance this Executor should be bounded.

For more information look at androidx.room.RoomDatabase.Builder.setQueryExecutor.

Parameters
@NonNull Executor taskExecutor

The Executor which will be used by WorkManager for all its internal book-keeping
Returns
@NonNull Configuration.Builder

This Builder instance

setWorkerCoroutineContext

Added in 2.10.0
public final @NonNull Configuration.Builder setWorkerCoroutineContext(@NonNull CoroutineContext context)

Specifies a custom CoroutineContext to run CoroutineWorker.doWork. WorkManager will use its own Job with the provided CoroutineContext.

If setExecutor wasn't called then context will be used as Executor to run Worker as well.

Parameters
@NonNull CoroutineContext context

A CoroutineContext for running CoroutineWorkers
Returns
@NonNull Configuration.Builder

This Builder instance

setWorkerExecutionExceptionHandler

Added in 2.10.0
public final @NonNull Configuration.Builder setWorkerExecutionExceptionHandler(
    @NonNull Consumer<@NonNull WorkerExceptionInfo> workerExceptionHandler
)

Specifies a WorkerExceptionHandler that can be used to intercept exceptions caused when trying to execute ListenableWorkers.

This exception handler will be invoked on a thread bound to Configuration.taskExecutor.

Parameters
@NonNull Consumer<@NonNull WorkerExceptionInfo> workerExceptionHandler

an instance to handle exceptions
Returns
@NonNull Configuration.Builder

This Builder instance

setWorkerFactory

Added in 1.0.0
public final @NonNull Configuration.Builder setWorkerFactory(@NonNull WorkerFactory workerFactory)

Specifies a custom WorkerFactory for WorkManager.

Parameters
@NonNull WorkerFactory workerFactory

A WorkerFactory for creating ListenableWorkers
Returns
@NonNull Configuration.Builder

This Builder instance

setWorkerInitializationExceptionHandler

Added in 2.10.0
public final @NonNull Configuration.Builder setWorkerInitializationExceptionHandler(
    @NonNull Consumer<@NonNull WorkerExceptionInfo> workerExceptionHandler
)

Specifies a WorkerExceptionHandler that can be used to intercept exceptions caused when trying to initialize ListenableWorkers.

This exception handler will be invoked on a thread bound to Configuration.taskExecutor.

Parameters
@NonNull Consumer<@NonNull WorkerExceptionInfo> workerExceptionHandler

an instance to handle exceptions
Returns
@NonNull Configuration.Builder

This Builder instance