Deprecate CellLocation#requestLocationUpdate

Remove this method, which is undesirable, has unfortunate
side effects, and which is a worse way of getting the current
location than other methods such as TelephonyManager#getAllCellInfo()
(since KK) and TelephonyManager#requestCellInfoUpdate() (since QT/11).

Bug: 152648516
Test: make update-api && make (docstring-only change)
Change-Id: I3c7d345abcdd8c35cf539d33166ddf76ba987b1c

3 files changed, 9 insertions, 2 deletions

diff --git a/api/current.txt b/api/current.txt
index fea1f2f4cac4..f1338f07f294 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -45143,7 +45143,7 @@ package android.telephony {
   public abstract class CellLocation {
     ctor public CellLocation();
     method public static android.telephony.CellLocation getEmpty();
-    method public static void requestLocationUpdate();
+    method @Deprecated public static void requestLocationUpdate();
   }
 
   public abstract class CellSignalStrength {
diff --git a/non-updatable-api/current.txt b/non-updatable-api/current.txt
index 3ad076f60c08..a28569297832 100644
--- a/non-updatable-api/current.txt
+++ b/non-updatable-api/current.txt
@@ -44999,7 +44999,7 @@ package android.telephony {
   public abstract class CellLocation {
     ctor public CellLocation();
     method public static android.telephony.CellLocation getEmpty();
-    method public static void requestLocationUpdate();
+    method @Deprecated public static void requestLocationUpdate();
   }
 
   public abstract class CellSignalStrength {
diff --git a/telephony/java/android/telephony/CellLocation.java b/telephony/java/android/telephony/CellLocation.java
index b32f456581ab..61f68ce32287 100644
--- a/telephony/java/android/telephony/CellLocation.java
+++ b/telephony/java/android/telephony/CellLocation.java
@@ -47,7 +47,14 @@ public abstract class CellLocation {
      *
      * Callers wishing to request a single location update should use
      * {@link TelephonyManager#requestCellInfoUpdate}.
+     *
+     * @deprecated this method has undesirable side-effects, and it calls into the OS without
+     * access to a {@link android.content.Context Context}, meaning that certain safety checks and
+     * attribution are error-prone. Given that this method has numerous downsides, and given that
+     * there are long-available superior alternatives, callers are strongly discouraged from using
+     * this method.
      */
+    @Deprecated
     public static void requestLocationUpdate() {
         // Since this object doesn't have a context, this is the best we can do.
         final Context appContext = ActivityThread.currentApplication();