diff --git a/core/api/current.txt b/core/api/current.txt index 74e3043a4e375..3bd49b935d579 100644 --- a/core/api/current.txt +++ b/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 @FloatRange public float distanceTo(@NonNull android.location.Location); - method public void dump(@NonNull android.util.Printer, @Nullable String); - method @FloatRange public float getAccuracy(); + 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(from=0.0) public float distanceTo(@NonNull android.location.Location); + method @Deprecated public void dump(@NonNull android.util.Printer, @Nullable String); + 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 public float getBearingAccuracyDegrees(); - method @IntRange public long getElapsedRealtimeAgeMillis(); - method @IntRange public long getElapsedRealtimeAgeMillis(@IntRange long); - method @IntRange public long getElapsedRealtimeMillis(); - method @IntRange public long getElapsedRealtimeNanos(); - method @FloatRange public double getElapsedRealtimeUncertaintyNanos(); + method @FloatRange(from=0.0, to=360.0, toInclusive=false) public float getBearing(); + method @FloatRange(from=0.0) public float getBearingAccuracyDegrees(); + method @IntRange(from=0) public long getElapsedRealtimeAgeMillis(); + method public long getElapsedRealtimeAgeMillis(@IntRange(from=0) long); + method @IntRange(from=0) public long getElapsedRealtimeMillis(); + method @IntRange(from=0) public long getElapsedRealtimeNanos(); + method @FloatRange(from=0.0) public double getElapsedRealtimeUncertaintyNanos(); method @Nullable public android.os.Bundle getExtras(); - method @FloatRange public double getLatitude(); - method @FloatRange public double getLongitude(); + method @FloatRange(from=-90.0, to=90.0) public double getLatitude(); + method @FloatRange(from=-180.0, to=180.0) public double getLongitude(); method @Nullable public String getProvider(); - method @FloatRange public float getSpeed(); - method @FloatRange public float getSpeedAccuracyMetersPerSecond(); - method @IntRange public long getTime(); - method @FloatRange public float getVerticalAccuracyMeters(); + method @FloatRange(from=0.0) public float getSpeed(); + method @FloatRange(from=0.0) public float getSpeedAccuracyMetersPerSecond(); + method @IntRange(from=0) public long getTime(); + 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 setElapsedRealtimeNanos(@IntRange long); - method public void setElapsedRealtimeUncertaintyNanos(@FloatRange double); + method public void setBearingAccuracyDegrees(@FloatRange(from=0.0) float); + method public void setElapsedRealtimeNanos(@IntRange(from=0) long); + 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 setLongitude(@FloatRange double); + method public void setLatitude(@FloatRange(from=-90.0, to=90.0) 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 setSpeedAccuracyMetersPerSecond(@FloatRange float); - method public void setTime(@IntRange long); - method public void setVerticalAccuracyMeters(@FloatRange float); + method public void setSpeed(@FloatRange(from=0.0) float); + method public void setSpeedAccuracyMetersPerSecond(@FloatRange(from=0.0) float); + method public void setTime(@IntRange(from=0) long); + 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 CREATOR; field public static final int FORMAT_DEGREES = 0; // 0x0 diff --git a/location/java/android/location/Location.java b/location/java/android/location/Location.java index f1605f1ffe5d1..033056cb2a694 100644 --- a/location/java/android/location/Location.java +++ b/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) { - set(l); + public Location(@NonNull Location location) { + set(location); } /** * Turns this location into a copy of the given location. */ - public void set(@NonNull Location l) { - mFieldsMask = l.mFieldsMask; - mProvider = l.mProvider; - mTimeMs = l.mTimeMs; - mElapsedRealtimeNs = l.mElapsedRealtimeNs; - mElapsedRealtimeUncertaintyNs = l.mElapsedRealtimeUncertaintyNs; - mLatitudeDegrees = l.mLatitudeDegrees; - mLongitudeDegrees = l.mLongitudeDegrees; - mHorizontalAccuracyMeters = l.mHorizontalAccuracyMeters; - mAltitudeMeters = l.mAltitudeMeters; - mAltitudeAccuracyMeters = l.mAltitudeAccuracyMeters; - mSpeedMetersPerSecond = l.mSpeedMetersPerSecond; - mSpeedAccuracyMetersPerSecond = l.mSpeedAccuracyMetersPerSecond; - mBearingDegrees = l.mBearingDegrees; - mBearingAccuracyDegrees = l.mBearingAccuracyDegrees; - mExtras = (l.mExtras == null) ? null : new Bundle(l.mExtras); + public void set(@NonNull Location location) { + mFieldsMask = location.mFieldsMask; + mProvider = location.mProvider; + mTimeMs = location.mTimeMs; + mElapsedRealtimeNs = location.mElapsedRealtimeNs; + mElapsedRealtimeUncertaintyNs = location.mElapsedRealtimeUncertaintyNs; + mLatitudeDegrees = location.mLatitudeDegrees; + mLongitudeDegrees = location.mLongitudeDegrees; + mHorizontalAccuracyMeters = location.mHorizontalAccuracyMeters; + mAltitudeMeters = location.mAltitudeMeters; + mAltitudeAccuracyMeters = location.mAltitudeAccuracyMeters; + mSpeedMetersPerSecond = location.mSpeedMetersPerSecond; + mSpeedAccuracyMetersPerSecond = location.mSpeedAccuracyMetersPerSecond; + mBearingDegrees = location.mBearingDegrees; + mBearingAccuracyDegrees = location.mBearingAccuracyDegrees; + 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 - * location and the given location. Distance is defined using - * the WGS84 ellipsoid. + * Returns the approximate distance in meters between this location and the given location. + * Distance is defined using 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 - * North when traveling along the shortest path between this - * location and the given location. The shortest path is defined - * using the WGS84 ellipsoid. Locations that are (nearly) - * antipodal may produce meaningless results. + * Returns the approximate initial bearing in degrees east of true north when traveling along + * the shortest path between this location and the given location. The shortest path is defined + * using the WGS84 ellipsoid. Locations that are (nearly) 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. * - *

On the other hand, this method may be useful for presenting a human readable time to the + *

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. * *

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. * - *

This value can be compared with {@link android.os.SystemClock#elapsedRealtimeNanos}, to + *

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. * - *

This is only valid if {@link #hasSpeed()} is true. All locations generated by the + *

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 - * speeds. + * Set the speed at the time of this location, in meters per second. * * @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. * *

*/ 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 double startLongitude, - @FloatRange double endLatitude, - @FloatRange double endLongitude, + @FloatRange(from = -90.0, to = 90.0) double startLatitude, + @FloatRange(from = -180.0, to = 180.0) double startLongitude, + @FloatRange(from = -90.0, to = 90.0) double endLatitude, + @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");