* See {@link android.app.job.JobInfo} for more description of the types of jobs that can be run * and how to construct them. You will construct these JobInfo objects and pass them to the * JobScheduler with {@link #schedule(JobInfo)}. When the criteria declared are met, the * system will execute this job on your application's {@link android.app.job.JobService}. * You identify the service component that implements the logic for your job when you * construct the JobInfo using * {@link android.app.job.JobInfo.Builder#Builder(int,android.content.ComponentName)}. *
** The framework will be intelligent about when it executes jobs, and attempt to batch * and defer them as much as possible. Typically, if you don't specify a deadline on a job, it * can be run at any moment depending on the current state of the JobScheduler's internal queue. *
** Starting in Android version {@link android.os.Build.VERSION_CODES#UPSIDE_DOWN_CAKE}, * JobScheduler may try to optimize job execution by shifting execution to times with more available * system resources in order to lower user impact. Factors in system health include sufficient * battery, idle, charging, and access to an un-metered network. Jobs will initially be treated as * if they have all these requirements, but as their deadlines approach, restrictions will become * less strict. Requested requirements will not be affected by this change. *
* * {@see android.app.job.JobInfo.Builder#setRequiresBatteryNotLow(boolean)} * {@see android.app.job.JobInfo.Builder#setRequiresDeviceIdle(boolean)} * {@see android.app.job.JobInfo.Builder#setRequiresCharging(boolean)} * {@see android.app.job.JobInfo.Builder#setRequiredNetworkType(int)} * ** While a job is running, the system holds a wakelock on behalf of your app. For this reason, * you do not need to take any action to guarantee that the device stays awake for the * duration of the job. *
*You do not * instantiate this class directly; instead, retrieve it through * {@link android.content.Context#getSystemService * Context.getSystemService(Context.JOB_SCHEDULER_SERVICE)}. * *
Prior to Android version {@link android.os.Build.VERSION_CODES#S}, jobs could only have * a maximum of 100 jobs scheduled at a time. Starting with Android version * {@link android.os.Build.VERSION_CODES#S}, that limit has been increased to 150. * Expedited jobs also count towards the limit. * *
In Android version {@link android.os.Build.VERSION_CODES#LOLLIPOP}, jobs had a maximum * execution time of one minute. Starting with Android version * {@link android.os.Build.VERSION_CODES#M} and ending with Android version * {@link android.os.Build.VERSION_CODES#R}, jobs had a maximum execution time of 10 minutes. * Starting from Android version {@link android.os.Build.VERSION_CODES#S}, jobs will still be * stopped after 10 minutes if the system is busy or needs the resources, but if not, jobs * may continue running longer than 10 minutes. * *
Note: Beginning with API 30 * ({@link android.os.Build.VERSION_CODES#R}), JobScheduler will throttle runaway applications. * Calling {@link #schedule(JobInfo)} and other such methods with very high frequency can have a * high cost and so, to make sure the system doesn't get overwhelmed, JobScheduler will begin * to throttle apps, regardless of target SDK version. */ @SystemService(Context.JOB_SCHEDULER_SERVICE) public abstract class JobScheduler { /** * Whether to throw an exception when an app doesn't properly implement all the necessary * data transfer APIs. * * @hide */ @ChangeId @EnabledAfter(targetSdkVersion = Build.VERSION_CODES.TIRAMISU) public static final long THROW_ON_INVALID_DATA_TRANSFER_IMPLEMENTATION = 255371817L; /** @hide */ @IntDef(prefix = { "RESULT_" }, value = { RESULT_FAILURE, RESULT_SUCCESS, }) @Retention(RetentionPolicy.SOURCE) public @interface Result {} /** * Returned from {@link #schedule(JobInfo)} if a job wasn't scheduled successfully. Scheduling * can fail for a variety of reasons, including, but not limited to: *
Since leading and trailing whitespace can lead to hard-to-debug issues, * they will be {@link String#trim() trimmed}. An empty String (after trimming) is not allowed. * @see #getNamespace() */ @NonNull public JobScheduler forNamespace(@NonNull String namespace) { throw new RuntimeException("Not implemented. Must override in a subclass."); } /** * Get the namespace this JobScheduler instance is operating in. A {@code null} value means * that the app has not specified a namespace for this instance, and it is therefore using the * default namespace. */ @Nullable public String getNamespace() { throw new RuntimeException("Not implemented. Must override in a subclass."); } /** @hide */ @Nullable public static String sanitizeNamespace(@Nullable String namespace) { if (namespace == null) { return null; } return namespace.trim().intern(); } /** * Schedule a job to be executed. Will replace any currently scheduled job with the same * ID with the new information in the {@link JobInfo}. If a job with the given ID is currently * running, it will be stopped. * *
Note: Scheduling a job can have a high cost, even if it's * rescheduling the same job and the job didn't execute, especially on platform versions before * version {@link android.os.Build.VERSION_CODES#Q}. As such, the system may throttle calls to * this API if calls are made too frequently in a short amount of time. * *
Note: The JobService component needs to be enabled in order to successfully schedule a * job. * * @param job The job you wish scheduled. See * {@link android.app.job.JobInfo.Builder JobInfo.Builder} for more detail on the sorts of jobs * you can schedule. * @return the result of the schedule request. * @throws IllegalArgumentException if the specified {@link JobService} doesn't exist or is * disabled. */ public abstract @Result int schedule(@NonNull JobInfo job); /** * Similar to {@link #schedule}, but allows you to enqueue work for a new or existing * job. If a job with the same ID is already scheduled, it will be replaced with the * new {@link JobInfo}, but any previously enqueued work will remain and be dispatched the * next time it runs. If a job with the same ID is already running, the new work will be * enqueued for it without stopping the job. * *
The work you enqueue is later retrieved through * {@link JobParameters#dequeueWork() JobParameters.dequeueWork}. Be sure to see there * about how to process work; the act of enqueueing work changes how you should handle the * overall lifecycle of an executing job.
* *It is strongly encouraged that you use the same {@link JobInfo} for all work you * enqueue. This will allow the system to optimally schedule work along with any pending * and/or currently running work. If the JobInfo changes from the last time the job was * enqueued, the system will need to update the associated JobInfo, which can cause a disruption * in execution. In particular, this can result in any currently running job that is processing * previous work to be stopped and restarted with the new JobInfo.
* *It is recommended that you avoid using * {@link JobInfo.Builder#setExtras(PersistableBundle)} or * {@link JobInfo.Builder#setTransientExtras(Bundle)} with a JobInfo you are using to * enqueue work. The system will try to compare these extras with the previous JobInfo, * but there are situations where it may get this wrong and count the JobInfo as changing. * (That said, you should be relatively safe with a simple set of consistent data in these * fields.) You should never use {@link JobInfo.Builder#setClipData(ClipData, int)} with * work you are enqueuing, since currently this will always be treated as a different JobInfo, * even if the ClipData contents are exactly the same.
* *Note: Scheduling a job can have a high cost, even if it's * rescheduling the same job and the job didn't execute, especially on platform versions before * version {@link android.os.Build.VERSION_CODES#Q}. As such, the system may throttle calls to * this API if calls are made too frequently in a short amount of time. * *
Note: Prior to Android version * {@link android.os.Build.VERSION_CODES#UPSIDE_DOWN_CAKE}, JobWorkItems could not be persisted. * Apps were not allowed to enqueue JobWorkItems with persisted jobs and the system would throw * an {@link IllegalArgumentException} if they attempted to do so. Starting with * {@link android.os.Build.VERSION_CODES#UPSIDE_DOWN_CAKE}, * JobWorkItems can be persisted alongside the hosting job. * However, Intents cannot be persisted. Set a {@link PersistableBundle} using * {@link JobWorkItem.Builder#setExtras(PersistableBundle)} for any information that needs * to be persisted. * *
Note: The JobService component needs to be enabled in order to successfully schedule a * job. * * @param job The job you wish to enqueue work for. See * {@link android.app.job.JobInfo.Builder JobInfo.Builder} for more detail on the sorts of jobs * you can schedule. * @param work New work to enqueue. This will be available later when the job starts running. * @return the result of the enqueue request. * @throws IllegalArgumentException if the specified {@link JobService} doesn't exist or is * disabled. */ public abstract @Result int enqueue(@NonNull JobInfo job, @NonNull JobWorkItem work); /** * * @param job The job to be scheduled. * @param packageName The package on behalf of which the job is to be scheduled. This will be * used to track battery usage and appIdleState. * @param userId User on behalf of whom this job is to be scheduled. * @param tag Debugging tag for dumps associated with this job (instead of the service class) * @hide */ @SuppressWarnings("HiddenAbstractMethod") @SystemApi @RequiresPermission(android.Manifest.permission.UPDATE_DEVICE_STATS) public abstract @Result int scheduleAsPackage(@NonNull JobInfo job, @NonNull String packageName, int userId, String tag); /** * Cancel the specified job. If the job is currently executing, it is stopped * immediately and the return value from its {@link JobService#onStopJob(JobParameters)} * method is ignored. * * @param jobId unique identifier for the job to be canceled, as supplied to * {@link JobInfo.Builder#Builder(int, android.content.ComponentName) * JobInfo.Builder(int, android.content.ComponentName)}. */ public abstract void cancel(int jobId); /** * Cancel all jobs that have been scheduled in the current namespace by the * calling application. * *
* Starting with Android version {@link android.os.Build.VERSION_CODES#UPSIDE_DOWN_CAKE}, this
* will only cancel within the current namespace. If a namespace hasn't been explicitly set
* with {@link #forNamespace(String)}, then this will cancel jobs in the default namespace.
* To cancel all jobs scheduled by the application,
* use {@link #cancelInAllNamespaces()} instead.
*/
public abstract void cancelAll();
/**
* Cancel all jobs that have been scheduled by the calling application, regardless of
* namespace.
*/
public void cancelInAllNamespaces() {
throw new RuntimeException("Not implemented. Must override in a subclass.");
}
/**
* Retrieve all jobs that have been scheduled by the calling application.
*
* @return a list of all of the app's scheduled jobs. This includes jobs that are
* currently started as well as those that are still waiting to run.
*/
public abstract @NonNull List This is a slow operation, so it should be called sparingly.
* @hide
*/
@Nullable
public List