JobScheduler
abstract class JobScheduler
| kotlin.Any | |
| ↳ | android.app.job.JobScheduler |
This is an API for scheduling various types of jobs against the framework that will be executed in your application's own process.
See android.app.job.JobInfo for more description of the types of jobs that can be run and how to construct them. You will construct these JobInfo objects and pass them to the JobScheduler with schedule(android.app.job.JobInfo). When the criteria declared are met, the system will execute this job on your application's android.app.job.JobService. You identify the service component that implements the logic for your job when you construct the JobInfo using android.app.job.JobInfo.Builder#Builder(int,android.content.ComponentName).
The framework will be intelligent about when it executes jobs, and attempt to batch and defer them as much as possible. Typically, if you don't specify a deadline on a job, it can be run at any moment depending on the current state of the JobScheduler's internal queue.
Starting in Android version android.os.Build.VERSION_CODES#UPSIDE_DOWN_CAKE, JobScheduler may try to optimize job execution by shifting execution to times with more available system resources in order to lower user impact. Factors in system health include sufficient battery, idle, charging, and access to an un-metered network. Jobs will initially be treated as if they have all these requirements, but as their deadlines approach, restrictions will become less strict. Requested requirements will not be affected by this change.
While a job is running, the system holds a wakelock on behalf of your app. For this reason, you do not need to take any action to guarantee that the device stays awake for the duration of the job.
You do not instantiate this class directly; instead, retrieve it through android.content.Context#getSystemService.
Prior to Android version android.os.Build.VERSION_CODES#S, jobs could only have a maximum of 100 jobs scheduled at a time. Starting with Android version android.os.Build.VERSION_CODES#S, that limit has been increased to 150. Expedited jobs also count towards the limit.
In Android version android.os.Build.VERSION_CODES#LOLLIPOP, jobs had a maximum execution time of one minute. Starting with Android version android.os.Build.VERSION_CODES#M and ending with Android version android.os.Build.VERSION_CODES#R, jobs had a maximum execution time of 10 minutes. Starting from Android version android.os.Build.VERSION_CODES#S, jobs will still be stopped after 10 minutes if the system is busy or needs the resources, but if not, jobs may continue running longer than 10 minutes.
Note: Beginning with API 30 (android.os.Build.VERSION_CODES#R), JobScheduler will throttle runaway applications. Calling schedule(android.app.job.JobInfo) and other such methods with very high frequency can have a high cost and so, to make sure the system doesn't get overwhelmed, JobScheduler will begin to throttle apps, regardless of target SDK version.
Summary
| Constants | |
|---|---|
| static Int |
The app is in a state that prevents the job from running (eg. the |
| static Int |
The current standby bucket prevents the job from running. |
| static Int |
The app is restricted from running in the background. |
| static Int |
The requested battery-not-low constraint is not satisfied. |
| static Int |
The requested charging constraint is not satisfied. |
| static Int |
The requested connectivity constraint is not satisfied. |
| static Int |
The requested content trigger constraint is not satisfied. |
| static Int |
The override deadline has not transpired. |
| static Int |
The requested idle constraint is not satisfied. |
| static Int |
The minimum latency has not transpired. |
| static Int |
The system's estimate of when the app will be launched is far away enough to warrant delaying this job. |
| static Int |
The requested storage-not-low constraint is not satisfied. |
| static Int |
The job is being deferred due to the device state (eg. Doze, battery saver, memory usage, thermal status, etc.). |
| static Int |
The job is currently running and is therefore not pending. |
| static Int |
The job doesn't exist. |
| static Int |
JobScheduler thinks it can defer this job to a more optimal running time. |
| static Int |
The app has consumed all of its current quota. |
| static Int |
There is no known reason why the job is pending. |
| static Int |
JobScheduler is respecting one of the user's actions (eg. force stop or adb shell commands) to defer this job. |
| static Int |
Returned from |
| static Int |
Returned from |
| Public constructors | |
|---|---|
| Public methods | |
|---|---|
| open Boolean |
Returns |
| abstract Unit |
Cancel the specified job. |
| abstract Unit |
Cancel all jobs that have been scheduled in the current namespace by the calling application. |
| open Unit |
Cancel all jobs that have been scheduled by the calling application, regardless of namespace. |
| abstract Int |
enqueue(job: JobInfo, work: JobWorkItem)Similar to |
| open JobScheduler |
forNamespace(namespace: String)Get a JobScheduler instance that is dedicated to a specific namespace. |
| abstract MutableList<JobInfo!> |
Retrieve all jobs that have been scheduled by the calling application. |
| open String? |
Get the namespace this JobScheduler instance is operating in. |
| abstract JobInfo? |
getPendingJob(jobId: Int)Look up the description of a scheduled job. |
| open Int |
getPendingJobReason(jobId: Int)Returns a reason why the job is pending and not currently executing. |
| open IntArray |
getPendingJobReasons(jobId: Int)Returns potential reasons why the job with the given |
| open MutableList<PendingJobReasonsInfo!> |
getPendingJobReasonsHistory(jobId: Int)For the given |
| open MutableMap<String!, MutableList<JobInfo!>!> |
Retrieve all jobs that have been scheduled by the calling application within the current namespace. |
| abstract Int |
Schedule a job to be executed. |
Constants
PENDING_JOB_REASON_APP
static val PENDING_JOB_REASON_APP: Int
The app is in a state that prevents the job from running (eg. the JobService component is disabled).
Value: 1PENDING_JOB_REASON_APP_STANDBY
static val PENDING_JOB_REASON_APP_STANDBY: Int
The current standby bucket prevents the job from running.
Value: 2PENDING_JOB_REASON_BACKGROUND_RESTRICTION
static val PENDING_JOB_REASON_BACKGROUND_RESTRICTION: Int
The app is restricted from running in the background.
Value: 3PENDING_JOB_REASON_CONSTRAINT_BATTERY_NOT_LOW
static val PENDING_JOB_REASON_CONSTRAINT_BATTERY_NOT_LOW: Int
The requested battery-not-low constraint is not satisfied.
Value: 4PENDING_JOB_REASON_CONSTRAINT_CHARGING
static val PENDING_JOB_REASON_CONSTRAINT_CHARGING: Int
The requested charging constraint is not satisfied.
Value: 5PENDING_JOB_REASON_CONSTRAINT_CONNECTIVITY
static val PENDING_JOB_REASON_CONSTRAINT_CONNECTIVITY: Int
The requested connectivity constraint is not satisfied.
Value: 6PENDING_JOB_REASON_CONSTRAINT_CONTENT_TRIGGER
static val PENDING_JOB_REASON_CONSTRAINT_CONTENT_TRIGGER: Int
The requested content trigger constraint is not satisfied.
Value: 7PENDING_JOB_REASON_CONSTRAINT_DEADLINE
static val PENDING_JOB_REASON_CONSTRAINT_DEADLINE: Int
The override deadline has not transpired.
Value: 16PENDING_JOB_REASON_CONSTRAINT_DEVICE_IDLE
static val PENDING_JOB_REASON_CONSTRAINT_DEVICE_IDLE: Int
The requested idle constraint is not satisfied.
Value: 8PENDING_JOB_REASON_CONSTRAINT_MINIMUM_LATENCY
static val PENDING_JOB_REASON_CONSTRAINT_MINIMUM_LATENCY: Int
The minimum latency has not transpired.
Value: 9PENDING_JOB_REASON_CONSTRAINT_PREFETCH
static val PENDING_JOB_REASON_CONSTRAINT_PREFETCH: Int
The system's estimate of when the app will be launched is far away enough to warrant delaying this job.
Value: 10PENDING_JOB_REASON_CONSTRAINT_STORAGE_NOT_LOW
static val PENDING_JOB_REASON_CONSTRAINT_STORAGE_NOT_LOW: Int
The requested storage-not-low constraint is not satisfied.
Value: 11PENDING_JOB_REASON_DEVICE_STATE
static val PENDING_JOB_REASON_DEVICE_STATE: Int
The job is being deferred due to the device state (eg. Doze, battery saver, memory usage, thermal status, etc.).
Value: 12PENDING_JOB_REASON_EXECUTING
static val PENDING_JOB_REASON_EXECUTING: Int
The job is currently running and is therefore not pending.
Value: -1PENDING_JOB_REASON_INVALID_JOB_ID
static val PENDING_JOB_REASON_INVALID_JOB_ID: Int
The job doesn't exist.
Value: -2PENDING_JOB_REASON_JOB_SCHEDULER_OPTIMIZATION
static val PENDING_JOB_REASON_JOB_SCHEDULER_OPTIMIZATION: Int
JobScheduler thinks it can defer this job to a more optimal running time.
Value: 13PENDING_JOB_REASON_QUOTA
static val PENDING_JOB_REASON_QUOTA: Int
The app has consumed all of its current quota.
Value: 14PENDING_JOB_REASON_UNDEFINED
static val PENDING_JOB_REASON_UNDEFINED: Int
There is no known reason why the job is pending. If additional reasons are added on newer Android versions, the system may return this reason to apps whose target SDK is not high enough to expect that reason.
Value: 0PENDING_JOB_REASON_USER
static val PENDING_JOB_REASON_USER: Int
JobScheduler is respecting one of the user's actions (eg. force stop or adb shell commands) to defer this job.
Value: 15RESULT_FAILURE
static val RESULT_FAILURE: Int
Returned from schedule(android.app.job.JobInfo) if a job wasn't scheduled successfully. Scheduling can fail for a variety of reasons, including, but not limited to:
- an invalid parameter was supplied (eg. the run-time for your job is too short, or the system can't resolve the requisite
JobServicein your package) - the app has too many jobs scheduled
- the app has tried to schedule too many jobs in a short amount of time
Value: 0RESULT_SUCCESS
static val RESULT_SUCCESS: Int
Returned from schedule(android.app.job.JobInfo) if this job has been successfully scheduled.
Value: 1Public constructors
JobScheduler
JobScheduler()
Public methods
canRunUserInitiatedJobs
open fun canRunUserInitiatedJobs(): Boolean
Returns true if the calling app currently holds the android.Manifest.permission#RUN_USER_INITIATED_JOBS permission, allowing it to run user-initiated jobs.
cancel
abstract fun cancel(jobId: Int): Unit
Cancel the specified job. If the job is currently executing, it is stopped immediately and the return value from its JobService.onStopJob(JobParameters) method is ignored.
| Parameters | |
|---|---|
jobId |
Int: unique identifier for the job to be canceled, as supplied to JobInfo.Builder(int, android.content.ComponentName). |
cancelAll
abstract fun cancelAll(): Unit
Cancel all jobs that have been scheduled in the current namespace by the calling application.
Starting with Android version android.os.Build.VERSION_CODES#UPSIDE_DOWN_CAKE, this will only cancel within the current namespace. If a namespace hasn't been explicitly set with forNamespace(java.lang.String), then this will cancel jobs in the default namespace. To cancel all jobs scheduled by the application, use cancelInAllNamespaces() instead.
cancelInAllNamespaces
open fun cancelInAllNamespaces(): Unit
Cancel all jobs that have been scheduled by the calling application, regardless of namespace.
enqueue
abstract fun enqueue(
job: JobInfo,
work: JobWorkItem
): Int
Similar to schedule, but allows you to enqueue work for a new or existing job. If a job with the same ID is already scheduled, it will be replaced with the new JobInfo, but any previously enqueued work will remain and be dispatched the next time it runs. If a job with the same ID is already running, the new work will be enqueued for it without stopping the job.
The work you enqueue is later retrieved through JobParameters.dequeueWork. Be sure to see there about how to process work; the act of enqueueing work changes how you should handle the overall lifecycle of an executing job.
It is strongly encouraged that you use the same JobInfo for all work you enqueue. This will allow the system to optimally schedule work along with any pending and/or currently running work. If the JobInfo changes from the last time the job was enqueued, the system will need to update the associated JobInfo, which can cause a disruption in execution. In particular, this can result in any currently running job that is processing previous work to be stopped and restarted with the new JobInfo.
It is recommended that you avoid using JobInfo.Builder.setExtras(PersistableBundle) or JobInfo.Builder.setTransientExtras(Bundle) with a JobInfo you are using to enqueue work. The system will try to compare these extras with the previous JobInfo, but there are situations where it may get this wrong and count the JobInfo as changing. (That said, you should be relatively safe with a simple set of consistent data in these fields.) You should never use JobInfo.Builder.setClipData(ClipData, int) with work you are enqueuing, since currently this will always be treated as a different JobInfo, even if the ClipData contents are exactly the same.
Note: Scheduling a job can have a high cost, even if it's rescheduling the same job and the job didn't execute, especially on platform versions before version android.os.Build.VERSION_CODES#Q. As such, the system may throttle calls to this API if calls are made too frequently in a short amount of time.
Note: Prior to Android version android.os.Build.VERSION_CODES#UPSIDE_DOWN_CAKE, JobWorkItems could not be persisted. Apps were not allowed to enqueue JobWorkItems with persisted jobs and the system would throw an IllegalArgumentException if they attempted to do so. Starting with android.os.Build.VERSION_CODES#UPSIDE_DOWN_CAKE, JobWorkItems can be persisted alongside the hosting job. However, Intents cannot be persisted. Set a PersistableBundle using JobWorkItem.Builder.setExtras(PersistableBundle) for any information that needs to be persisted.
Note: The JobService component needs to be enabled in order to successfully schedule a job.
| Parameters | |
|---|---|
job |
JobInfo: The job you wish to enqueue work for. See JobInfo.Builder for more detail on the sorts of jobs you can schedule. This value cannot be null. |
work |
JobWorkItem: New work to enqueue. This will be available later when the job starts running. This value cannot be null. |
| Return | |
|---|---|
Int |
the result of the enqueue request. Value is android.app.job.JobScheduler#RESULT_FAILURE, or android.app.job.JobScheduler#RESULT_SUCCESS |
| Exceptions | |
|---|---|
java.lang.IllegalArgumentException |
if the specified JobService doesn't exist or is disabled. |
forNamespace
open fun forNamespace(namespace: String): JobScheduler
Get a JobScheduler instance that is dedicated to a specific namespace. Any API calls using this instance will interact with jobs in that namespace, unless the API documentation says otherwise. Attempting to update a job scheduled in another namespace will not be possible but will instead create or update the job inside the current namespace. A JobScheduler instance dedicated to a namespace must be used to schedule or update jobs in that namespace.
Since leading and trailing whitespace can lead to hard-to-debug issues, they will be trimmed. An empty String (after trimming) is not allowed.
| Parameters | |
|---|---|
namespace |
String: This value cannot be null. |
| Return | |
|---|---|
JobScheduler |
This value cannot be null. |
See Also
getAllPendingJobs
abstract fun getAllPendingJobs(): MutableList<JobInfo!>
Retrieve all jobs that have been scheduled by the calling application.
| Return | |
|---|---|
MutableList<JobInfo!> |
a list of all of the app's scheduled jobs. This includes jobs that are currently started as well as those that are still waiting to run. This value cannot be null. |
getNamespace
open fun getNamespace(): String?
Get the namespace this JobScheduler instance is operating in. A null value means that the app has not specified a namespace for this instance, and it is therefore using the default namespace.
getPendingJob
abstract fun getPendingJob(jobId: Int): JobInfo?
Look up the description of a scheduled job.
| Return | |
|---|---|
JobInfo? |
The JobInfo description of the given scheduled job, or null if the supplied job ID does not correspond to any job. |
getPendingJobReason
open fun getPendingJobReason(jobId: Int): Int
Returns a reason why the job is pending and not currently executing. If there are multiple reasons why a job may be pending, this will only return one of them.
getPendingJobReasons
open fun getPendingJobReasons(jobId: Int): IntArray
Returns potential reasons why the job with the given jobId may be pending and not currently executing. The returned array will include android.app.job.JobScheduler.PendingJobReason composed of both explicitly set constraints on the job and implicit constraints imposed by the system. The results can be used to debug why a given job may not be currently executing.
getPendingJobReasonsHistory
open fun getPendingJobReasonsHistory(jobId: Int): MutableList<PendingJobReasonsInfo!>
For the given jobId, returns a limited historical view of why the job may have been pending execution. The returned list is composed of PendingJobReasonsInfo objects, each of which include a timestamp since epoch along with an array of unsatisfied constraints represented by android.app.job.JobScheduler.PendingJobReason.
These constants could either be explicitly set constraints on the job or implicit constraints imposed by the system due to various reasons. The results can be used to debug why a given job may have been pending execution.
If the only android.app.job.JobScheduler.PendingJobReason for the timestamp is android.app.job.JobScheduler.PendingJobReason#PENDING_JOB_REASON_UNDEFINED, it could mean that the job was ready to be executed at that point in time.
Note: there is no set interval for the timestamps in the returned list since constraint changes occur based on device status and various other factors.
Note: the pending job reasons history is not persisted across device reboots.
| Return | |
|---|---|
MutableList<PendingJobReasonsInfo!> |
This value cannot be null. |
| Exceptions | |
|---|---|
java.lang.IllegalArgumentException |
if the jobId is invalid. |
See Also
getPendingJobsInAllNamespaces
open fun getPendingJobsInAllNamespaces(): MutableMap<String!, MutableList<JobInfo!>!>
Retrieve all jobs that have been scheduled by the calling application within the current namespace.
| Return | |
|---|---|
MutableMap<String!, MutableList<JobInfo!>!> |
a list of all of the app's scheduled jobs scheduled with the current namespace. If a namespace hasn't been explicitly set with forNamespace(java.lang.String), then this will return jobs in the default namespace. This includes jobs that are currently started as well as those that are still waiting to run. This value cannot be null. |
schedule
abstract fun schedule(job: JobInfo): Int
Schedule a job to be executed. Will replace any currently scheduled job with the same ID with the new information in the JobInfo. If a job with the given ID is currently running, it will be stopped.
Note: Scheduling a job can have a high cost, even if it's rescheduling the same job and the job didn't execute, especially on platform versions before version android.os.Build.VERSION_CODES#Q. As such, the system may throttle calls to this API if calls are made too frequently in a short amount of time.
Note: The JobService component needs to be enabled in order to successfully schedule a job.
| Parameters | |
|---|---|
job |
JobInfo: The job you wish scheduled. See JobInfo.Builder for more detail on the sorts of jobs you can schedule. This value cannot be null. |
| Return | |
|---|---|
Int |
the result of the schedule request. Value is android.app.job.JobScheduler#RESULT_FAILURE, or android.app.job.JobScheduler#RESULT_SUCCESS |
| Exceptions | |
|---|---|
java.lang.IllegalArgumentException |
if the specified JobService doesn't exist or is disabled. |