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