In Android M+ it is encouraged to use JobScheduler for all background jobs, instead of using things like IntentService or polling using alarms. Using the system API is beneficial as it has a full view of what goes on in the system and can schedule jobs accordingly.
However, this functionality was introduced in Android L, and the API has been very stable since Android M. This means that we also need a similar framework for older versions of Android, which is provided by Google Play services. We prefer system APIs, since they do not require including external libraries which bloats the APK size of Chrome and adds unnecessary complexity. The GcmNetworkManager is only used when the system API is not available.
The background_task_scheduler component provides a new framework for use within chromium to schedule and execute background jobs using the frameworks available on a given version of Android. The public API of the framework is similar to that of the Android JobScheduler, but it is backed by either the system JobScheduler API or by GcmNetworkManager. What service is used to back the framework remains unknown to callers of the API.
A task is defined as a class that implements the BackgroundTask interface, which looks like this:
interface BackgroundTask { interface TaskFinishedCallback { void taskFinished(boolean needsReschedule); } boolean onStartTask(Context context, TaskParameters taskParameters, TaskFinishedCallback callback); boolean onStopTask(Context context, TaskParameters taskParameters); }
Any class implementing this interface must have a public constructor which takes no arguments.
A task must also have a unique ID, and it must be listed in TaskIds to ensure there is no overlap between different tasks.
A task is scheduled by creating an object containing information about the task, such as when to run it, whether it requires battery, and other similar constraints. This object is called TaskInfo and has a builder you can use to set all the relevant fields.
There are two main types of tasks; one-off tasks and periodic tasks. One-off tasks are only executed once, whereas periodic tasks are executed once per a defined interval.
As an example for how to create a one-off task that executes in 200 minutes, you can do the following:
TaskInfo.createOneOffTask(TaskIds.YOUR_FEATURE, MyBackgroundTask.class, TimeUnit.MINUTES.toMillis(200)).build();
For a periodic task that executes every 200 minutes, you can call:
TaskInfo.createPeriodicTask(TaskIds.YOUR_FEATURE, MyBackgroundTask.class, TimeUnit.MINUTES.toMillis(200)).build();
Typically you will also set other required parameters such as what type of network conditions are necessary and whether the task requires the device to be charging. They can be set on the builder like this:
TaskInfo.createOneOffTask(TaskIds.YOUR_FEATURE, MyBackgroundTask.class, TimeUnit.MINUTES.toMillis(100) TimeUnit.MINUTES.toMillis(200)) .setRequiresCharging(true) .setRequiredNetworkType(TaskInfo.NETWORK_TYPE_UNMETERED) .build();
When the task is ready for scheduling, you use the BackgroundTaskSchedulerFactory to get the current instance of the BackgroundTaskScheduler and use it to schedule the job.
BackgroundTaskScheduleFactory.getScheduler().schedule(myTaskInfo);
If you ever need to cancel a task, you can do that by calling cancel, and passing in the task ID:
BackgroundTaskScheduleFactory.getScheduler().cancel(TaskIds.YOUR_FEATURE);
A TaskInfo supports passing in arguments through a Bundle, but only values that can be part of an Android BaseBundle are allowed. You can pass them in using the TaskInfo.Builder:
Bundle myBundle = new Bundle(); myBundle.putString("foo", "bar"); myBundle.putLong("number", 1337L); TaskInfo.createOneOffTask(TaskIds.YOUR_FEATURE, MyBackgroundTask.class, TimeUnit.MINUTES.toMillis(100) TimeUnit.MINUTES.toMillis(200)) .setExtras(myBundle) .build();
These arguments will be readable for the task through the TaskParameters object that is passed to both onStartTask(...) and onStopTask(...), by doing the following:
boolean onStartTask(Context context, TaskParameters taskParameters, TaskFinishedCallback callback) { Bundle myExtras = taskParameters.getExtras(); // Use |myExtras|. ... }
Even though the BackgroundTaskScheduler provides functionality for invoking code while the application is in the background, the BackgroundTask instance is still invoked on the application main thread.
This means that unless the operation is extremely quick, processing must happen asynchronously, and the call to onStartJob(...) must return before the task has finished processing. In that case, onStartJob(...) must return true, and instead invoke the TaskFinishedCallback when the processing is finished, which typically happens on a different Thread, Handler or using an AsyncTask.
If the task finishes while still being on the main thread, onStartJob(...) should return false, indicating that no further processsing is required.
If at any time the constraints given through the TaskInfo object does not hold anymore, or if the system deems it necessary, onStopTask(...) will be invoked, requiring all activity to cease immediately. The task can return true if the task needs to be rescheduled since it was canceled, or false otherwise.
The system will hold a wakelock from the time onStartTask(...) is invoked until either the task itself invokes the TaskFinishedCallback, or onStopTask(...) is invoked.