Join us on the livestream at Android Dev Summit on 7-8 November 2018, starting at 10AM PDT!

JobScheduler

public abstract class JobScheduler
extends Object

java.lang.Object
   ↳ 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 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(JobInfo). When the criteria declared are met, the system will execute this job on your application's JobService. You identify the service component that implements the logic for your job when you construct the JobInfo using JobInfo.Builder.JobInfo.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.

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 Context.getSystemService(Context.JOB_SCHEDULER_SERVICE).

Instances of this class must be obtained using Context.getSystemService(Class) with the argument JobScheduler.class or Context.getSystemService(String) with the argument Context.JOB_SCHEDULER_SERVICE.

Summary

Constants

int RESULT_FAILURE

Returned from schedule(JobInfo) when an invalid parameter was supplied.

int RESULT_SUCCESS

Returned from schedule(JobInfo) if this job has been successfully scheduled.

Public constructors

JobScheduler()

Public methods

abstract void cancel(int jobId)

Cancel the specified job.

abstract void cancelAll()

Cancel all jobs that have been scheduled by the calling application.

abstract int enqueue(JobInfo job, JobWorkItem work)

Similar to schedule(JobInfo), but allows you to enqueue work for a new or existing job.

abstract List<JobInfo> getAllPendingJobs()

Retrieve all jobs that have been scheduled by the calling application.

abstract JobInfo getPendingJob(int jobId)

Look up the description of a scheduled job.

abstract int schedule(JobInfo job)

Schedule a job to be executed.

Inherited methods

Constants

RESULT_FAILURE

added in API level 21
public static final int RESULT_FAILURE

Returned from schedule(JobInfo) when an invalid parameter was supplied. This can occur if the run-time for your job is too short, or perhaps the system can't resolve the requisite JobService in your package.

Constant Value: 0 (0x00000000)

RESULT_SUCCESS

added in API level 21
public static final int RESULT_SUCCESS

Returned from schedule(JobInfo) if this job has been successfully scheduled.

Constant Value: 1 (0x00000001)

Public constructors

JobScheduler

added in API level 21
public JobScheduler ()

Public methods

cancel

added in API level 21
public abstract void cancel (int jobId)

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

added in API level 21
public abstract void cancelAll ()

Cancel all jobs that have been scheduled by the calling application.

enqueue

added in API level 26
public abstract int enqueue (JobInfo job, 
                JobWorkItem work)

Similar to schedule(JobInfo), 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.

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 enqueue, since currently this will always be treated as a different JobInfo, even if the ClipData contents are exactly the same.

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 must never be null.

work JobWorkItem: New work to enqueue. This will be available later when the job starts running.

This value must never be null.

Returns
int the result of the enqueue request.

Value is RESULT_FAILURE or RESULT_SUCCESS.

getAllPendingJobs

added in API level 21
public abstract List<JobInfo> getAllPendingJobs ()

Retrieve all jobs that have been scheduled by the calling application.

Returns
List<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 will never be null.

getPendingJob

added in API level 24
public abstract JobInfo getPendingJob (int jobId)

Look up the description of a scheduled job.

Parameters
jobId int

Returns
JobInfo The JobInfo description of the given scheduled job, or null if the supplied job ID does not correspond to any job.

schedule

added in API level 21
public abstract int schedule (JobInfo job)

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.

Parameters
job JobInfo: The job you wish scheduled. See JobInfo.Builder for more detail on the sorts of jobs you can schedule.

This value must never be null.

Returns
int the result of the schedule request.

Value is RESULT_FAILURE or RESULT_SUCCESS.