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 java.util.List; 20 21 /** 22 * This is an API for scheduling various types of jobs against the framework that will be executed 23 * in your application's own process. 24 * <p> 25 * See {@link android.app.job.JobInfo} for more description of the types of jobs that can be run 26 * and how to construct them. You will construct these JobInfo objects and pass them to the 27 * JobScheduler with {@link #schedule(JobInfo)}. When the criteria declared are met, the 28 * system will execute this job on your application's {@link android.app.job.JobService}. 29 * You identify which JobService is meant to execute the logic for your job when you create the 30 * JobInfo with 31 * {@link android.app.job.JobInfo.Builder#JobInfo.Builder(int,android.content.ComponentName)}. 32 * </p> 33 * <p> 34 * The framework will be intelligent about when you receive your callbacks, and attempt to batch 35 * and defer them as much as possible. Typically if you don't specify a deadline on your job, it 36 * can be run at any moment depending on the current state of the JobScheduler's internal queue, 37 * however it might be deferred as long as until the next time the device is connected to a power 38 * source. 39 * </p> 40 * <p>You do not 41 * instantiate this class directly; instead, retrieve it through 42 * {@link android.content.Context#getSystemService 43 * Context.getSystemService(Context.JOB_SCHEDULER_SERVICE)}. 44 */ 45 public abstract class JobScheduler { 46 /** 47 * Returned from {@link #schedule(JobInfo)} when an invalid parameter was supplied. This can occur 48 * if the run-time for your job is too short, or perhaps the system can't resolve the 49 * requisite {@link JobService} in your package. 50 */ 51 public static final int RESULT_FAILURE = 0; 52 /** 53 * Returned from {@link #schedule(JobInfo)} if this application has made too many requests for 54 * work over too short a time. 55 */ 56 // TODO: Determine if this is necessary. 57 public static final int RESULT_SUCCESS = 1; 58 59 /** 60 * @param job The job you wish scheduled. See 61 * {@link android.app.job.JobInfo.Builder JobInfo.Builder} for more detail on the sorts of jobs 62 * you can schedule. 63 * @return If >0, this int returns the jobId of the successfully scheduled job. 64 * Otherwise you have to compare the return value to the error codes defined in this class. 65 */ schedule(JobInfo job)66 public abstract int schedule(JobInfo job); 67 68 /** 69 * Cancel a job that is pending in the JobScheduler. 70 * @param jobId unique identifier for this job. Obtain this value from the jobs returned by 71 * {@link #getAllPendingJobs()}. 72 * @return 73 */ cancel(int jobId)74 public abstract void cancel(int jobId); 75 76 /** 77 * Cancel all jobs that have been registered with the JobScheduler by this package. 78 */ cancelAll()79 public abstract void cancelAll(); 80 81 /** 82 * @return a list of all the jobs registered by this package that have not yet been executed. 83 */ getAllPendingJobs()84 public abstract List<JobInfo> getAllPendingJobs(); 85 86 } 87