[android] Add JobScheduler-based BackgroundTaskScheduler.

components/background_task_scheduler/android/java/src/org/chromium/components/background_task_scheduler/BackgroundTask.java

+// Copyright 2017 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+package org.chromium.components.background_task_scheduler;
+
+import android.content.Context;
+import android.support.annotation.AnyThread;
+import android.support.annotation.MainThread;
+
+/**
+ * Entry point for callbacks from {@link BackgroundTaskScheduler}. Any classes implementing
+ * this interface must have a public which takes no arguments.

[David Trainor- moved to gerrit, 2017/02/24 07:19:48]

the word constructor should be in here somewhere :)

[nyquist, 2017/02/24 23:41:11]

:-p Done.

+ * The callbacks will be executed on the main thread, which means that execution logic must be
+ * offloaded to another {@link Thread}, {@link android.os.Handler} or {@link android.os.AsyncTask}.
+ */
+public interface BackgroundTask {
+    /**
+     * Callback to invoke whenever background processing has finished after first returning true
+     * from {@link #onStartTask(Context, TaskParameters, TaskFinishedCallback)}.
+     */
+    interface TaskFinishedCallback {
+        /**
+         * Callback to inform the {@link BackgroundTaskScheduler} that the background processing
+         * now has finished. When this callback is invoked, the system will stop holding a wakelock.
+         * @param needsReSchedule whether this task must be rescheduled.

[David Trainor- moved to gerrit, 2017/02/24 07:19:48]

ReSchedule -> Reschedule everywhere?

[nyquist, 2017/02/24 23:41:11]

Done.

+         */
+        @AnyThread
+        void taskFinished(boolean needsReSchedule);
+    }
+
+    /**
+     * Callback from {@link BackgroundTaskScheduler} when your task should start processing.
+     * It is invoked on the main thread, and if your task finishes quickly, you should return false
+     * from this method when you are done processing. If this is a long-running task, you should
+     * return true from this method, and instead invoke the {@link TaskFinishedCallback} when the
+     * processing is finished on some other {@link Thread}, {@link android.os.Handler} or
+     * {@link android.os.AsyncTask}. While this method is running the system holds a wakelock. If
+     * false is returned from this method, the wakelock is immediately released, but if this method
+     * returns true, the wakelock is not released until either the {@link TaskFinishedCallback} is
+     * invoked, or the system calls {@link #onStopTask(Context, TaskParameters)}.
+     * @param context the current context.

[Peter Beverloo, 2017/02/24 18:07:09]

micro nit: A blank line between the documentation paragraph and the parameters
would help readability a lot.

[nyquist, 2017/02/24 23:41:11]

Very much agreed. Followed through for everything in this CL.

+     * @param taskParameters the data passed in as {@link TaskInfo} when the task was scheduled.
+     * @param callback if the task needs to continue processing after returning from the call to
+     *                 {@link #onStartTask(Context, TaskParameters, TaskFinishedCallback)}, this
+     *                 callback must be invoked when the processing has finished.
+     * @return true if the task needs to continue processing work. False if there is no more work.
+     * @see TaskInfo
+     */
+    @MainThread
+    boolean onStartTask(
+            Context context, TaskParameters taskParameters, TaskFinishedCallback callback);
+
+    /**
+     * Callback from {@link BackgroundTaskScheduler} when the system has determined that the
+     * execution of the task must stop immediately, even before the {@link TaskFinishedCallback}
+     * has been invoked. This will typically happen whenever the required conditions for the task
+     * are no longer met. See {@link TaskInfo}. A wakelock is held by the system while this callback
+     * is invoked, and immediately released after this method returns.
+     * @param context the current context.
+     * @param taskParameters the data passed in as {@link TaskInfo} when the task was scheduled.
+     * @return true if the task needs to be rescheduled according to the rescheduling criteria
+     * specified when the task was scheduled initially. False if the taskshould not be rescheduled.
+     * Regardless of the value returned, your task must stop executing.
+     * @see TaskInfo
+     */
+    @MainThread
+    boolean onStopTask(Context context, TaskParameters taskParameters);
+}