javax.microedition.location
Class Location

java.lang.Object
  javax.microedition.location.Location

public class Location

extends Object

The Location class represents the standard set of basic location information. This includes the timestamped coordinates, accuracy, speed, heading, and information about the positioning method used for the location, plus an optional 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. 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. 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. This class is extracted from JSR179

Version:

0.1, 26 march 2003

Author:

donsez

Field Summary

static int	MTA_ASSISTED Location method is assisted by the other party (Terminal assisted for Network based, Network assisted for terminal based).
static int	MTA_UNASSISTED Location method is unassisted.
static int	MTE_ANGLEOFARRIVAL Location method Angle of Arrival for cellular / terrestrial RF system.
static int	MTE_CELLID Location method Cell-ID for cellular (in GSM, this is the same as CGI, Cell Global Identity).
static int	MTE_SATELLITE Location method using satellites (for example, Global Positioning System (GPS)).
static int	MTE_SHORTRANGE Location method Short-range positioning system (for example, Bluetooth LP).
static int	MTE_TIMEDIFFERENCE Location method Time Difference for cellular / terrestrial RF system (for example, Enhanced Observed Time Difference (E-OTD) for GSM).
static int	MTE_TIMEOFARRIVAL Location method Time of Arrival (TOA) for cellular / terrestrial RF system.
static int	MTY_NETWORKBASED Location method is of type network based.
static int	MTY_TERMINALBASED Location method is of type terminal based.

Constructor Summary

Location()

Method Summary

void	addExtraInfo(String mimetype, String extrainfo) Adds a feature to the ExtraInfo attribute of the Location object
QualifiedCoordinates	getCoordinates() Returns the coordinates of this location and their accuracy.
float	getCourse() Returns the terminal's course made good in degrees relative to true north.
String	getExtraInfo(String mimetype) Returns extra information about the location.
int	getLocationMethod() Returns information about the location method used.
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.
void	setCoordinates(QualifiedCoordinates coordinates) Sets the coordinates attribute of the Location object
void	setCourse(float course)
void	setLocationMethod(int locationMethod) Sets the locationMethod attribute of the Location object
void	setSpeed(float speed) Sets the speed attribute of the Location object
void	setTimestamp(long timestamp) Sets the timestamp attribute of the Location object
void	setValid(boolean valid) Sets the valid attribute of the Location object

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MTA_ASSISTED

public static final int MTA_ASSISTED

Location method is assisted by the other party (Terminal assisted for Network based, Network assisted for terminal based).

See Also:

Constant Field Values

MTA_UNASSISTED

public static final int MTA_UNASSISTED

Location method is unassisted.

See Also:

Constant Field Values

MTE_ANGLEOFARRIVAL

public static final int MTE_ANGLEOFARRIVAL

Location method Angle of Arrival for cellular / terrestrial RF system.

See Also:

Constant Field Values

MTE_CELLID

public static final int MTE_CELLID

Location method Cell-ID for cellular (in GSM, this is the same as CGI, Cell Global Identity).

See Also:

Constant Field Values

MTE_SATELLITE

public static final int MTE_SATELLITE

Location method using satellites (for example, Global Positioning System (GPS)).

See Also:

Constant Field Values

MTE_SHORTRANGE

public static final int MTE_SHORTRANGE

Location method Short-range positioning system (for example, Bluetooth LP).

See Also:

Constant Field Values

MTE_TIMEDIFFERENCE

public static final int MTE_TIMEDIFFERENCE

Location method Time Difference for cellular / terrestrial RF system (for example, Enhanced Observed Time Difference (E-OTD) for GSM).

See Also:

Constant Field Values

MTE_TIMEOFARRIVAL

public static final int MTE_TIMEOFARRIVAL

Location method Time of Arrival (TOA) for cellular / terrestrial RF system.

See Also:

Constant Field Values

MTY_NETWORKBASED

public static final int MTY_NETWORKBASED

Location method is of type network based.

See Also:

Constant Field Values

MTY_TERMINALBASED

public static final int MTY_TERMINALBASED

Location method is of type terminal based.

See Also:

Constant Field Values

Constructor Detail

Location

public Location()

Method Detail

getLocationMethod

public int getLocationMethod()

Returns information about the location method used.

Returns:

The locationMethod value

setLocationMethod

public void setLocationMethod(int locationMethod)

Sets the locationMethod attribute of the Location object

Parameters:

locationMethod - The new locationMethod value

getCoordinates

public QualifiedCoordinates getCoordinates()

Returns the coordinates of this location and their accuracy.

Returns:

The coordinates value

setCoordinates

public void setCoordinates(QualifiedCoordinates coordinates)

Sets the coordinates attribute of the Location object

Parameters:

coordinates - The new coordinates value

getSpeed

public float getSpeed()

Returns the terminal's current ground speed in meters per second (m/s) at the time of measurement.

Returns:

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

setSpeed

public void setSpeed(float speed)

Sets the speed attribute of the Location object

Parameters:

speed - The new speed value

getCourse

public 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

setCourse

public void setCourse(float course)

getTimestamp

public long getTimestamp()

Returns the time stamp at which the data was collected.

Returns:

The timestamp value

setTimestamp

public void setTimestamp(long timestamp)

Sets the timestamp attribute of the Location object

Parameters:

timestamp - The new timestamp value

isValid

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

Returns:

The valid value

setValid

public void setValid(boolean valid)

Sets the valid attribute of the Location object

Parameters:

valid - The new valid value

getExtraInfo

public String getExtraInfo(String mimetype)

Returns extra information about the location. This method is intended to provide location method specific extra information that applications that are aware of the used location method and information format are able to use.
A MIME type is used to identify the type of the extra information when requesting it. If the implementation supports this type, it returns the extra information as a String encoded according to format identified by the MIME type. If the implementation does not support this type, the method returns null.
This specification does not require implementations to support any extra information type.
The following MIME types are defined here together with their definitions in order to ensure interoperability of implementations wishing to use these types. The definition of these types here is not an indication that these formats are preferred over any other format not defined here.
When the MIME type is "application/X-java-location-nmea", the returned string shall be a valid sequence of NMEA sentences formatted according to the syntax specified in the NMEA 0183 v3.1 specification. These sentences should represent the set of NMEA sentences that are related to this location at the time this location was created.
When the MIME type is "application/X-java-location-lif", the returned string shall contain an XML formatted document containing the "pd" element defined in the LIF Mobile Location Protocol TS 101 v3.0.0 as the root element of the document.
When the MIME type is "text/plain", the returned string shall contain textual extra information that can be displayed to the end user.

Parameters:

mimetype - the MIME type of the requested extra information

Returns:

string encoded according to the format identified by the MIME type defined in the parameter. null if the information for the requested MIME type is not available or not supported by this implementation.

addExtraInfo

public void addExtraInfo(String mimetype,
                         String extrainfo)

Adds a feature to the ExtraInfo attribute of the Location object

Parameters:

mimetype - The feature to be added to the ExtraInfo attribute

extrainfo - The feature to be added to the ExtraInfo attribute