Un-deprecate setInexactRepeating() and tweak docs

Bug 10461371

Change-Id: Ic62a0e94c83c0c7b50e21a7bee19c3d92255d231

2 files changed, 58 insertions, 39 deletions

diff --git a/api/current.txt b/api/current.txt
index 014e91deca84..ccff70fde1bd 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -3083,18 +3083,18 @@ package android.app {
     method public void cancel(android.app.PendingIntent);
     method public void set(int, long, android.app.PendingIntent);
     method public void setExact(int, long, android.app.PendingIntent);
-    method public deprecated void setInexactRepeating(int, long, long, android.app.PendingIntent);
+    method public void setInexactRepeating(int, long, long, android.app.PendingIntent);
     method public void setRepeating(int, long, long, android.app.PendingIntent);
     method public void setTime(long);
     method public void setTimeZone(java.lang.String);
     method public void setWindow(int, long, long, android.app.PendingIntent);
     field public static final int ELAPSED_REALTIME = 3; // 0x3
     field public static final int ELAPSED_REALTIME_WAKEUP = 2; // 0x2
-    field public static final deprecated long INTERVAL_DAY = 86400000L; // 0x5265c00L
-    field public static final deprecated long INTERVAL_FIFTEEN_MINUTES = 900000L; // 0xdbba0L
-    field public static final deprecated long INTERVAL_HALF_DAY = 43200000L; // 0x2932e00L
-    field public static final deprecated long INTERVAL_HALF_HOUR = 1800000L; // 0x1b7740L
-    field public static final deprecated long INTERVAL_HOUR = 3600000L; // 0x36ee80L
+    field public static final long INTERVAL_DAY = 86400000L; // 0x5265c00L
+    field public static final long INTERVAL_FIFTEEN_MINUTES = 900000L; // 0xdbba0L
+    field public static final long INTERVAL_HALF_DAY = 43200000L; // 0x2932e00L
+    field public static final long INTERVAL_HALF_HOUR = 1800000L; // 0x1b7740L
+    field public static final long INTERVAL_HOUR = 3600000L; // 0x36ee80L
     field public static final int RTC = 1; // 0x1
     field public static final int RTC_WAKEUP = 0; // 0x0
   }
diff --git a/core/java/android/app/AlarmManager.java b/core/java/android/app/AlarmManager.java
index 27b5a5a94860..0cf7ad06a291 100644
--- a/core/java/android/app/AlarmManager.java
+++ b/core/java/android/app/AlarmManager.java
@@ -48,6 +48,15 @@ import android.os.WorkSource;
  * etc) it is easier and much more efficient to use
  * {@link android.os.Handler}.</b>
  *
