Merge SP1A.210425.001

Change-Id: I8d45e47c131320cac5e794fd629fdef84dd3bcfc

3 files changed, 93 insertions, 75 deletions

diff --git a/location/java/android/location/Geocoder.java b/location/java/android/location/Geocoder.java
index 307fb8783c51..51586d708018 100644
--- a/location/java/android/location/Geocoder.java
+++ b/location/java/android/location/Geocoder.java
@@ -45,6 +45,10 @@ import java.util.concurrent.TimeUnit;
  * empty list if there no backend service in the platform.  Use the
  * isPresent() method to determine whether a Geocoder implementation
  * exists.
+ *
+ * <p class="note"><strong>Warning:</strong> Geocoding services may provide no guarantees on
+ * availability or accuracy. Results are a best guess, and are not guaranteed to be meaningful or
+ * correct. Do not use this API for any safety-critical or regulatory compliance purpose.
  */
 public final class Geocoder {
 
@@ -95,15 +99,15 @@ public final class Geocoder {
     }
 
     /**
-     * Returns an array of Addresses that are known to describe the
-     * area immediately surrounding the given latitude and longitude.
-     * The returned addresses will be localized for the locale
-     * provided to this class's constructor.
+     * Returns an array of Addresses that attempt to describe the area immediately surrounding the
+     * given latitude and longitude. The returned addresses should be localized for the locale
+     * provided to this class's constructor. Results may be obtained by means of a network lookup
+     * and this method may take some time to return, and so should not be called on the main thread.
      *
-     * <p> The returned values may be obtained by means of a network lookup.
-     * The results are a best guess and are not guaranteed to be meaningful or
-     * correct. It may be useful to call this method from a thread separate from your
-     * primary UI thread.
+     * <p class="note"><strong>Warning:</strong> Geocoding services may provide no guarantees on
+     * availability or accuracy. Results are a best guess, and are not guaranteed to be meaningful
+     * or correct. Do <b>NOT</b> use this API for any safety-critical or regulatory compliance
+     * purposes.
      *
      * @param latitude the latitude a point for the search
      * @param longitude the longitude a point for the search
@@ -134,17 +138,17 @@ public final class Geocoder {
     }
 
     /**
-     * Returns an array of Addresses that are known to describe the
-     * named location, which may be a place name such as "Dalvik,
-     * Iceland", an address such as "1600 Amphitheatre Parkway,
-     * Mountain View, CA", an airport code such as "SFO", etc..  The
-     * returned addresses will be localized for the locale provided to
-     * this class's constructor.
-     *
-     * <p> The query will block and returned values will be obtained by means of a network lookup.
-     * The results are a best guess and are not guaranteed to be meaningful or
-     * correct. It may be useful to call this method from a thread separate from your
-     * primary UI thread.
+     * Returns an array of Addresses that attempt to describe the named location, which may be a
+     * place name such as "Dalvik, Iceland", an address such as "1600 Amphitheatre Parkway, Mountain
+     * View, CA", an airport code such as "SFO", and so forth. The returned addresses should be
+     * localized for the locale provided to this class's constructor. Results may be obtained by
+     * means of a network lookup and this method may take some time to return, and so should not be
+     * called on the main thread.
+     *
+     * <p class="note"><strong>Warning:</strong> Geocoding services may provide no guarantees on
+     * availability or accuracy. Results are a best guess, and are not guaranteed to be meaningful
+     * or correct. Do <b>NOT</b> use this API for any safety-critical or regulatory compliance
+     * purposes.
      *
      * @param locationName a user-supplied description of a location
      * @param maxResults max number of results to return. Smaller numbers (1 to 5) are recommended
@@ -161,21 +165,20 @@ public final class Geocoder {
     }
 
     /**
-     * Returns an array of Addresses that are known to describe the
-     * named location, which may be a place name such as "Dalvik,
-     * Iceland", an address such as "1600 Amphitheatre Parkway,
-     * Mountain View, CA", an airport code such as "SFO", etc..  The
-     * returned addresses will be localized for the locale provided to
-     * this class's constructor.
-     *
-     * <p> You may specify a bounding box for the search results by including
-     * the Latitude and Longitude of the Lower Left point and Upper Right
-     * point of the box.
-     *
-     * <p> The query will block and returned values will be obtained by means of a network lookup.
-     * The results are a best guess and are not guaranteed to be meaningful or
-     * correct. It may be useful to call this method from a thread separate from your
-     * primary UI thread.
+     * Returns an array of Addresses that attempt to describe the named location, which may be a
+     * place name such as "Dalvik, Iceland", an address such as "1600 Amphitheatre Parkway, Mountain
+     * View, CA", an airport code such as "SFO", and so forth. The returned addresses should be
+     * localized for the locale provided to this class's constructor. Results may be obtained by
+     * means of a network lookup and this method may take some time to return, and so should not be
+     * called on the main thread.
+     *
+     * <p> You may specify a bounding box for the search results by including the latitude and
+     * longitude of the lower left point and upper right point of the box.
+     *
+     * <p class="note"><strong>Warning:</strong> Geocoding services may provide no guarantees on
+     * availability or accuracy. Results are a best guess, and are not guaranteed to be meaningful
+     * or correct. Do <b>NOT</b> use this API for any safety-critical or regulatory compliance
+     * purposes.
      *
      * @param locationName a user-supplied description of a location
      * @param maxResults max number of addresses to return. Smaller numbers (1 to 5) are recommended
diff --git a/location/java/android/location/Location.java b/location/java/android/location/Location.java
index 5f8d795cd654..1e8b9521e41e 100644
--- a/location/java/android/location/Location.java
+++ b/location/java/android/location/Location.java
@@ -508,15 +508,23 @@ public class Location implements Parcelable {
     /**
      * Return the UTC time of this location fix, in milliseconds since epoch (January 1, 1970).
      *
-     * <p>Note that the UTC time on a device is not monotonic; it can jump forwards or backwards
-     * unpredictably, so this time should not be used to calculate time deltas between locations.
-     * Instead prefer {@link #getElapsedRealtimeNanos} for that purpose.
+     * <p>There is no guarantee that different locations have times set from the same clock.
+     * Locations derived from the {@link LocationManager#GPS_PROVIDER} are guaranteed to have their
+     * time set from the clock in use by the satellite constellation that provided the fix.
+     * Locations derived from other providers may use any clock to set their time, though it is most
+     * common to use the device clock (which may be incorrect).
      *
-     * <p>On the other hand, this method is useful for presenting a human readable time to the user,
-     * or for carefully comparing location fixes across reboot or across devices.
+     * <p>Note that the device clock UTC time is not monotonic; it can jump forwards or backwards
+     * unpredictably and may be changed at any time by the user, so this time should not be used to
+     * order or compare locations. Prefer {@link #getElapsedRealtimeNanos} for that purpose, as this
+     * clock is guaranteed to be monotonic.
      *
-     * <p>All locations generated by the {@link LocationManager} are guaranteed to have a UTC time,
-     * however remember that the system time may have changed since the location was generated.
+     * <p>On the other hand, this method may be useful for presenting a human readable time to the
+     * user, or as a heuristic for comparing location fixes across reboot or across devices.
+     *
+     * <p>All locations generated by the {@link LocationManager} are guaranteed to have a UTC time
+     * set, however remember that the device clock may have changed since the location was
+     * generated.
      *
      * @return UTC time of fix, in milliseconds since January 1, 1970.
      */
@@ -534,53 +542,60 @@ public class Location implements Parcelable {
     }
 
     /**
-     * Return the time of this fix, in elapsed real-time since system boot.
+     * Return the time of this fix in nanoseconds of elapsed realtime since system boot.
      *
-     * <p>This value can be reliably compared to
-     * {@link android.os.SystemClock#elapsedRealtimeNanos},
-     * to calculate the age of a fix and to compare Location fixes. This
-     * is reliable because elapsed real-time is guaranteed monotonic for
-     * each system boot and continues to increment even when the system
-     * is in deep sleep (unlike {@link #getTime}.
+     * <p>This value can be compared with {@link android.os.SystemClock#elapsedRealtimeNanos}, to
+     * reliably order or compare locations. This is reliable because elapsed realtime is guaranteed
+     * to be monotonic and continues to increment even when the system is in deep sleep (unlike
+     * {@link #getTime}). However, since elapsed realtime is with reference to system boot, it does
+     * not make sense to use this value to order or compare locations across boot cycles.
      *
-     * <p>All locations generated by the {@link LocationManager}
-     * are guaranteed to have a valid elapsed real-time.
+     * <p>All locations generated by the {@link LocationManager} are guaranteed to have a valid
+     * elapsed realtime set.
      *
-     * @return elapsed real-time of fix, in nanoseconds since system boot.
+     * @return elapsed realtime of fix, in nanoseconds since system boot.
      */
     public long getElapsedRealtimeNanos() {
         return mElapsedRealtimeNanos;
     }
 
-    /** @hide */
+    /**
+     * Return the time of this fix in milliseconds of elapsed realtime since system boot.
+     *
+     * @see #getElapsedRealtimeNanos()
+     *
+     * @hide
+     */
     public long getElapsedRealtimeMillis() {
         return NANOSECONDS.toMillis(getElapsedRealtimeNanos());
     }
 
-    /** @hide */
-    public long getElapsedRealtimeAgeNanos(long referenceRealtimeNs) {
-        return referenceRealtimeNs - mElapsedRealtimeNanos;
-    }
-
-    /** @hide */
-    public long getElapsedRealtimeAgeNanos() {
-        return getElapsedRealtimeAgeNanos(SystemClock.elapsedRealtimeNanos());
-    }
-
-    /** @hide */
+    /**
+     * Returns the age of this fix with respect to the current elapsed realtime.
+     *
+     * @see #getElapsedRealtimeNanos()
+     *
+     * @hide
+     */
     public long getElapsedRealtimeAgeMillis() {
         return getElapsedRealtimeAgeMillis(SystemClock.elapsedRealtime());
     }
 
-    /** @hide */
+    /**
+     * Returns the age of this fix with respect to the given elapsed realtime.
+     *
+     * @see #getElapsedRealtimeNanos()
+     *
+     * @hide
+     */
     public long getElapsedRealtimeAgeMillis(long referenceRealtimeMs) {
         return referenceRealtimeMs - NANOSECONDS.toMillis(mElapsedRealtimeNanos);
     }
 
     /**
-     * Set the time of this fix, in elapsed real-time since system boot.
+     * Set the time of this fix, in elapsed realtime since system boot.
      *
-     * @param time elapsed real-time of fix, in nanoseconds since system boot.
+     * @param time elapsed realtime of fix, in nanoseconds since system boot.
      */
     public void setElapsedRealtimeNanos(long time) {
         mElapsedRealtimeNanos = time;
@@ -1143,7 +1158,7 @@ public class Location implements Parcelable {
                 s.append(" bAcc=").append(mBearingAccuracyDegrees);
             }
         }
-        if (isFromMockProvider()) {
+        if (isMock()) {
             s.append(" mock");
         }
 
@@ -1293,12 +1308,12 @@ public class Location implements Parcelable {
      * and {@link #bearingTo} don't duplicate work.
      */
     private static class BearingDistanceCache {
-        private double mLat1 = 0.0;
-        private double mLon1 = 0.0;
-        private double mLat2 = 0.0;
-        private double mLon2 = 0.0;
-        private float mDistance = 0.0f;
-        private float mInitialBearing = 0.0f;
-        private float mFinalBearing = 0.0f;
+        double mLat1 = 0.0;
+        double mLon1 = 0.0;
+        double mLat2 = 0.0;
+        double mLon2 = 0.0;
+        float mDistance = 0.0f;
+        float mInitialBearing = 0.0f;
+        float mFinalBearing = 0.0f;
     }
 }
diff --git a/location/java/android/location/LocationManager.java b/location/java/android/location/LocationManager.java
index 137d417d57c8..e6d94539fcf1 100644
--- a/location/java/android/location/LocationManager.java
+++ b/location/java/android/location/LocationManager.java
@@ -1969,7 +1969,7 @@ public class LocationManager {
 
     /**
      * Sets a new location for the given test provider. This location will be identiable as a mock
-     * location to all clients via {@link Location#isFromMockProvider()}.
+     * location to all clients via {@link Location#isMock()}.
      *
      * <p>The location object must have a minimum number of fields set to be considered valid, as
      * per documentation on {@link Location} class.