Add javadoc for new location API's. (4e31c4ff) · Commits · e / os / android_frameworks_base

api/current.txt

+3 −3

location/java/android/location/Criteria.java

+3 −1

Original line number	Original line	Diff line number	Diff line
	@@ -24,7 +24,9 @@ import android.os.Parcelable;
	* location provider. Providers maybe ordered according to accuracy,		* location provider. Providers maybe ordered according to accuracy,
	* power usage, ability to report altitude, speed,		* power usage, ability to report altitude, speed,
	* and bearing, and monetary cost.		* and bearing, and monetary cost.
	* @deprecated {@link LocationRequest} instead		*
			* @deprecated use {@link LocationRequest} instead, and also see notes
			* at {@link LocationManager}
	*/		*/
	@Deprecated		@Deprecated
	public class Criteria implements Parcelable {		public class Criteria implements Parcelable {

location/java/android/location/Geofence.java

+9 −1

Original line number	Original line	Diff line number	Diff line
	@@ -20,7 +20,11 @@ import android.os.Parcel;
	import android.os.Parcelable;		import android.os.Parcelable;

	/**		/**
	* Represents a Geofence		* Represents a geographical boundary, also known as a geofence.
			*
			* <p>Currently only circular geofences are supported, but this object
			* is opaque so could be used in the future to represent polygons or other
			* shapes.
	*/		*/
	public final class Geofence implements Parcelable {		public final class Geofence implements Parcelable {
	/** @hide */		/** @hide */
	@@ -33,6 +37,7 @@ public final class Geofence implements Parcelable {

	/**		/**
	* Create a horizontal, circular geofence.		* Create a horizontal, circular geofence.
			*
	* @param latitude latitude in degrees		* @param latitude latitude in degrees
	* @param longitude longitude in degrees		* @param longitude longitude in degrees
	* @param radius radius in meters		* @param radius radius in meters
	@@ -152,6 +157,9 @@ public final class Geofence implements Parcelable {
	return result;		return result;
	}		}

			/**
			* Two geofences are equal if they have identical properties.
			*/
	@Override		@Override
	public boolean equals(Object obj) {		public boolean equals(Object obj) {
	if (this == obj)		if (this == obj)

location/java/android/location/Location.java

+140 −85

Original line number	Original line	Diff line number	Diff line
	@@ -27,15 +27,15 @@ import java.text.DecimalFormat;
	import java.util.StringTokenizer;		import java.util.StringTokenizer;

	/**		/**
	* A class representing a geographic location sensed at a particular		* A data class representing a geographic location.
	* time (a "fix"). A location consists of a latitude and longitude, a
	* UTC timestamp. and optionally information on altitude, speed, and
	* bearing.
	*		*
	* <p> Information specific to a particular provider or class of		* <p>A location can consist of a latitude, longitude, timestamp,
	* providers may be communicated to the application using getExtras,		* and other information such as bearing, altitude and velocity.
	* which returns a Bundle of key/value pairs. Each provider will only		*
	* provide those entries for which information is available.		* <p>All locations generated by the {@link LocationManager} are
			* guaranteed to have a valid latitude, longitude, and timestamp
			* (both UTC time and elapsed real-time since boot), all other
			* parameters are optional.
	*/		*/
	public class Location implements Parcelable {		public class Location implements Parcelable {
	/**		/**
	@@ -86,20 +86,19 @@ public class Location implements Parcelable {
	private float[] mResults = new float[2];		private float[] mResults = new float[2];

	/**		/**
	* Constructs a new Location. By default, time, latitude,		* Construct a new Location with a named provider.
	* longitude, and numSatellites are 0; hasAltitude, hasSpeed, and		*
	* hasBearing are false; and there is no extra information.		* <p>By default time, latitude and longitude are 0, and the location
			* has no bearing, altitude, speed, accuracy or extras.
	*		*
	* @param provider the name of the location provider that generated this		* @param provider the name of the provider that generated this location
	* location fix.
	*/		*/
	public Location(String provider) {		public Location(String provider) {
	mProvider = provider;		mProvider = provider;
	}		}

	/**		/**
	* Constructs a new Location object that is a copy of the given		* Construct a new Location object that is copied from an existing one.
	* location.
	*/		*/
	public Location(Location l) {		public Location(Location l) {
	set(l);		set(l);
	@@ -447,9 +446,19 @@ public class Location implements Parcelable {
	}		}

	/**		/**
	* Returns the name of the provider that generated this fix,		* Returns the name of the provider that generated this fix.
	* or null if it is not associated with a provider.		*
			* <p class="note">At API version 17 we deprecated {@link LocationProvider}
			* and all API methods that request a provider by name. The new API methods
			* will produce locations that could come from different sources, and even
			* locations that are fused from several sources. So you should generally
			* not care what provider is associated with a location object.
			*
			* @return the provider, or null if it has not been set
			*
			* @deprecated locations can now be sourced from many providers, or even fused
	*/		*/
			@Deprecated
	public String getProvider() {		public String getProvider() {
	return mProvider;		return mProvider;
	}		}
	@@ -462,16 +471,19 @@ public class Location implements Parcelable {
	}		}

	/**		/**
	* Return the UTC time of this fix, in milliseconds since January 1,		* Return the UTC time of this fix, in milliseconds since January 1, 1970.
	* 1970.		*
	* <p>Note that the UTC time on a device is not monotonic: it		* <p>Note that the UTC time on a device is not monotonic: it
	* can jump forwards or backwards unpredictably. So always use		* can jump forwards or backwards unpredictably. So always use
	* {@link #getElapsedRealtimeNano()} when calculating time deltas.		* {@link #getElapsedRealtimeNano} when calculating time deltas.
	* <p>On the other hand, {@link #getTime()} is useful for presenting		*
			* <p>On the other hand, {@link #getTime} is useful for presenting
	* a human readable time to the user, or for carefully comparing		* a human readable time to the user, or for carefully comparing
	* location fixes across reboot or across devices.		* location fixes across reboot or across devices.
	* <p>This method will always return a valid timestamp on		*
	* Locations generated by a {@link LocationProvider}.		* <p>All locations generated by the {@link LocationManager}
			* are guaranteed to have a valid UTC time, however remember that
			* the system time may have changed since the location was generated.
	*		*
	* @return time of fix, in milliseconds since January 1, 1970.		* @return time of fix, in milliseconds since January 1, 1970.
	*/		*/
	@@ -491,13 +503,16 @@ 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 elapsed real-time since system boot.
			*
	* <p>This value can be reliably compared to		* <p>This value can be reliably compared to
	* {@link android.os.SystemClock#elapsedRealtimeNano()},		* {@link android.os.SystemClock#elapsedRealtimeNano},
	* to calculate the age of a fix, and to compare Location fixes, since		* to calculate the age of a fix and to compare Location fixes. This
	* elapsed real-time is guaranteed monotonic for each system boot, and		* is reliable because elapsed real-time is guaranteed monotonic for
	* continues to increment even when the system is in deep sleep.		* each system boot and continues to increment even when the system
	* <p>This method will always return a valid timestamp on		* is in deep sleep (unlike {@link #getTime}.
	* Locations generated by a {@link LocationProvider}.		*
			* <p>All locations generated by the {@link LocationManager}
			* are guaranteed to have a valid elapsed real-time.
	*		*
	* @return elapsed real-time of fix, in nanoseconds since system boot.		* @return elapsed real-time of fix, in nanoseconds since system boot.
	*/		*/
	@@ -515,56 +530,59 @@ public class Location implements Parcelable {
	}		}

	/**		/**
	* Return the latitude of this fix.		* Get the latitude, in degrees.
	* <p>This method will always return a valid latitude on		*
	* Locations generated by a {@link LocationProvider}.		* <p>All locations generated by the {@link LocationManager}
			* will have a valid latitude.
	*/		*/
	public double getLatitude() {		public double getLatitude() {
	return mLatitude;		return mLatitude;
	}		}

	/**		/**
	* Sets the latitude of this fix.		* Set the latitude, in degrees.
	*/		*/
	public void setLatitude(double latitude) {		public void setLatitude(double latitude) {
	mLatitude = latitude;		mLatitude = latitude;
	}		}

	/**		/**
	* Return the longitude of this fix.		* Get the longitude, in degrees.
	* <p>This method will always return a valid longitude on		*
	* Locations generated by a {@link LocationProvider}.		* <p>All locations generated by the {@link LocationManager}
			* will have a valid longitude.
	*/		*/
	public double getLongitude() {		public double getLongitude() {
	return mLongitude;		return mLongitude;
	}		}

	/**		/**
	* Sets the longitude of this fix.		* Set the longitude, in degrees.
	*/		*/
	public void setLongitude(double longitude) {		public void setLongitude(double longitude) {
	mLongitude = longitude;		mLongitude = longitude;
	}		}

	/**		/**
	* Returns true if this fix contains altitude information, false		* True if this location has an altitude.
	* otherwise.
	*/		*/
	public boolean hasAltitude() {		public boolean hasAltitude() {
	return mHasAltitude;		return mHasAltitude;
	}		}

	/**		/**
	* Returns the altitude of this fix. If {@link #hasAltitude} is false,		* Get the altitude if available, in meters above sea level.
	* 0.0f is returned.		*
			* <p>If this location does not have an altitude then 0.0 is returned.
	*/		*/
	public double getAltitude() {		public double getAltitude() {
	return mAltitude;		return mAltitude;
	}		}

	/**		/**
	* Sets the altitude of this fix. Following this call,		* Set the altitude, in meters above sea level.
	* hasAltitude() will return true.		*
			* <p>Following this call {@link #hasAltitude} will return true.
	*/		*/
	public void setAltitude(double altitude) {		public void setAltitude(double altitude) {
	mAltitude = altitude;		mAltitude = altitude;
	@@ -572,8 +590,10 @@ public class Location implements Parcelable {
	}		}

	/**		/**
	* Clears the altitude of this fix. Following this call,		* Remove the altitude from this location.
	* hasAltitude() will return false.		*
			* <p>Following this call {@link #hasAltitude} will return false,
			* and {@link #getAltitude} will return 0.0.
	*/		*/
	public void removeAltitude() {		public void removeAltitude() {
	mAltitude = 0.0f;		mAltitude = 0.0f;
	@@ -581,24 +601,25 @@ public class Location implements Parcelable {
	}		}

	/**		/**
	* Returns true if this fix contains speed information, false		* True if this location has a speed.
	* otherwise. The default implementation returns false.
	*/		*/
	public boolean hasSpeed() {		public boolean hasSpeed() {
	return mHasSpeed;		return mHasSpeed;
	}		}

	/**		/**
	* Returns the speed of the device over ground in meters/second.		* Get the speed if it is available, in meters/second over ground.
	* If hasSpeed() is false, 0.0f is returned.		*
			* <p>If this location does not have a speed then 0.0 is returned.
	*/		*/
	public float getSpeed() {		public float getSpeed() {
	return mSpeed;		return mSpeed;
	}		}

	/**		/**
	* Sets the speed of this fix, in meters/second. Following this		* Set the speed, in meters/second over ground.
	* call, hasSpeed() will return true.		*
			* <p>Following this call {@link #hasSpeed} will return true.
	*/		*/
	public void setSpeed(float speed) {		public void setSpeed(float speed) {
	mSpeed = speed;		mSpeed = speed;
	@@ -606,8 +627,10 @@ public class Location implements Parcelable {
	}		}

	/**		/**
	* Clears the speed of this fix. Following this call, hasSpeed()		* Remove the speed from this location.
	* will return false.		*
			* <p>Following this call {@link #hasSpeed} will return false,
			* and {@link #getSpeed} will return 0.0.
	*/		*/
	public void removeSpeed() {		public void removeSpeed() {
	mSpeed = 0.0f;		mSpeed = 0.0f;
	@@ -615,24 +638,32 @@ public class Location implements Parcelable {
	}		}

	/**		/**
	* Returns true if the provider is able to report bearing information,		* True if this location has a bearing.
	* false otherwise. The default implementation returns false.
	*/		*/
	public boolean hasBearing() {		public boolean hasBearing() {
	return mHasBearing;		return mHasBearing;
	}		}

	/**		/**
	* Returns the direction of travel in degrees East of true		* Get the bearing, in degrees.
	* North. If hasBearing() is false, 0.0 is returned.		*
			* <p>Bearing is the horizontal direction of travel of this device,
			* and is not related to the device orientation. It is guaranteed to
			* be in the range (0.0, 360.0] if the device has a bearing.
			*
			* <p>If this location does not have a bearing then 0.0 is returned.
	*/		*/
	public float getBearing() {		public float getBearing() {
	return mBearing;		return mBearing;
	}		}

	/**		/**
	* Sets the bearing of this fix. Following this call, hasBearing()		* Set the bearing, in degrees.
	* will return true.		*
			* <p>Bearing is the horizontal direction of travel of this device,
			* and is not related to the device orientation.
			*
			* <p>The input will be wrapped into the range (0.0, 360.0].
	*/		*/
	public void setBearing(float bearing) {		public void setBearing(float bearing) {
	while (bearing < 0.0f) {		while (bearing < 0.0f) {
	@@ -646,8 +677,10 @@ public class Location implements Parcelable {
	}		}

	/**		/**
	* Clears the bearing of this fix. Following this call, hasBearing()		* Remove the bearing from this location.
	* will return false.		*
			* <p>Following this call {@link #hasBearing} will return false,
			* and {@link #getBearing} will return 0.0.
	*/		*/
	public void removeBearing() {		public void removeBearing() {
	mBearing = 0.0f;		mBearing = 0.0f;
	@@ -655,35 +688,47 @@ public class Location implements Parcelable {
	}		}

	/**		/**
	* Return true if this Location has an associated accuracy.		* True if this location has an accuracy.
	* <p>All Location objects generated by a {@link LocationProvider}		*
	* will have an accuracy.		* <p>All locations generated by the {@link LocationManager} have an
			* accuracy.
	*/		*/
	public boolean hasAccuracy() {		public boolean hasAccuracy() {
	return mHasAccuracy;		return mHasAccuracy;
	}		}

	/**		/**
	* Return the accuracy of this Location fix.		* Get the estimated accuracy of this location, in meters.
	* <p>Accuracy is measured in meters, and indicates the		*
	* radius of 95% confidence.		* <p>We define accuracy as the radius of 68% confidence. In other
	* In other words, there is a 95% probability that the		* words, if you draw a circle centered at this location's
	* true location is within a circle centered at the reported		* latitude and longitude, and with a radius equal to the accuracy,
	* location, with radius of the reported accuracy.		* then there is a 68% probability that the true location is inside
	* <p>This is only a measure of horizontal accuracy, and does		* the circle.
	* not indicate the accuracy of bearing, velocity or altitude		*
	* if those are included in this Location.		* <p>In statistical terms, it is assumed that location errors
	* <p>If {@link #hasAccuracy} is false, 0.0 is returned.		* are random with a normal distribution, so the 68% confidence circle
	* <p>All Location object generated by a {@link LocationProvider}		* represents one standard deviation. Note that in practice, location
	* will have a valid accuracy.		* errors do not always follow such a simple distribution.
			*
			* <p>This accuracy estimation is only concerned with horizontal
			* accuracy, and does not indicate the accuracy of bearing,
			* velocity or altitude if those are included in this Location.
			*
			* <p>If this location does not have an accuracy, then 0.0 is returned.
			* All locations generated by the {@link LocationManager} include
			* an accuracy.
	*/		*/
	public float getAccuracy() {		public float getAccuracy() {
	return mAccuracy;		return mAccuracy;
	}		}

	/**		/**
	* Sets the accuracy of this fix. Following this call, hasAccuracy()		* Set the estimated accuracy of this location, meters.
	* will return true.		*
			* <p>See {@link #getAccuracy} for the definition of accuracy.
			*
			* <p>Following this call {@link #hasAccuracy} will return true.
	*/		*/
	public void setAccuracy(float accuracy) {		public void setAccuracy(float accuracy) {
	mAccuracy = accuracy;		mAccuracy = accuracy;
	@@ -691,8 +736,10 @@ public class Location implements Parcelable {
	}		}

	/**		/**
	* Clears the accuracy of this fix. Following this call, hasAccuracy()		* Remove the accuracy from this location.
	* will return false.		*
			* <p>Following this call {@link #hasAccuracy} will return false, and
			* {@link #getAccuracy} will return 0.0.
	*/		*/
	public void removeAccuracy() {		public void removeAccuracy() {
	mAccuracy = 0.0f;		mAccuracy = 0.0f;
	@@ -700,8 +747,14 @@ public class Location implements Parcelable {
	}		}

	/**		/**
	* Return true if this Location object has enough data set to		* Return true if this Location object is complete.
	* be considered a valid fix from a {@link LocationProvider}.		*
			* <p>A location object is currently considered complete if it has
			* a valid provider, accuracy, wall-clock time and elapsed real-time.
			*
			* <p>All locations supplied by the {@link LocationManager} to
			* applications must be complete.
			*
	* @see #makeComplete		* @see #makeComplete
	* @hide		* @hide
	*/		*/
	@@ -714,9 +767,11 @@ public class Location implements Parcelable {
	}		}

	/**		/**
	* Helper to fill in incomplete fields.		* Helper to fill incomplete fields.
	* Only use this to assist in backwards compatibility		*
	* with Location objects received from applications.		* <p>Used to assist in backwards compatibility with
			* Location objects received from applications.
			*
	* @see #isComplete		* @see #isComplete
	* @hide		* @hide
	*/		*/