1 /* 2 * Copyright (C) 2014 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License 15 */ 16 17 package android.app.job; 18 19 import android.annotation.NonNull; 20 import android.annotation.Nullable; 21 import android.annotation.SystemApi; 22 23 import java.util.List; 24 25 /** 26 * This is an API for scheduling various types of jobs against the framework that will be executed 27 * in your application's own process. 28 * <p> 29 * See {@link android.app.job.JobInfo} for more description of the types of jobs that can be run 30 * and how to construct them. You will construct these JobInfo objects and pass them to the 31 * JobScheduler with {@link #schedule(JobInfo)}. When the criteria declared are met, the 32 * system will execute this job on your application's {@link android.app.job.JobService}. 33 * You identify which JobService is meant to execute the logic for your job when you create the 34 * JobInfo with 35 * {@link android.app.job.JobInfo.Builder#JobInfo.Builder(int,android.content.ComponentName)}. 36 * </p> 37 * <p> 38 * The framework will be intelligent about when you receive your callbacks, and attempt to batch 39 * and defer them as much as possible. Typically if you don't specify a deadline on your job, it 40 * can be run at any moment depending on the current state of the JobScheduler's internal queue, 41 * however it might be deferred as long as until the next time the device is connected to a power 42 * source. 43 * </p> 44 * <p>You do not 45 * instantiate this class directly; instead, retrieve it through 46 * {@link android.content.Context#getSystemService 47 * Context.getSystemService(Context.JOB_SCHEDULER_SERVICE)}. 48 */ 49 public abstract class JobScheduler { 50 /** 51 * Returned from {@link #schedule(JobInfo)} when an invalid parameter was supplied. This can occur 52 * if the run-time for your job is too short, or perhaps the system can't resolve the 53 * requisite {@link JobService} in your package. 54 */ 55 public static final int RESULT_FAILURE = 0; 56 /** 57 * Returned from {@link #schedule(JobInfo)} if this job has been successfully scheduled. 58 */ 59 public static final int RESULT_SUCCESS = 1; 60 61 /** 62 * @param job The job you wish scheduled. See 63 * {@link android.app.job.JobInfo.Builder JobInfo.Builder} for more detail on the sorts of jobs 64 * you can schedule. 65 * @return An int representing ({@link #RESULT_SUCCESS} or {@link #RESULT_FAILURE}). 66 */ schedule(JobInfo job)67 public abstract int schedule(JobInfo job); 68 69 /** 70 * 71 * @param job The job to be scheduled. 72 * @param packageName The package on behalf of which the job is to be scheduled. This will be 73 * used to track battery usage and appIdleState. 74 * @param userId User on behalf of whom this job is to be scheduled. 75 * @param tag Debugging tag for dumps associated with this job (instead of the service class) 76 * @return {@link #RESULT_SUCCESS} or {@link #RESULT_FAILURE} 77 * @hide 78 */ 79 @SystemApi scheduleAsPackage(JobInfo job, String packageName, int userId, String tag)80 public abstract int scheduleAsPackage(JobInfo job, String packageName, int userId, String tag); 81 82 /** 83 * Cancel a job that is pending in the JobScheduler. 84 * @param jobId unique identifier for this job. Obtain this value from the jobs returned by 85 * {@link #getAllPendingJobs()}. 86 */ cancel(int jobId)87 public abstract void cancel(int jobId); 88 89 /** 90 * Cancel all jobs that have been registered with the JobScheduler by this package. 91 */ cancelAll()92 public abstract void cancelAll(); 93 94 /** 95 * Retrieve all jobs for this package that are pending in the JobScheduler. 96 * 97 * @return a list of all the jobs registered by this package that have not 98 * yet been executed. 99 */ getAllPendingJobs()100 public abstract @NonNull List<JobInfo> getAllPendingJobs(); 101 102 /** 103 * Retrieve a specific job for this package that is pending in the 104 * JobScheduler. 105 * 106 * @return job registered by this package that has not yet been executed. 107 */ getPendingJob(int jobId)108 public abstract @Nullable JobInfo getPendingJob(int jobId); 109 } 110