Merge "Update Location APIs per feedback" into tm-dev

core/api/current.txt

@@ -19487,26 +19487,26 @@ package android.location {
     method @NonNull public static String convert(@FloatRange double, int);
     method @FloatRange public static double convert(@NonNull String);
     method public int describeContents();
-    method public static void distanceBetween(@FloatRange double, @FloatRange double, @FloatRange double, @FloatRange double, float[]);
+    method public static void distanceBetween(@FloatRange(from=-90.0, to=90.0) double, @FloatRange(from=-180.0, to=180.0) double, @FloatRange(from=-90.0, to=90.0) double, @FloatRange(from=-180.0, to=180.0) double, float[]);
-    method @FloatRange public float distanceTo(@NonNull android.location.Location);
+    method @FloatRange(from=0.0) public float distanceTo(@NonNull android.location.Location);
-    method public void dump(@NonNull android.util.Printer, @Nullable String);
+    method @Deprecated public void dump(@NonNull android.util.Printer, @Nullable String);
-    method @FloatRange public float getAccuracy();
+    method @FloatRange(from=0.0) public float getAccuracy();
     method @FloatRange public double getAltitude();
-    method @FloatRange(from=0.0f, to=360.0f, toInclusive=false) public float getBearing();
+    method @FloatRange(from=0.0, to=360.0, toInclusive=false) public float getBearing();
-    method @FloatRange public float getBearingAccuracyDegrees();
+    method @FloatRange(from=0.0) public float getBearingAccuracyDegrees();
-    method @IntRange public long getElapsedRealtimeAgeMillis();
+    method @IntRange(from=0) public long getElapsedRealtimeAgeMillis();
-    method @IntRange public long getElapsedRealtimeAgeMillis(@IntRange long);
+    method public long getElapsedRealtimeAgeMillis(@IntRange(from=0) long);
-    method @IntRange public long getElapsedRealtimeMillis();
+    method @IntRange(from=0) public long getElapsedRealtimeMillis();
-    method @IntRange public long getElapsedRealtimeNanos();
+    method @IntRange(from=0) public long getElapsedRealtimeNanos();
-    method @FloatRange public double getElapsedRealtimeUncertaintyNanos();
+    method @FloatRange(from=0.0) public double getElapsedRealtimeUncertaintyNanos();
     method @Nullable public android.os.Bundle getExtras();
-    method @FloatRange public double getLatitude();
+    method @FloatRange(from=-90.0, to=90.0) public double getLatitude();
-    method @FloatRange public double getLongitude();
+    method @FloatRange(from=-180.0, to=180.0) public double getLongitude();
     method @Nullable public String getProvider();
-    method @FloatRange public float getSpeed();
+    method @FloatRange(from=0.0) public float getSpeed();
-    method @FloatRange public float getSpeedAccuracyMetersPerSecond();
+    method @FloatRange(from=0.0) public float getSpeedAccuracyMetersPerSecond();
-    method @IntRange public long getTime();
+    method @IntRange(from=0) public long getTime();
-    method @FloatRange public float getVerticalAccuracyMeters();
+    method @FloatRange(from=0.0) public float getVerticalAccuracyMeters();
     method public boolean hasAccuracy();
     method public boolean hasAltitude();
     method public boolean hasBearing();
@@ -19528,21 +19528,21 @@ package android.location {
     method public void removeVerticalAccuracy();
     method public void reset();
     method public void set(@NonNull android.location.Location);
-    method public void setAccuracy(@FloatRange float);
+    method public void setAccuracy(@FloatRange(from=0.0) float);
     method public void setAltitude(@FloatRange double);
     method public void setBearing(@FloatRange(fromInclusive=false, toInclusive=false) float);
-    method public void setBearingAccuracyDegrees(@FloatRange float);
+    method public void setBearingAccuracyDegrees(@FloatRange(from=0.0) float);
-    method public void setElapsedRealtimeNanos(@IntRange long);
+    method public void setElapsedRealtimeNanos(@IntRange(from=0) long);
-    method public void setElapsedRealtimeUncertaintyNanos(@FloatRange double);
+    method public void setElapsedRealtimeUncertaintyNanos(@FloatRange(from=0.0) double);
     method public void setExtras(@Nullable android.os.Bundle);
-    method public void setLatitude(@FloatRange double);
+    method public void setLatitude(@FloatRange(from=-90.0, to=90.0) double);
-    method public void setLongitude(@FloatRange double);
+    method public void setLongitude(@FloatRange(from=-180.0, to=180.0) double);
     method public void setMock(boolean);
     method public void setProvider(@Nullable String);
-    method public void setSpeed(@FloatRange float);
+    method public void setSpeed(@FloatRange(from=0.0) float);
-    method public void setSpeedAccuracyMetersPerSecond(@FloatRange float);
+    method public void setSpeedAccuracyMetersPerSecond(@FloatRange(from=0.0) float);
-    method public void setTime(@IntRange long);
+    method public void setTime(@IntRange(from=0) long);
-    method public void setVerticalAccuracyMeters(@FloatRange float);
+    method public void setVerticalAccuracyMeters(@FloatRange(from=0.0) float);
     method public void writeToParcel(@NonNull android.os.Parcel, int);
     field @NonNull public static final android.os.Parcelable.Creator<android.location.Location> CREATOR;
     field public static final int FORMAT_DEGREES = 0; // 0x0

location/java/android/location/Location.java

@@ -132,31 +132,31 @@ public class Location implements Parcelable {
     }
 
     /**
-     * Construct a new Location object that is copied from an existing one.
+     * Constructs a new location copied from the given location.
      */
-    public Location(@NonNull Location l) {
+    public Location(@NonNull Location location) {
-        set(l);
+        set(location);
     }
 
     /**
      * Turns this location into a copy of the given location.
      */
-    public void set(@NonNull Location l) {
+    public void set(@NonNull Location location) {
-        mFieldsMask = l.mFieldsMask;
+        mFieldsMask = location.mFieldsMask;
-        mProvider = l.mProvider;
+        mProvider = location.mProvider;
-        mTimeMs = l.mTimeMs;
+        mTimeMs = location.mTimeMs;
-        mElapsedRealtimeNs = l.mElapsedRealtimeNs;
+        mElapsedRealtimeNs = location.mElapsedRealtimeNs;
-        mElapsedRealtimeUncertaintyNs = l.mElapsedRealtimeUncertaintyNs;
+        mElapsedRealtimeUncertaintyNs = location.mElapsedRealtimeUncertaintyNs;
-        mLatitudeDegrees = l.mLatitudeDegrees;
+        mLatitudeDegrees = location.mLatitudeDegrees;
-        mLongitudeDegrees = l.mLongitudeDegrees;
+        mLongitudeDegrees = location.mLongitudeDegrees;
-        mHorizontalAccuracyMeters = l.mHorizontalAccuracyMeters;
+        mHorizontalAccuracyMeters = location.mHorizontalAccuracyMeters;
-        mAltitudeMeters = l.mAltitudeMeters;
+        mAltitudeMeters = location.mAltitudeMeters;
-        mAltitudeAccuracyMeters = l.mAltitudeAccuracyMeters;
+        mAltitudeAccuracyMeters = location.mAltitudeAccuracyMeters;
-        mSpeedMetersPerSecond = l.mSpeedMetersPerSecond;
+        mSpeedMetersPerSecond = location.mSpeedMetersPerSecond;
-        mSpeedAccuracyMetersPerSecond = l.mSpeedAccuracyMetersPerSecond;
+        mSpeedAccuracyMetersPerSecond = location.mSpeedAccuracyMetersPerSecond;
-        mBearingDegrees = l.mBearingDegrees;
+        mBearingDegrees = location.mBearingDegrees;
-        mBearingAccuracyDegrees = l.mBearingAccuracyDegrees;
+        mBearingAccuracyDegrees = location.mBearingAccuracyDegrees;
-        mExtras = (l.mExtras == null) ? null : new Bundle(l.mExtras);
+        mExtras = (location.mExtras == null) ? null : new Bundle(location.mExtras);
     }
 
     /**
@@ -182,14 +182,13 @@ public class Location implements Parcelable {
     }
 
     /**
-     * Returns the approximate distance in meters between this
+     * Returns the approximate distance in meters between this location and the given location.
-     * location and the given location.  Distance is defined using
+     * Distance is defined using the WGS84 ellipsoid.
-     * the WGS84 ellipsoid.
      *
      * @param dest the destination location
      * @return the approximate distance in meters
      */
-    public @FloatRange float distanceTo(@NonNull Location dest) {
+    public @FloatRange(from = 0.0) float distanceTo(@NonNull Location dest) {
         BearingDistanceCache cache = sBearingDistanceCache.get();
         // See if we already have the result
         if (mLatitudeDegrees != cache.mLat1 || mLongitudeDegrees != cache.mLon1
@@ -201,11 +200,10 @@ public class Location implements Parcelable {
     }
 
     /**
-     * Returns the approximate initial bearing in degrees East of true
+     * Returns the approximate initial bearing in degrees east of true north when traveling along
-     * North when traveling along the shortest path between this
+     * the shortest path between this location and the given location. The shortest path is defined
-     * location and the given location.  The shortest path is defined
+     * using the WGS84 ellipsoid. Locations that are (nearly) antipodal may produce meaningless
-     * using the WGS84 ellipsoid.  Locations that are (nearly)
+     * results.
-     * antipodal may produce meaningless results.
      *
      * @param dest the destination location
      * @return the initial bearing in degrees
@@ -254,7 +252,7 @@ public class Location implements Parcelable {
      * not be used to order or compare locations. Prefer {@link #getElapsedRealtimeNanos} for that
      * purpose, as the elapsed realtime clock is guaranteed to be monotonic.
      *
-     * <p>On the other hand, this method may be useful for presenting a human readable time to the
+     * <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 this time
@@ -263,25 +261,24 @@ public class Location implements Parcelable {
      *
      * @return the Unix epoch time of this location
      */
-    public @IntRange long getTime() {
+    public @IntRange(from = 0) long getTime() {
         return mTimeMs;
     }
 
     /**
      * Sets the Unix epoch time of this location fix, in milliseconds since the start of the Unix
-     * epoch (00:00:00 January 1, 1970 UTC).
+     * epoch (00:00:00 January 1 1970 UTC).
      *
      * @param timeMs the Unix epoch time of this location
-     * @see #getTime for more information about times / clocks
      */
-    public void setTime(@IntRange long timeMs) {
+    public void setTime(@IntRange(from = 0) long timeMs) {
         mTimeMs = timeMs;
     }
 
     /**
      * Return the time of this fix in nanoseconds of elapsed realtime since system boot.
      *
-     * <p>This value can be compared with {@link android.os.SystemClock#elapsedRealtimeNanos}, to
+     * <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
@@ -292,7 +289,7 @@ public class Location implements Parcelable {
      *
      * @return elapsed realtime of this location in nanoseconds
      */
-    public @IntRange long getElapsedRealtimeNanos() {
+    public @IntRange(from = 0) long getElapsedRealtimeNanos() {
         return mElapsedRealtimeNs;
     }
 
@@ -302,7 +299,7 @@ public class Location implements Parcelable {
      * @return elapsed realtime of this location in milliseconds
      * @see #getElapsedRealtimeNanos()
      */
-    public @IntRange long getElapsedRealtimeMillis() {
+    public @IntRange(from = 0) long getElapsedRealtimeMillis() {
         return NANOSECONDS.toMillis(mElapsedRealtimeNs);
     }
 
@@ -312,7 +309,7 @@ public class Location implements Parcelable {
      *
      * @return age of this location in milliseconds
      */
-    public @IntRange long getElapsedRealtimeAgeMillis() {
+    public @IntRange(from = 0) long getElapsedRealtimeAgeMillis() {
         return getElapsedRealtimeAgeMillis(SystemClock.elapsedRealtime());
     }
 
@@ -323,7 +320,8 @@ public class Location implements Parcelable {
      * @param referenceRealtimeMs reference realtime in milliseconds
      * @return age of this location in milliseconds
      */
-    public @IntRange long getElapsedRealtimeAgeMillis(@IntRange long referenceRealtimeMs) {
+    public long getElapsedRealtimeAgeMillis(
+            @IntRange(from = 0) long referenceRealtimeMs) {
         return referenceRealtimeMs - getElapsedRealtimeMillis();
     }
 
@@ -332,7 +330,7 @@ public class Location implements Parcelable {
      *
      * @param elapsedRealtimeNs elapsed realtime in nanoseconds
      */
-    public void setElapsedRealtimeNanos(@IntRange long elapsedRealtimeNs) {
+    public void setElapsedRealtimeNanos(@IntRange(from = 0) long elapsedRealtimeNs) {
         mElapsedRealtimeNs = elapsedRealtimeNs;
     }
 
@@ -346,7 +344,7 @@ public class Location implements Parcelable {
      *
      * @return uncertainty in nanoseconds of the elapsed realtime of this location
      */
-    public @FloatRange double getElapsedRealtimeUncertaintyNanos() {
+    public @FloatRange(from = 0.0) double getElapsedRealtimeUncertaintyNanos() {
         return mElapsedRealtimeUncertaintyNs;
     }
 
@@ -358,20 +356,20 @@ public class Location implements Parcelable {
      *                                     this location
      */
     public void setElapsedRealtimeUncertaintyNanos(
-            @FloatRange double elapsedRealtimeUncertaintyNs) {
+            @FloatRange(from = 0.0) double elapsedRealtimeUncertaintyNs) {
         mElapsedRealtimeUncertaintyNs = elapsedRealtimeUncertaintyNs;
         mFieldsMask |= HAS_ELAPSED_REALTIME_UNCERTAINTY_MASK;
     }
 
     /**
-     * True if this location has a elapsed realtime uncertainty, false otherwise.
+     * True if this location has an elapsed realtime uncertainty, false otherwise.
      */
     public boolean hasElapsedRealtimeUncertaintyNanos() {
         return (mFieldsMask & HAS_ELAPSED_REALTIME_UNCERTAINTY_MASK) != 0;
     }
 
     /**
-     * Removes the elapsed realtime uncertainy from this location.
+     * Removes the elapsed realtime uncertainty from this location.
      */
     public void removeElapsedRealtimeUncertaintyNanos() {
         mFieldsMask &= ~HAS_ELAPSED_REALTIME_UNCERTAINTY_MASK;
@@ -383,7 +381,7 @@ public class Location implements Parcelable {
      *
      * @return latitude of this location
      */
-    public @FloatRange double getLatitude() {
+    public @FloatRange(from = -90.0, to = 90.0) double getLatitude() {
         return mLatitudeDegrees;
     }
 
@@ -392,7 +390,7 @@ public class Location implements Parcelable {
      *
      * @param latitudeDegrees latitude in degrees
      */
-    public void setLatitude(@FloatRange double latitudeDegrees) {
+    public void setLatitude(@FloatRange(from = -90.0, to = 90.0) double latitudeDegrees) {
         mLatitudeDegrees = latitudeDegrees;
     }
 
@@ -402,7 +400,7 @@ public class Location implements Parcelable {
      *
      * @return longitude of this location
      */
-    public @FloatRange double getLongitude() {
+    public @FloatRange(from = -180.0, to = 180.0) double getLongitude() {
         return mLongitudeDegrees;
     }
 
@@ -411,7 +409,7 @@ public class Location implements Parcelable {
      *
      * @param longitudeDegrees longitude in degrees
      */
-    public void setLongitude(@FloatRange double longitudeDegrees) {
+    public void setLongitude(@FloatRange(from = -180.0, to = 180.0) double longitudeDegrees) {
         mLongitudeDegrees = longitudeDegrees;
     }
 
@@ -423,12 +421,12 @@ public class Location implements Parcelable {
      * reported location, there is a 68% chance that the true location falls within this circle.
      * This accuracy value is only valid for horizontal positioning, and not vertical positioning.
      *
-     * <p>This is only valid if {@link #hasSpeed()} is true. All locations generated by the
+     * <p>This is only valid if {@link #hasAccuracy()} is true. All locations generated by the
      * {@link LocationManager} include horizontal accuracy.
      *
      * @return horizontal accuracy of this location
      */
-    public @FloatRange float getAccuracy() {
+    public @FloatRange(from = 0.0) float getAccuracy() {
         return mHorizontalAccuracyMeters;
     }
 
@@ -437,7 +435,7 @@ public class Location implements Parcelable {
      *
      * @param horizontalAccuracyMeters horizontal altitude in meters
      */
-    public void setAccuracy(@FloatRange float horizontalAccuracyMeters) {
+    public void setAccuracy(@FloatRange(from = 0.0) float horizontalAccuracyMeters) {
         mHorizontalAccuracyMeters = horizontalAccuracyMeters;
         mFieldsMask |= HAS_HORIZONTAL_ACCURACY_MASK;
     }
@@ -500,7 +498,7 @@ public class Location implements Parcelable {
      *
      * @return vertical accuracy of this location
      */
-    public @FloatRange float getVerticalAccuracyMeters() {
+    public @FloatRange(from = 0.0) float getVerticalAccuracyMeters() {
         return mAltitudeAccuracyMeters;
     }
 
@@ -509,7 +507,7 @@ public class Location implements Parcelable {
      *
      * @param altitudeAccuracyMeters altitude accuracy in meters
      */
-    public void setVerticalAccuracyMeters(@FloatRange float altitudeAccuracyMeters) {
+    public void setVerticalAccuracyMeters(@FloatRange(from = 0.0) float altitudeAccuracyMeters) {
         mAltitudeAccuracyMeters = altitudeAccuracyMeters;
         mFieldsMask |= HAS_ALTITUDE_ACCURACY_MASK;
     }
@@ -538,17 +536,16 @@ public class Location implements Parcelable {
      *
      * @return speed at the time of this location
      */
-    public @FloatRange float getSpeed() {
+    public @FloatRange(from = 0.0) float getSpeed() {
         return mSpeedMetersPerSecond;
     }
 
     /**
-     * Set the speed at the time of this location, in meters per second. Prefer not to set negative
+     * Set the speed at the time of this location, in meters per second.
-     * speeds.
      *
      * @param speedMetersPerSecond speed in meters per second
      */
-    public void setSpeed(@FloatRange float speedMetersPerSecond) {
+    public void setSpeed(@FloatRange(from = 0.0) float speedMetersPerSecond) {
         mSpeedMetersPerSecond = speedMetersPerSecond;
         mFieldsMask |= HAS_SPEED_MASK;
     }
@@ -576,7 +573,7 @@ public class Location implements Parcelable {
      *
      * @return vertical accuracy of this location
      */
-    public @FloatRange float getSpeedAccuracyMetersPerSecond() {
+    public @FloatRange(from = 0.0) float getSpeedAccuracyMetersPerSecond() {
         return mSpeedAccuracyMetersPerSecond;
     }
 
@@ -585,7 +582,8 @@ public class Location implements Parcelable {
      *
      * @param speedAccuracyMeterPerSecond speed accuracy in meters per second
      */
-    public void setSpeedAccuracyMetersPerSecond(@FloatRange float speedAccuracyMeterPerSecond) {
+    public void setSpeedAccuracyMetersPerSecond(
+            @FloatRange(from = 0.0) float speedAccuracyMeterPerSecond) {
         mSpeedAccuracyMetersPerSecond = speedAccuracyMeterPerSecond;
         mFieldsMask |= HAS_SPEED_ACCURACY_MASK;
     }
@@ -613,7 +611,7 @@ public class Location implements Parcelable {
      *
      * @return bearing at the time of this location
      */
-    public @FloatRange(from = 0f, to = 360f, toInclusive = false) float getBearing() {
+    public @FloatRange(from = 0.0, to = 360.0, toInclusive = false) float getBearing() {
         return mBearingDegrees;
     }
 
@@ -663,7 +661,7 @@ public class Location implements Parcelable {
      *
      * @return bearing accuracy in degrees of this location
      */
-    public @FloatRange float getBearingAccuracyDegrees() {
+    public @FloatRange(from = 0.0) float getBearingAccuracyDegrees() {
         return mBearingAccuracyDegrees;
     }
 
@@ -672,7 +670,7 @@ public class Location implements Parcelable {
      *
      * @param bearingAccuracyDegrees bearing accuracy in degrees
      */
-    public void setBearingAccuracyDegrees(@FloatRange float bearingAccuracyDegrees) {
+    public void setBearingAccuracyDegrees(@FloatRange(from = 0.0) float bearingAccuracyDegrees) {
         mBearingAccuracyDegrees = bearingAccuracyDegrees;
         mFieldsMask |= HAS_BEARING_ACCURACY_MASK;
     }
@@ -692,9 +690,11 @@ public class Location implements Parcelable {
     }
 
     /**
-     * Returns true if the Location came from a mock provider.
+     * Returns true if this is a mock location. If this location comes from the Android framework,
+     * this indicates that the location was provided by a test location provider, and thus may not
+     * be related to the actual location of the device.
      *
-     * @return true if this Location came from a mock provider, false otherwise
+     * @return true if this location came from a mock provider, false otherwise
      * @deprecated Prefer {@link #isMock()} instead.
      */
     @Deprecated
@@ -703,9 +703,9 @@ public class Location implements Parcelable {
     }
 
     /**
-     * Flag this Location as having come from a mock provider or not.
+     * Flag this location as having come from a mock provider or not.
      *
-     * @param isFromMockProvider true if this Location came from a mock provider, false otherwise
+     * @param isFromMockProvider true if this location came from a mock provider, false otherwise
      * @deprecated Prefer {@link #setMock(boolean)} instead.
      * @hide
      */
@@ -745,7 +745,7 @@ public class Location implements Parcelable {
      * will be present for any location.
      *
      * <ul>
-     * <li> satellites - the number of satellites used to derive the GNSS fix
+     * <li> satellites - the number of satellites used to derive a GNSS fix
      * </ul>
      */
     public @Nullable Bundle getExtras() {
@@ -899,7 +899,13 @@ public class Location implements Parcelable {
         return s.toString();
     }
 
-    /** Dumps location. */
+    /**
+     * Dumps location information to the given Printer.
+     *
+     * @deprecated Prefer to use {@link #toString()} along with whatever custom formatting is
+     * required instead of this method. It is not this class's job to manage print representations.
+     */
+    @Deprecated
     public void dump(@NonNull Printer pw, @Nullable String prefix) {
         pw.println(prefix + this);
     }
@@ -1209,10 +1215,10 @@ public class Location implements Parcelable {
      * @throws IllegalArgumentException if results is null or has length < 1
      */
     public static void distanceBetween(
-            @FloatRange double startLatitude,
+            @FloatRange(from = -90.0, to = 90.0) double startLatitude,
-            @FloatRange double startLongitude,
+            @FloatRange(from = -180.0, to = 180.0) double startLongitude,
-            @FloatRange double endLatitude,
+            @FloatRange(from = -90.0, to = 90.0) double endLatitude,
-            @FloatRange double endLongitude,
+            @FloatRange(from = -180.0, to = 180.0)  double endLongitude,
             float[] results) {
         if (results == null || results.length < 1) {
             throw new IllegalArgumentException("results is null or has length < 1");