org.j4me.bluetoothgps
Interface Location


public interface Location

The Location class represents the standard set of basic location information. This includes the timestamped coordinates, accuracy, speed, course, and information about the positioning method used for the location, plus an optional textual address.

The location method is indicated using a bit field. The individual bits are defined using constants in this class. This bit field is a bitwise combination of the location method technology bits (MTE_*), method type (MTY_*) and method assistance information (MTA_*). All other bits in the 32 bit integer than those that have defined constants in this class are reserved and MUST not be set by implementations (i.e. these bits must be 0).

A Location object may be either 'valid' or 'invalid'. The validity can be queried using the isValid method. A valid Location object represents a location with valid coordinates and the getQualifiedCoordinates method must return their coordinates. An invalid Location object doesn't have valid coordinates, but the extra info that is obtained from the getExtraInfo method can provide information about the reason why it was not possible to provide a valid Location. For an invalid Location object, the getQualifiedCoordinates method may return either null or some coordinates where the information is not necessarily fully correct. The periodic location updates to the LocationListener may return invalid Location objects if it isn't possible to determine the location.

This class is only a container for the information. When the platform implementation returns Location objects, it MUST ensure that it only returns objects where the parameters have values set as described for their semantics in this class.


Method Summary
 float getCourse()
          Returns the terminal's course made good in degrees relative to true north.
 QualifiedCoordinates getQualifiedCoordinates()
          Returns the coordinates of this location and their accuracy.
 float getSpeed()
          Returns the terminal's current ground speed in meters per second (m/s) at the time of measurement.
 long getTimestamp()
          Returns the time stamp at which the data was collected.
 boolean isValid()
          Returns whether this Location instance represents a valid location with coordinates or an invalid one where all the data, especially the latitude and longitude coordinates, may not be present.
 

Method Detail

getQualifiedCoordinates

QualifiedCoordinates getQualifiedCoordinates()
Returns the coordinates of this location and their accuracy.

Returns:
a QualifiedCoordinates object. If the coordinates are not known, returns null.

getSpeed

float getSpeed()
Returns the terminal's current ground speed in meters per second (m/s) at the time of measurement. The speed is always a non-negative value. Note that unlike the coordinates, speed does not have an associated accuracy because the methods used to determine the speed typically are not able to indicate the accuracy.

Returns:
the current ground speed in m/s for the terminal or Float.NaN if the speed is not known

getCourse

float getCourse()
Returns the terminal's course made good in degrees relative to true north. The value is always in the range [0.0,360.0) degrees.

Returns:
the terminal's course made good in degrees relative to true north or Float.NaN if the course is not known

getTimestamp

long getTimestamp()
Returns the time stamp at which the data was collected. This timestamp should represent the point in time when the measurements were made. Implementations make best effort to set the timestamp as close to this point in time as possible. The time returned is the time of the local clock in the terminal in milliseconds using the same clock and same time representation as System.currentTimeMillis().

Returns:
a timestamp representing the time
See Also:
System.currentTimeMillis()

isValid

boolean isValid()
Returns whether this Location instance represents a valid location with coordinates or an invalid one where all the data, especially the latitude and longitude coordinates, may not be present. A valid Location object contains valid coordinates whereas an invalid Location object may not contain valid coordinates but may contain other information via the getExtraInfo() method to provide information on why it was not possible to provide a valid Location object.

Returns:
a boolean value with true indicating that this Location instance is valid and false indicating an invalid Location instance