From 88f9d7935cb3799b6521b82eb6e3299cdd474e8c Mon Sep 17 00:00:00 2001
From: Suprabh Shukla <suprabh@google.com>
Date: Thu, 2 Feb 2023 14:44:45 -0800
Subject: [PATCH] Deprecate unsupported AlarmManager#set System API

This .set system API has many undesirable traits:
1. It accepts an interval, when providing any interval except 0 will
   result in an Exception.
2. It doesn't allow the caller to pass a tag to help identify the
   listener that may be involved in an issue.
3. The window length parameter is redundant as there are already better
   named APIs to use for windowed or exact alarms.
Using WINDOW_HEURISTIC as window length is an internal implementation
detail and its usage is not supported.

Test: atest CtsAlarmManagerTestCases:BasicApiTests

Bug: 141785404
Change-Id: Iaa0e4e914db6cd957885b431b8a1c1175afba13e
---
 .../framework/java/android/app/AlarmManager.java    | 13 ++++++++++++-
 core/api/system-current.txt                         |  2 +-
 2 files changed, 13 insertions(+), 2 deletions(-)

diff --git a/apex/jobscheduler/framework/java/android/app/AlarmManager.java b/apex/jobscheduler/framework/java/android/app/AlarmManager.java
index 7ed4d35b3ccc5..c2a72b7454783 100644
--- a/apex/jobscheduler/framework/java/android/app/AlarmManager.java
+++ b/apex/jobscheduler/framework/java/android/app/AlarmManager.java
@@ -667,7 +667,7 @@ public class AlarmManager {
      * than supplying a PendingIntent to be sent when the alarm time is reached, this variant
      * supplies an {@link OnAlarmListener} instance that will be invoked at that time.
      * <p>
-     * The OnAlarmListener {@link OnAlarmListener#onAlarm() onAlarm()} method will be
+     * The OnAlarmListener's {@link OnAlarmListener#onAlarm() onAlarm()} method will be
      * invoked via the specified target Executor.
      *
      * <p>
@@ -919,8 +919,19 @@ public class AlarmManager {
      * invoked via the specified target Handler, or on the application's main looper
      * if {@code null} is passed as the {@code targetHandler} parameter.
      *
+     * <p>The behavior of this API when {@code windowMillis < 0} is undefined.
+     *
+     * @deprecated Better alternative APIs exist for setting an alarm with this method:
+     * <ul>
+     *     <li>For alarms with {@code windowMillis > 0}, use
+     *     {@link #setWindow(int, long, long, String, Executor, WorkSource, OnAlarmListener)}</li>
+     *     <li>For alarms with {@code windowMillis = 0}, use
+     *     {@link #setExact(int, long, String, Executor, WorkSource, OnAlarmListener)}</li>
+     * </ul>
+     *
      * @hide
      */
+    @Deprecated
     @SystemApi
     @RequiresPermission(android.Manifest.permission.UPDATE_DEVICE_STATS)
     public void set(@AlarmType int type, long triggerAtMillis, long windowMillis,
diff --git a/core/api/system-current.txt b/core/api/system-current.txt
index cf8df97024252..c8f25dfa3e8d7 100644
--- a/core/api/system-current.txt
+++ b/core/api/system-current.txt
@@ -545,7 +545,7 @@ package android.app {
 
   public class AlarmManager {
     method @RequiresPermission(android.Manifest.permission.UPDATE_DEVICE_STATS) public void set(int, long, long, long, @NonNull android.app.PendingIntent, @Nullable android.os.WorkSource);
-    method @RequiresPermission(android.Manifest.permission.UPDATE_DEVICE_STATS) public void set(int, long, long, long, @NonNull android.app.AlarmManager.OnAlarmListener, @Nullable android.os.Handler, @Nullable android.os.WorkSource);
+    method @Deprecated @RequiresPermission(android.Manifest.permission.UPDATE_DEVICE_STATS) public void set(int, long, long, long, @NonNull android.app.AlarmManager.OnAlarmListener, @Nullable android.os.Handler, @Nullable android.os.WorkSource);
     method @RequiresPermission(android.Manifest.permission.UPDATE_DEVICE_STATS) public void setExact(int, long, @Nullable String, @NonNull java.util.concurrent.Executor, @NonNull android.os.WorkSource, @NonNull android.app.AlarmManager.OnAlarmListener);
     method @RequiresPermission(android.Manifest.permission.UPDATE_DEVICE_STATS) public void setExactAndAllowWhileIdle(int, long, @Nullable String, @NonNull java.util.concurrent.Executor, @Nullable android.os.WorkSource, @NonNull android.app.AlarmManager.OnAlarmListener);
     method @RequiresPermission(android.Manifest.permission.SCHEDULE_PRIORITIZED_ALARM) public void setPrioritized(int, long, long, @Nullable String, @NonNull java.util.concurrent.Executor, @NonNull android.app.AlarmManager.OnAlarmListener);