From 49f93486a909e222f901841321862965442e5286 Mon Sep 17 00:00:00 2001 From: Katie McCormick Date: Fri, 7 Feb 2014 14:33:10 -0800 Subject: Doc update: clarify best practices. Fix for: b/12515292 Change-Id: I1616d41c052582ff6c82b87cd0282cf1d25bb84d --- docs/html/training/scheduling/alarms.jd | 113 +++++++++++++++++++++++++------- 1 file changed, 89 insertions(+), 24 deletions(-) diff --git a/docs/html/training/scheduling/alarms.jd b/docs/html/training/scheduling/alarms.jd index 758dc95..8373d95 100644 --- a/docs/html/training/scheduling/alarms.jd +++ b/docs/html/training/scheduling/alarms.jd @@ -12,6 +12,7 @@ trainingnavtop=true

This lesson teaches you to

    +
  1. Understand the Trade-offs
  2. Set a Repeating Alarm
  3. Cancel an Alarm
  4. Start an Alarm When the Device Boots
    5. @@ -28,6 +29,21 @@ class="button">Download the sample + +
    +

    Video

    +

    The App Clinic: Cricket

    +
    +     + + +
    +

    Video

    +

    DevBytes: Efficient Data Transfers

    +
    +     +

    Alarms (based on the {@link android.app.AlarmManager} class) give you a way to perform time-based operations outside the lifetime of your application. For example, you could use an alarm to initiate a long-running operation, such @@ -55,6 +71,76 @@ instead consider using the {@link android.os.Handler} class in conjunction with {@link java.util.Timer} and {@link java.lang.Thread}. This approach gives Android better control over system resources.

    +

    Understand the Trade-offs

    + +

    A repeating alarm is a relatively simple mechanism with limited flexibility. +It may +not be the best choice for your app, particularly if you need to trigger network +operations. A poorly designed alarm can cause battery drain and put a significant load on +servers.

    + +

    A common scenario for triggering an operation outside the lifetime of your app is +syncing data with a server. This is a case where you might be tempted to use a +repeating alarm. But if you own the server that is hosting your app's +data, using Google Cloud Messaging (GCM) +in conjunction with sync adapter +is a better solution than {@link android.app.AlarmManager}. A sync adapter gives you all +the same scheduling options as {@link android.app.AlarmManager}, but it offers +you significantly more flexibility. For example, +a sync could be based on a "new data" message from the server/device (see +Running a Sync +Adapter for details), the user's activity (or inactivity), the time of day, and so on. +See the linked videos at the top of this page for a detailed discussion of when and how +to use GCM and sync adapter.

    + +

    Best practices

    + +

    Every choice you make in designing your repeating alarm can have consequences in how your +app uses (or abuses) system resources. For example, imagine a popular app that +syncs with a server. If the sync operation is based on clock time and every instance of the +app syncs at 11:00 p.m., the load on the server could result in high latency or even +"denial of service." Follow these best practices in using alarms:

    + + + +

    Set a Repeating Alarm

    As described above, repeating alarms are a good choice for scheduling regular events or @@ -69,29 +155,6 @@ immediately. that uses the same pending intent, it replaces the original alarm. -

    Every choice you make in designing your repeating alarm can have consequences in how your -app uses (or abuses) system resources. Even a carefully managed alarm can have a major impact -on battery life. Follow these guidelines as you design your app:

    - -

    Choose an alarm type

    @@ -119,7 +182,9 @@ hour), use one of the elapsed real time types. In general, this is the better ch

    If you need your alarm to fire at a particular time of day, then choose one of the clock-based real time clock types. Note, however, that this approach can have some drawbacks—the app may not translate well to other locales, and if the user -changes the device's time setting, it could cause unexpected behavior in your app.

    +changes the device's time setting, it could cause unexpected behavior in your app. Using a +real time clock alarm type also does not scale well, as discussed above. We recommend +that you use a "elapsed real time" alarm if you can.

    Here is the list of types:

    -- cgit v1.1