Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Un-deprecate setInexactRepeating() and tweak docs

Browse Source 
Bug 10461371

Change-Id: Ic62a0e94c83c0c7b50e21a7bee19c3d92255d231
This commit is contained in:
Christopher Tate
2013-10-25 16:14:38 -07:00
parent c802a66140
commit 109e4db471
2 changed files with 58 additions and 39 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
api/current.txt
View File

@@ -3084,18 +3084,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
}

85
core/java/android/app/AlarmManager.java
View File

@@ -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);