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
17package android.app.job;
18
19import android.annotation.IntDef;
20import android.annotation.NonNull;
21import android.annotation.Nullable;
22import android.annotation.RequiresPermission;
23import android.annotation.SystemApi;
24import android.annotation.SystemService;
25import android.content.ClipData;
26import android.content.Context;
27import android.content.Intent;
28import android.os.Bundle;
29import android.os.PersistableBundle;
30
31import java.lang.annotation.Retention;
32import java.lang.annotation.RetentionPolicy;
33import java.util.List;
34
35/**
36 * This is an API for scheduling various types of jobs against the framework that will be executed
37 * in your application's own process.
38 * <p>
39 * See {@link android.app.job.JobInfo} for more description of the types of jobs that can be run
40 * and how to construct them. You will construct these JobInfo objects and pass them to the
41 * JobScheduler with {@link #schedule(JobInfo)}. When the criteria declared are met, the
42 * system will execute this job on your application's {@link android.app.job.JobService}.
43 * You identify which JobService is meant to execute the logic for your job when you create the
44 * JobInfo with
45 * {@link android.app.job.JobInfo.Builder#JobInfo.Builder(int,android.content.ComponentName)}.
46 * </p>
47 * <p>
48 * The framework will be intelligent about when you receive your callbacks, and attempt to batch
49 * and defer them as much as possible. Typically if you don't specify a deadline on your job, it
50 * can be run at any moment depending on the current state of the JobScheduler's internal queue,
51 * however it might be deferred as long as until the next time the device is connected to a power
52 * source.
53 * </p>
54 * <p>You do not
55 * instantiate this class directly; instead, retrieve it through
56 * {@link android.content.Context#getSystemService
57 * Context.getSystemService(Context.JOB_SCHEDULER_SERVICE)}.
58 */
59@SystemService(Context.JOB_SCHEDULER_SERVICE)
60public abstract class JobScheduler {
61    /** @hide */
62    @IntDef(prefix = { "RESULT_" }, value = {
63            RESULT_FAILURE,
64            RESULT_SUCCESS,
65    })
66    @Retention(RetentionPolicy.SOURCE)
67    public @interface Result {}
68
69    /**
70     * Returned from {@link #schedule(JobInfo)} when an invalid parameter was supplied. This can occur
71     * if the run-time for your job is too short, or perhaps the system can't resolve the
72     * requisite {@link JobService} in your package.
73     */
74    public static final int RESULT_FAILURE = 0;
75    /**
76     * Returned from {@link #schedule(JobInfo)} if this job has been successfully scheduled.
77     */
78    public static final int RESULT_SUCCESS = 1;
79
80    /**
81     * Schedule a job to be executed.  Will replace any currently scheduled job with the same
82     * ID with the new information in the {@link JobInfo}.  If a job with the given ID is currently
83     * running, it will be stopped.
84     *
85     * @param job The job you wish scheduled. See
86     * {@link android.app.job.JobInfo.Builder JobInfo.Builder} for more detail on the sorts of jobs
87     * you can schedule.
88     * @return the result of the schedule request.
89     */
90    public abstract @Result int schedule(@NonNull JobInfo job);
91
92    /**
93     * Similar to {@link #schedule}, but allows you to enqueue work for a new <em>or existing</em>
94     * job.  If a job with the same ID is already scheduled, it will be replaced with the
95     * new {@link JobInfo}, but any previously enqueued work will remain and be dispatched the
96     * next time it runs.  If a job with the same ID is already running, the new work will be
97     * enqueued for it.
98     *
99     * <p>The work you enqueue is later retrieved through
100     * {@link JobParameters#dequeueWork() JobParameters.dequeueWork}.  Be sure to see there
101     * about how to process work; the act of enqueueing work changes how you should handle the
102     * overall lifecycle of an executing job.</p>
103     *
104     * <p>It is strongly encouraged that you use the same {@link JobInfo} for all work you
105     * enqueue.  This will allow the system to optimally schedule work along with any pending
106     * and/or currently running work.  If the JobInfo changes from the last time the job was
107     * enqueued, the system will need to update the associated JobInfo, which can cause a disruption
108     * in execution.  In particular, this can result in any currently running job that is processing
109     * previous work to be stopped and restarted with the new JobInfo.</p>
110     *
111     * <p>It is recommended that you avoid using
112     * {@link JobInfo.Builder#setExtras(PersistableBundle)} or
113     * {@link JobInfo.Builder#setTransientExtras(Bundle)} with a JobInfo you are using to
114     * enqueue work.  The system will try to compare these extras with the previous JobInfo,
115     * but there are situations where it may get this wrong and count the JobInfo as changing.
116     * (That said, you should be relatively safe with a simple set of consistent data in these
117     * fields.)  You should never use {@link JobInfo.Builder#setClipData(ClipData, int)} with
118     * work you are enqueue, since currently this will always be treated as a different JobInfo,
119     * even if the ClipData contents are exactly the same.</p>
120     *
121     * @param job The job you wish to enqueue work for. See
122     * {@link android.app.job.JobInfo.Builder JobInfo.Builder} for more detail on the sorts of jobs
123     * you can schedule.
124     * @param work New work to enqueue.  This will be available later when the job starts running.
125     * @return the result of the enqueue request.
126     */
127    public abstract @Result int enqueue(@NonNull JobInfo job, @NonNull JobWorkItem work);
128
129    /**
130     *
131     * @param job The job to be scheduled.
132     * @param packageName The package on behalf of which the job is to be scheduled. This will be
133     *                    used to track battery usage and appIdleState.
134     * @param userId    User on behalf of whom this job is to be scheduled.
135     * @param tag Debugging tag for dumps associated with this job (instead of the service class)
136     * @hide
137     */
138    @SystemApi
139    @RequiresPermission(android.Manifest.permission.UPDATE_DEVICE_STATS)
140    public abstract @Result int scheduleAsPackage(@NonNull JobInfo job, @NonNull String packageName,
141            int userId, String tag);
142
143    /**
144     * Cancel a job that is pending in the JobScheduler.
145     * @param jobId unique identifier for this job. Obtain this value from the jobs returned by
146     * {@link #getAllPendingJobs()}.
147     */
148    public abstract void cancel(int jobId);
149
150    /**
151     * Cancel all jobs that have been registered with the JobScheduler by this package.
152     */
153    public abstract void cancelAll();
154
155    /**
156     * Retrieve all jobs for this package that are pending in the JobScheduler.
157     *
158     * @return a list of all the jobs registered by this package that have not
159     *         yet been executed.
160     */
161    public abstract @NonNull List<JobInfo> getAllPendingJobs();
162
163    /**
164     * Retrieve a specific job for this package that is pending in the
165     * JobScheduler.
166     *
167     * @return job registered by this package that has not yet been executed.
168     */
169    public abstract @Nullable JobInfo getPendingJob(int jobId);
170}
171