Un-deprecate setInexactRepeating() and tweak docs
Bug 10461371
Change-Id: Ic62a0e94c83c0c7b50e21a7bee19c3d92255d231
diff --git a/api/current.txt b/api/current.txt
index 078ed53..8e69592 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -3084,18 +3084,18 @@
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 27b5a5a9..0cf7ad0 100644
--- a/core/java/android/app/AlarmManager.java
+++ b/core/java/android/app/AlarmManager.java
@@ -48,6 +48,15 @@
* 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 @@
* 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 @@
* <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 @@
* 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 @@
* 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 @@
}
/**
- * @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 @@
* 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 @@
* @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);
