FileDocCategorySizeDatePackage
JobService.javaAPI DocAndroid 5.1 API10947Thu Mar 12 22:22:10 GMT 2015android.app.job

JobService

public abstract class JobService extends android.app.Service

Entry point for the callback from the {@link android.app.job.JobScheduler}.

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

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

Fields Summary
private static final String
TAG
public static final String
PERMISSION_BIND
Job services must be protected with this permission: 

...

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

private final int
MSG_EXECUTE_JOB
Identifier for a message that will result in a call to {@link #onStartJob(android.app.job.JobParameters)}.
private final int
MSG_STOP_JOB
Message that will result in a call to {@link #onStopJob(android.app.job.JobParameters)}.
private final int
MSG_JOB_FINISHED
Message that the client has completed execution of this job.
private final Object
mHandlerLock
Lock object for {@link #mHandler}.
JobHandler
mHandler
Handler we post jobs to. Responsible for calling into the client logic, and handling the callback to the system.
IJobService
mBinder
Binder for this service.
Constructors Summary
Methods Summary
voidensureHandler()

hide


      
      
        synchronized (mHandlerLock) {
            if (mHandler == null) {
                mHandler = new JobHandler(getMainLooper());
            }
        }
public final voidjobFinished(JobParameters params, boolean needsReschedule)
Callback to inform the JobManager you've finished executing. This can be called from any thread, as it will ultimately be run on your application's main thread. When the system receives this message it will release the wakelock being held.

You can specify post-execution behaviour to the scheduler here with needsReschedule . This will apply a back-off timer to your job based on the default, or what was set with {@link android.app.job.JobInfo.Builder#setBackoffCriteria(long, int)}. The original requirements are always honoured even for a backed-off job. Note that a job running in idle mode will not be backed-off. Instead what will happen is the job will be re-added to the queue and re-executed within a future idle maintenance window.

param
params Parameters specifying system-provided info about this job, this was given to your application in {@link #onStartJob(JobParameters)}.
param
needsReschedule True if this job should be rescheduled according to the back-off criteria specified at schedule-time. False otherwise.

        ensureHandler();
        Message m = Message.obtain(mHandler, MSG_JOB_FINISHED, params);
        m.arg2 = needsReschedule ? 1 : 0;
        m.sendToTarget();
public final android.os.IBinderonBind(android.content.Intent intent)

hide

        return mBinder.asBinder();
public abstract booleanonStartJob(JobParameters params)
Override this method with the callback logic for your job. Any such logic needs to be performed on a separate thread, as this function is executed on your application's main thread.

param
params Parameters specifying info about this job, including the extras bundle you optionally provided at job-creation time.
return
True if your service needs to process the work (on a separate thread). False if there's no more work to be done for this job.

public abstract booleanonStopJob(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 {@link #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
{@link android.app.job.JobInfo.Builder#setRequiredNetworkType(int)}, yet while your
job was executing the user toggled WiFi. Another example is if you had specified
{@link android.app.job.JobInfo.Builder#setRequiresDeviceIdle(boolean)}, and the phone left its
idle maintenance window. You are solely responsible for the behaviour of your application
upon receipt of this message; your app will likely start to misbehave if you ignore it. One
immediate repercussion is that the system will cease holding a wakelock for you.
param
params Parameters specifying info about this job.
return
True to indicate to the JobManager whether you'd like to reschedule this job based
on the retry criteria provided at job creation-time. False to drop the job. Regardless of
the value returned, your job must stop executing.