Merge "Docs: Job-scheduling doc for new DAC Performance section." into nyc-dev

1 files changed, 285 insertions, 0 deletions

diff --git a/docs/html/topic/performance/scheduling.jd b/docs/html/topic/performance/scheduling.jd
new file mode 100644
index 000000000000..b6f0fdc1b230
--- /dev/null
+++ b/docs/html/topic/performance/scheduling.jd
@@ -0,0 +1,285 @@
+page.title=Intelligent Job-Scheduling
+@jd:body
+
+<div id="qv-wrapper">
+<div id="qv">
+
+<h2>In this document</h2>
+<ol>
+   <li><a href="#js">Android Framework JobScheduler</a></li>
+   <li><a href="#am">AlarmManager</a></li>
+   <li><a href="#fjd">Firebase JobDispatcher</a></li>
+   <li><a href="#gcmnm">GCM Network Manager</a></li>
+   <li><a href="#af">Additional Facilities</a></li>
+   <ul>
+      <li><a href="#sa">SyncAdapter</a></li>
+      <li><a href="#services">Services</a></li>
+   </ul>
+   <li><a href="#ap">Additional Points</a></li>
+</ol>
+
+</div>
+</div>
+
+<p>
+Modern apps can perform many of their tasks asynchronously, outside the
+direct flow of user interaction. Some examples of these asynchronous tasks are:
+</p>
+
+<ul>
+   <li>Updating network resources.</li>
+   <li>Downloading information.</li>
+   <li>Updating background tasks.</li>
+   <li>Scheduling system service calls.</li>
+</ul>
+
+<p>
+Scheduling this work intelligently can improve your app’s performance,
+along with aspects of system health such as battery life. {@link android.app.job.JobScheduler}
+does this scheduling work for you.
+<p>
+
+<p>
+There are several APIs that your app can use to schedule background work. Chief
+among these options is {@link android.app.job.JobScheduler}.
+The {@link android.app.job.JobScheduler} API allows you to specify robust
+conditions for executing tasks,
+along with centralized task scheduling across the device for optimal
+system health. {@link android.app.job.JobScheduler} also offers highly
+scalable functionality: it is suitable for small tasks like clearing a cache,
+and for large ones such as syncing a database to the cloud.
+<p>
+
+<p>
+In addition to {@link android.app.job.JobScheduler}, there are several other
+facilities available to help your app schedule work. These include:
+</p>
+
+<ul>
+   <li><a href="{@docRoot}reference/android/app/AlarmManager.html">AlarmManager
+   </a></li>
+   <li><a href="https://github.com/firebase/firebase-jobdispatcher-android#user-content-firebase-jobdispatcher-">
+   Firebase JobDispatcher</a></li>
+   <li><a href="https://developers.google.com/cloud-messaging/network-manager">
+   GCM Network Manager</a></li>
+   <li><a href="{@docRoot}reference/android/content/AbstractThreadedSyncAdapter.html">
+   SyncAdapter</a></li>
+   <li><a href="{@docRoot}reference/android/content/AbstractThreadedSyncAdapter.html">
+   Additional Facilities</a></li>
+</ul>
+
+<p>
+This page provides brief introductions to {@link android.app.job.JobScheduler}
+and other APIs that can help your app schedule work to maximize app performance
+and system health.
+</p>
+
+<h2 id="js">Android Framework JobScheduler</h2>
+
+<p>
+{@link android.app.job.JobScheduler} is the Android framework’s native platform
+for scheduling tasks or work. It first became available in Android 5.0 (API
+level 21), and remains under active development. Notably, Android N (API
+level 24) added the ability to trigger jobs based on
+{@link android.content.ContentProvider} changes.
+</p>
+
+<p>
+{@link android.app.job.JobScheduler} is implemented in the platform, which
+allows it to collect information about jobs that need to run across all apps.
+This information is used to schedule jobs to run at, or around, the same time.
+Batching job execution in this fashion allows the device to enter and stay in
+sleep states longer, preserving battery life.
+</p>
+
+<p>
+You use {@link android.app.job.JobScheduler} by registering jobs, specifying
+their requirements for network and timing. The system then gracefully schedules
+the jobs to execute at the appropriate times. At the same time, it also defers
+job execution as necessary to comply with
+<a href="{@docRoot}topic/performance/monitoring-device-state/doze-standby.html">
+Doze and App Standby</a> restrictions.
+{@link android.app.job.JobScheduler} provides many methods to define
+job-execution conditions.
+</p>
+
+<p>
+If your app targets Android 5.0 (API level 21), we recommend that you use the
+{@link android.app.job.JobScheduler} to execute background tasks. For more
+information about {@link android.app.job.JobScheduler}, see its
+<a href="{@docRoot}reference/android/app/job/JobScheduler.html">API-reference
+documentation.</a>
+</p>
+
+<h2 id="am">AlarmManager</h2>
+
+<p>
+The {@link android.app.AlarmManager} API is another option that the framework
+provides for scheduling tasks. This API is useful in cases in which an app
+needs to post a notification or set off an alarm at a very specific time.
+</p>
+
+<p>
+You should only use this API for tasks that must execute at a specific time,
+but do not require the other, more robust, execution conditions that
+{@link android.app.job.JobScheduler} allows you to specify, such as device
+idle and charging detect.
+</p>
+
+<p>
+{@link android.app.AlarmManager} does not honor
+<a href="{@docRoot}topic/performance/monitoring-device-state/doze-standby.html">
+Doze and App Standby</a> restrictions; it runs tasks even during
+<a href="{@docRoot}topic/performance/monitoring-device-state/doze-standby.html">
+Doze or App Standby</a> mode. Additionally,
+an app running during
+<a href="{@docRoot}topic/performance/monitoring-device-state/doze-standby.html">
+Doze or App Standby</a> mode cannot use the network.
+</p>
+
+<h2 id="fjd">Firebase JobDispatcher</h2>
+
+<p>
+<a href="https://github.com/firebase/firebase-jobdispatcher-android#user-content-firebase-jobdispatcher-">
+Firebase JobDispatcher</a> is an open-source library that provides an API similar to
+{@link android.app.job.JobScheduler} in the Android platform.
+<a href="https://github.com/firebase/firebase-jobdispatcher-android#user-content-firebase-jobdispatcher-">
+Firebase JobDispatcher</a> serves as a
+{@link android.app.job.JobScheduler}-compatibility layer for apps targeting
+versions of Android lower than 5.0 (API level 21).
+</p>
+
+<p>
+<a href="https://github.com/firebase/firebase-jobdispatcher-android#user-content-firebase-jobdispatcher-">
+Firebase JobDispatcher</a> supports the use of Google Play services as an
+implementation for dispatching (running) jobs, but the library also allows you
+to define and use other implementations: For example, you might decide to use
+{@link android.app.job.JobScheduler} or write your own, custom code.
+Because of this versatility, we recommend that you use this
+<a href="https://github.com/firebase/firebase-jobdispatcher-android#user-content-firebase-jobdispatcher-">
+Firebase JobDispatcher</a> if your app targets a version of Android lower
+than 5.0 (API level 21).
+</p>
+
+<p>
+For more information about
+<a href="https://github.com/firebase/firebase-jobdispatcher-android#user-content-firebase-jobdispatcher-">
+Firebase JobDispatcher</a>, refer to its
+<a href="https://github.com/firebase/firebase-jobdispatcher-android#user-content-firebase-jobdispatcher-">
+documentation and source code</a>.
+</p>
+
+<h2 id = "gcmnm">GCM Network Manager</h2>
+
+<p>
+<a href="https://developers.google.com/cloud-messaging/network-manager">GCM
+Network Manager</a> is a compatibility port of the Android
+{@link android.app.job.JobScheduler} for apps that support versions of Android
+prior to 5.0 (API level 21). This API has all of the same advantages as
+{@link android.app.job.JobScheduler}. However, it depends on Google Play
+services, which acts like {@link android.app.job.JobScheduler} by taking care
+of cross-app job scheduling to improve battery life. This client library is
+part of the Google Play services GCM client library, but does not require
+that an app use
+<a href="https://developers.google.com/cloud-messaging/">Google Cloud
+Messaging</a>.
+</p>
+
+<p>
+This library is an earlier version of
+<a href="https://github.com/firebase/firebase-jobdispatcher-android#user-content-firebase-jobdispatcher-">
+Firebase JobDispatcher</a>. Forward development on GCM Network Manager has
+stopped; we recommend that you use
+<a href="https://github.com/firebase/firebase-jobdispatcher-android#user-content-firebase-jobdispatcher-">
+Firebase JobDispatcher</a> going forward.
+</p>
+
+<h2 id="af">Additional Facilities</h2>
+
+<p>
+In addition to the APIs and libraries described above, there are also sync
+adapters and services that can enable your app, under specific conditions,
+to perform better and more robustly.
+</p>
+
+<h3 id="sa">SyncAdapter</h3>
+
+<p>
+The framework continues to provide the
+{@link android.content.AbstractThreadedSyncAdapter SyncAdapter} class for
+managing tasks that sync data between the device and a server. Sync adapters are
+designed specifically for syncing data between a device and the cloud; you
+should only use them for this type of task. Sync adapters are more complex to
+implement than the libraries and APIs mentioned above, because they require at
+least a fake
+<a href="{@docRoot}training/sync-adapters/creating-authenticator.html">
+authenticator</a>and
+<a href="{@docRoot}training/sync-adapters/creating-stub-provider.html">
+content provider</a> implementation. For these reasons, you typically should
+not create a sync adapter just to sync data to the cloud in the
+background. Wherever possible, you should instead use
+{@link android.app.job.JobScheduler},
+<a href="https://github.com/firebase/firebase-jobdispatcher-android#user-content-firebase-jobdispatcher-">
+Firebase JobDispatcher</a>, or
+<a href="https://developers.google.com/cloud-messaging/network-manager">GCM
+Network Manager</a> .
+</p>
+
+<p>
+In Android N (API level 24), the {@code SyncManager} sits on top of
+the {@link android.app.job.JobScheduler}. You should only use the
+{@link android.content.AbstractThreadedSyncAdapter SyncAdapter}
+class if you require the additional functionality that it provides.
+</p>
+
+<h3 id="services">Services</h3>
+
+<p>
+The <a href="{@docRoot}guide/components/services.html">Services</a>
+framework allows you to perform long-running operations in the background.
+We recommend foreground services for tasks, such as playing
+music, which need to stay resident for the user. Bound services also continue
+to be useful for various use cases: for example, when a service needs to
+run only when a user is viewing a fragment or activity.
+</p>
+
+<p>
+You should avoid using started services that run perpetually or
+perform periodic work, since they continue to use device resources
+even when they are not performing useful tasks. Instead, you
+should use other solutions that this page describes,
+and that provide native lifecycle management. Use started services
+only as a last resort. The Android platform may not support
+started services in the future.
+</p>
+
+<h2 id="ap">Additional Points</h2>
+
+<p>
+Regardless of the solution you adopt, keep the following points in mind:
+</p>
+
+<ul>
+   <li>Captive Internet Portals, VPNs, and proxies can pose
+   Internet-connectivity detection problems. A library or API may think the
+   Internet is available, but your service may not be accessible. Fail
+   gracefully and reschedule as few of your tasks as possible.</li>
+   <li>Depending on the conditions you assign for running a task, 
+   such as network availability, after the task is triggered, a
+   change may occur so that those conditions are no longer met.
+   In such a case, your operation may fail unexpectedly and repeatedly.
+   For this reason, you
+   should code your background task logic to notice when tasks are failing
+   persistently, and perform exponential back-off to avoid
+   inadvertently over-using resources.</li>
+
+
+
+   <li>Remember to use exponential backoff when rescheduling any work,
+   especially when using {@link android.app.AlarmManager}. If your app uses
+   {@link android.app.job.JobScheduler},
+   <a href="https://developers.google.com/cloud-messaging/network-manager">GCM
+   Network Manager</a>,
+   <a href="https://github.com/firebase/firebase-jobdispatcher-android#user-content-firebase-jobdispatcher-">
+   Firebase JobDispatcher</a>, or sync adapters, exponential backoff is automatically used.</li>
+</ul>