+ * <p class="caution"><strong>Note:</strong> Beginning with API 19
+ * ({@link android.os.Build.VERSION_CODES#KITKAT}) alarm delivery is inexact:
+ * the OS will shift alarms in order to minimize wakeups and battery use.  There are
+ * new APIs to support applications which need strict delivery guarantees; see
+ * {@link #setWindow(int, long, long, PendingIntent)} and
+ * {@link #setExact(int, long, PendingIntent)}.  Applications whose {@code targetSdkVersion}
+ * is earlier than API 19 will continue to see the previous behavior in which all
+ * alarms are delivered exactly when requested.
+ *
  * <p>You do not
  * instantiate this class directly; instead, retrieve it through
  * {@link android.content.Context#getSystemService
@@ -132,6 +141,7 @@ public class AlarmManager
      * broadcast.  Recurring alarms that have gone undelivered because the
      * phone was asleep may have a count greater than one when delivered.  
      *
+     * <div class="note">
      * <p>
      * <b>Note:</b> Beginning in API 19, the trigger time passed to this method
      * is treated as inexact: the alarm will not be delivered before this time, but
@@ -144,16 +154,17 @@ public class AlarmManager
      * <p>
      * With the new batching policy, delivery ordering guarantees are not as
      * strong as they were previously.  If the application sets multiple alarms,
-     * it is possible that these alarms' <i>actual</i> delivery ordering may not match
-     * the order of their <i>requested</i> delivery times.  If your application has
+     * it is possible that these alarms' <em>actual</em> delivery ordering may not match
+     * the order of their <em>requested</em> delivery times.  If your application has
      * strong ordering requirements there are other APIs that you can use to get
      * the necessary behavior; see {@link #setWindow(int, long, long, PendingIntent)}
      * and {@link #setExact(int, long, PendingIntent)}.
      *
      * <p>
-     * <b>Note:</b> Applications whose targetSdkVersion is before API 19 will
+     * Applications whose {@code targetSdkVersion} is before API 19 will
      * continue to get the previous alarm behavior: all of their scheduled alarms
      * will be treated as exact.
+     * </div>
      *
      * @param type One of {@link #ELAPSED_REALTIME}, {@link #ELAPSED_REALTIME_WAKEUP},
      *        {@link #RTC}, or {@link #RTC_WAKEUP}.
@@ -206,11 +217,11 @@ public class AlarmManager
      * between alarms, then the approach to take is to use one-time alarms, 
      * scheduling the next one yourself when handling each alarm delivery.
      *
-     * <p>
+     * <p class="note">
      * <b>Note:</b> as of API 19, all repeating alarms are inexact.  If your
      * application needs precise delivery times then it must use one-time
      * exact alarms, rescheduling each time as described above. Legacy applications
-     * whose targetSdkVersion is earlier than API 19 will continue to have all
+     * whose {@code targetSdkVersion} is earlier than API 19 will continue to have all
      * of their alarms, including repeating alarms, treated as exact.
      *
      * @param type One of {@link #ELAPSED_REALTIME}, {@link #ELAPSED_REALTIME_WAKEUP},
@@ -250,18 +261,19 @@ public class AlarmManager
      * modest timeliness requirements for its alarms.
      *
      * <p>
-     * This method can also be used to achieve strict ordering guarantees by ensuring
-     * that the windows requested for each alarm do not intersect.
+     * This method can also be used to achieve strict ordering guarantees among
+     * multiple alarms by ensuring that the windows requested for each alarm do
+     * not intersect.
      *
      * <p>
      * When precise delivery is not required, applications should use the standard
      * {@link #set(int, long, PendingIntent)} method.  This will give the OS the most
-     * ability to minimize wakeups and battery use.  For alarms that must be delivered
+     * flexibility to minimize wakeups and battery use.  For alarms that must be delivered
      * at precisely-specified times with no acceptable variation, applications can use
      * {@link #setExact(int, long, PendingIntent)}.
      *
      * @param type One of {@link #ELAPSED_REALTIME}, {@link #ELAPSED_REALTIME_WAKEUP},
-     *        {@link #RTC}, or {@link #RTC_WAKEUP
+     *        {@link #RTC}, or {@link #RTC_WAKEUP}.
      * @param windowStartMillis The earliest time, in milliseconds, that the alarm should
      *        be delivered, expressed in the appropriate clock's units (depending on the alarm
      *        type).
@@ -355,54 +367,62 @@ public class AlarmManager
     }
 
     /**
-     * @deprecated setInexactRepeating() is deprecated; as of API 19 all
-     * repeating alarms are inexact.
+     * Available inexact recurrence interval recognized by
+     * {@link #setInexactRepeating(int, long, long, PendingIntent)}
+     * when running on Android prior to API 19.
      */
-    @Deprecated
     public static final long INTERVAL_FIFTEEN_MINUTES = 15 * 60 * 1000;
 
     /**
-     * @deprecated setInexactRepeating() is deprecated; as of API 19 all
-     * repeating alarms are inexact.
+     * Available inexact recurrence interval recognized by
+     * {@link #setInexactRepeating(int, long, long, PendingIntent)}
+     * when running on Android prior to API 19.
      */
-    @Deprecated
     public static final long INTERVAL_HALF_HOUR = 2*INTERVAL_FIFTEEN_MINUTES;
 
     /**
-     * @deprecated setInexactRepeating() is deprecated; as of API 19 all
-     * repeating alarms are inexact.
+     * Available inexact recurrence interval recognized by
+     * {@link #setInexactRepeating(int, long, long, PendingIntent)}
+     * when running on Android prior to API 19.
      */
-    @Deprecated
     public static final long INTERVAL_HOUR = 2*INTERVAL_HALF_HOUR;
 
     /**
-     * @deprecated setInexactRepeating() is deprecated; as of API 19 all
-     * repeating alarms are inexact.
+     * Available inexact recurrence interval recognized by
+     * {@link #setInexactRepeating(int, long, long, PendingIntent)}
+     * when running on Android prior to API 19.
      */
-    @Deprecated
     public static final long INTERVAL_HALF_DAY = 12*INTERVAL_HOUR;
 
     /**
-     * @deprecated setInexactRepeating() is deprecated; as of API 19 all
-     * repeating alarms are inexact.
+     * Available inexact recurrence interval recognized by
+     * {@link #setInexactRepeating(int, long, long, PendingIntent)}
+     * when running on Android prior to API 19.
      */
-    @Deprecated
     public static final long INTERVAL_DAY = 2*INTERVAL_HALF_DAY;
 
     /**
      * Schedule a repeating alarm that has inexact trigger time requirements;
      * for example, an alarm that repeats every hour, but not necessarily at
      * the top of every hour.  These alarms are more power-efficient than
-     * the strict recurrences supplied by {@link #setRepeating}, since the
-     * system can adjust alarms' phase to cause them to fire simultaneously,
+     * the strict recurrences traditionally supplied by {@link #setRepeating}, since the
+     * system can adjust alarms' delivery times to cause them to fire simultaneously,
      * avoiding waking the device from sleep more than necessary.
-     * 
+     *
      * <p>Your alarm's first trigger will not be before the requested time,
      * but it might not occur for almost a full interval after that time.  In
      * addition, while the overall period of the repeating alarm will be as
      * requested, the time between any two successive firings of the alarm
      * may vary.  If your application demands very low jitter, use
-     * {@link #setRepeating} instead.
+     * one-shot alarms with an appropriate window instead; see {@link
+     * #setWindow(int, long, long, PendingIntent)} and
+     * {@link #setExact(int, long, PendingIntent)}.
+     *
+     * <p class="note">
+     * As of API 19, all repeating alarms are inexact.  Because this method has
+     * been available since API 3, your application can safely call it and be
+     * assured that it will get similar behavior on both current and older versions
+     * of Android.
      *
      * @param type One of {@link #ELAPSED_REALTIME}, {@link #ELAPSED_REALTIME_WAKEUP},
      *        {@link #RTC}, or {@link #RTC_WAKEUP}.
@@ -412,17 +432,17 @@ public class AlarmManager
      * delay of almost an entire alarm interval before the first invocation of
      * the alarm.
      * @param intervalMillis interval in milliseconds between subsequent repeats
-     * of the alarm.  If this is one of INTERVAL_FIFTEEN_MINUTES,
+     * of the alarm.  Prior to API 19, if this is one of INTERVAL_FIFTEEN_MINUTES,
      * INTERVAL_HALF_HOUR, INTERVAL_HOUR, INTERVAL_HALF_DAY, or INTERVAL_DAY
      * then the alarm will be phase-aligned with other alarms to reduce the
      * number of wakeups.  Otherwise, the alarm will be set as though the
-     * application had called {@link #setRepeating}.
+     * application had called {@link #setRepeating}.  As of API 19, all repeating
+     * alarms will be inexact and subject to batching with other alarms regardless
+     * of their stated repeat interval.
      * @param operation Action to perform when the alarm goes off;
      * typically comes from {@link PendingIntent#getBroadcast
      * IntentSender.getBroadcast()}.
      *
-     * @deprecated As of API 19, all repeating alarms are inexact.
-     *
      * @see android.os.Handler
      * @see #set
      * @see #cancel
@@ -439,7 +459,6 @@ public class AlarmManager
      * @see #INTERVAL_HALF_DAY
      * @see #INTERVAL_DAY
      */
-    @Deprecated
     public void setInexactRepeating(int type, long triggerAtMillis,
             long intervalMillis, PendingIntent operation) {
         setImpl(type, triggerAtMillis, WINDOW_HEURISTIC, intervalMillis, operation, null);