Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit fbab1fcc authored by Kweku Adams's avatar Kweku Adams
Browse files

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
parent 3d121b71

apex/jobscheduler/framework/java/android/app/job/JobInfo.java

+10 −4
Original line number Diff line number Diff line
@@ -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.

         * <p>

         * 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.

         * <p>

         * 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.

         * <p>

         * 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

apex/jobscheduler/framework/java/android/app/job/JobService.java

+4 −0
Original line number Diff line number Diff line
@@ -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.</p>

     *

     * <p class="caution"><strong>Note:</strong> 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.