lightbulb_outline Help shape the future of the Google Play Console, Android Studio, and Firebase. Start survey

JobService

public abstract class JobService
extends Service

java.lang.Object
   ↳ android.content.Context
     ↳ android.content.ContextWrapper
       ↳ android.app.Service
         ↳ android.app.job.JobService


Entry point for the callback from the JobScheduler.

This is the base class that handles asynchronous requests that were previously scheduled. You are responsible for overriding onStartJob(JobParameters), which is where you will implement your job logic.

This service executes each incoming job on a Handler running on your application's main thread. This means that you must offload your execution logic to another thread/handler/AsyncTask of your choosing. Not doing so will result in blocking any future callbacks from the JobManager - specifically onStopJob(android.app.job.JobParameters), which is meant to inform you that the scheduling requirements are no longer being met.

Summary

Constants

String PERMISSION_BIND

Job services must be protected with this permission:

     <service android:name="MyJobService"
              android:permission="android.permission.BIND_JOB_SERVICE" >
         ...
          
    

Inherited constants

Public constructors

JobService()

Public methods

final void jobFinished(JobParameters params, boolean wantsReschedule)

Call this to inform the JobScheduler that the job has finished its work.

abstract boolean onStartJob(JobParameters params)

Called to indicate that the job has begun executing.

abstract boolean onStopJob(JobParameters params)

This method is called if the system has determined that you must stop execution of your job even before you've had a chance to call jobFinished(JobParameters, boolean).

Inherited methods

Constants

PERMISSION_BIND

added in API level 21
public static final String PERMISSION_BIND

Job services must be protected with this permission:

     <service android:name="MyJobService"
              android:permission="android.permission.BIND_JOB_SERVICE" >
         ...
     </service>
 

If a job service is declared in the manifest but not protected with this permission, that service will be ignored by the system.

Constant Value: "android.permission.BIND_JOB_SERVICE"

Public constructors

JobService

added in API level 21
public JobService ()

Public methods

jobFinished

added in API level 21
public final void jobFinished (JobParameters params, 
                boolean wantsReschedule)

Call this to inform the JobScheduler that the job has finished its work. When the system receives this message, it releases the wakelock being held for the job.

You can request that the job be scheduled again by passing true as the wantsReschedule parameter. This will apply back-off policy for the job; this policy can be adjusted through the JobInfo.Builder.setBackoffCriteria(long, int) method when the job is originally scheduled. The job's initial requirements are preserved when jobs are rescheduled, regardless of backed-off policy.

A job running while the device is dozing will not be rescheduled with the normal back-off policy. Instead, the job will be re-added to the queue and executed again during a future idle maintenance window.

Parameters
params JobParameters: The parameters identifying this job, as supplied to the job in the onStartJob(JobParameters) callback.

wantsReschedule boolean: true if this job should be rescheduled according to the back-off criteria specified when it was first scheduled; false otherwise.

onStartJob

added in API level 21
public abstract boolean onStartJob (JobParameters params)

Called to indicate that the job has begun executing. Override this method with the logic for your job. Like all other component lifecycle callbacks, this method executes on your application's main thread.

Return true from this method if your job needs to continue running. If you do this, the job remains active until you call jobFinished(JobParameters, boolean) to tell the system that it has completed its work, or until the job's required constraints are no longer satisfied. For example, if the job was scheduled using setRequiresCharging(true), it will be immediately halted by the system if the user unplugs the device from power, the job's onStopJob(JobParameters) callback will be invoked, and the app will be expected to shut down all ongoing work connected with that job.

The system holds a wakelock on behalf of your app as long as your job is executing. This wakelock is acquired before this method is invoked, and is not released until either you call jobFinished(JobParameters, boolean), or after the system invokes onStopJob(JobParameters) to notify your job that it is being shut down prematurely.

Returning false from this method means your job is already finished. The system's wakelock for the job will be released, and onStopJob(JobParameters) will not be invoked.

Parameters
params JobParameters: Parameters specifying info about this job, including the optional extras configured with {@link JobInfo.Builder#setExtras(android.os.PersistableBundle). This object serves to identify this specific running job instance when calling {@link #jobFinished(JobParameters, boolean)}.

Returns
boolean true if your service will continue running, using a separate thread when appropriate. false means that this job has completed its work.

onStopJob

added in API level 21
public abstract boolean onStopJob (JobParameters params)

This method is called if the system has determined that you must stop execution of your job even before you've had a chance to call jobFinished(JobParameters, boolean).

This will happen if the requirements specified at schedule time are no longer met. For example you may have requested WiFi with JobInfo.Builder.setRequiredNetworkType(int), yet while your job was executing the user toggled WiFi. Another example is if you had specified JobInfo.Builder.setRequiresDeviceIdle(boolean), and the phone left its idle maintenance window. You are solely responsible for the behavior of your application upon receipt of this message; your app will likely start to misbehave if you ignore it.

Once this method returns, the system releases the wakelock that it is holding on behalf of the job.

Parameters
params JobParameters: The parameters identifying this job, as supplied to the job in the onStartJob(JobParameters) callback.

Returns
boolean true to indicate to the JobManager whether you'd like to reschedule this job based on the retry criteria provided at job creation-time; or false to end the job entirely. Regardless of the value returned, your job must stop executing.