From fbab1fcc18d98fb4ac6fb994203fcce375c23bb0 Mon Sep 17 00:00:00 2001 From: Kweku Adams Date: Tue, 12 Jan 2021 10:27:01 -0800 Subject: [PATCH] Expand JS documentation. 1. Make it clear that "minimum latency" != "run ASAP after latency" 2. Note that deadline constraints are dropped from rescheduled jobs 3. Clarify that jobFinished does not need to be called if onStopJob is called Bug: 19536175 Test: Run `m offline-sdk-docs` and check site at out/target/common/docs/offline-sdk/reference/android/app/job/JobInfo.html Change-Id: I051feb0ebfcb0a24c452a38b91a751bbeef581f8 --- .../framework/java/android/app/job/JobInfo.java | 14 ++++++++++---- .../framework/java/android/app/job/JobService.java | 4 ++++ 2 files changed, 14 insertions(+), 4 deletions(-) diff --git a/apex/jobscheduler/framework/java/android/app/job/JobInfo.java b/apex/jobscheduler/framework/java/android/app/job/JobInfo.java index 17682a5b655a0..52442a66cf1d0 100644 --- a/apex/jobscheduler/framework/java/android/app/job/JobInfo.java +++ b/apex/jobscheduler/framework/java/android/app/job/JobInfo.java @@ -1433,7 +1433,10 @@ public class JobInfo implements Parcelable { } /** - * Specify that this job should be delayed by the provided amount of time. + * Specify that this job should be delayed by the provided amount of time. The job may not + * run the instant the delay has elapsed. JobScheduler will start the job at an + * indeterminate time after the delay has elapsed. + *

* Because it doesn't make sense setting this property on a periodic job, doing so will * throw an {@link java.lang.IllegalArgumentException} when * {@link android.app.job.JobInfo.Builder#build()} is called. @@ -1449,9 +1452,11 @@ public class JobInfo implements Parcelable { /** * Set deadline which is the maximum scheduling latency. The job will be run by this - * deadline even if other requirements are not met. Because it doesn't make sense setting - * this property on a periodic job, doing so will throw an - * {@link java.lang.IllegalArgumentException} when + * deadline even if other requirements (including a delay set through + * {@link #setMinimumLatency(long)}) are not met. + *

+ * Because it doesn't make sense setting this property on a periodic job, doing so will + * throw an {@link java.lang.IllegalArgumentException} when * {@link android.app.job.JobInfo.Builder#build()} is called. * @see JobInfo#getMaxExecutionDelayMillis() */ @@ -1465,6 +1470,7 @@ public class JobInfo implements Parcelable { * Set up the back-off/retry policy. * This defaults to some respectable values: {30 seconds, Exponential}. We cap back-off at * 5hrs. + *

* Note that trying to set a backoff criteria for a job with * {@link #setRequiresDeviceIdle(boolean)} will throw an exception when you call build(). * This is because back-off typically does not make sense for these types of jobs. See diff --git a/apex/jobscheduler/framework/java/android/app/job/JobService.java b/apex/jobscheduler/framework/java/android/app/job/JobService.java index fa7a2d362ffac..c251529ae0b12 100644 --- a/apex/jobscheduler/framework/java/android/app/job/JobService.java +++ b/apex/jobscheduler/framework/java/android/app/job/JobService.java @@ -153,6 +153,10 @@ public abstract class JobService extends Service { * Once this method returns (or times out), the system releases the wakelock that it is holding * on behalf of the job.

* + *

Note: When a job is stopped and rescheduled via this + * method call, the deadline constraint is excluded from the rescheduled job's constraint set. + * The rescheduled job will run again once all remaining constraints are satisfied. + * * @param params The parameters identifying this job, similar to what was supplied to the job in * the {@link #onStartJob(JobParameters)} callback, but with the stop reason * included.