Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.microedition.location
Class Location

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

public class Location
extends java.lang.Object

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 is related only to the coordinates of the Location object. It is not tight anymore to the criteria that was possibly used to retrieve a location provider. 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 there coordinates. An invalid Location object does not have valid coordinates, but the extra info and possible error code that are obtained from the getExtraInfo and getErrorCode methods 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.

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_INERTIALNAVIGATION
          Location method inertial navigation (dead reckoning)
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
protected Location()
          A protected constructor for the Location to allow implementations of LocationProviders to construct the Location instances.
 
Method Summary
 AddressInfo getAddressInfo()
          Returns the AddressInfo associated with this Location object.
 float getCourse()
          Returns the terminal's course made good in degrees relative to true north.
 java.lang.String getErrorCode()
          If the location information is not valid, this method returns the error code that may indicate the reason the invalid location information.
 java.lang.String getExtraInfo(java.lang.String mimetype)
          Returns extra information about the location.
 int getLocationMethod()
          Returns information about the location method used.
 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 timestamp 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.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

MTE_SATELLITE

public static final int MTE_SATELLITE

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

MTE_SATELLITE = 0x00000001

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

MTE_TIMEDIFFERENCE = 0x00000002

See Also:
Constant Field Values

MTE_TIMEOFARRIVAL

public static final int MTE_TIMEOFARRIVAL

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

MTE_TIMEOFARRIVAL = 0x00000004

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

MTE_CELLID = 0x00000008

See Also:
Constant Field Values

MTE_SHORTRANGE

public static final int MTE_SHORTRANGE

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

MTE_SHORTRANGE = 0x00000010

See Also:
Constant Field Values

MTE_ANGLEOFARRIVAL

public static final int MTE_ANGLEOFARRIVAL

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

MTE_ANGLEOFARRIVAL = 0x00000020

See Also:
Constant Field Values

MTE_INERTIALNAVIGATION

public static final int MTE_INERTIALNAVIGATION

Location method inertial navigation (dead reckoning)

MTE_INERTIALNAVIGATION = 0x00000040

Since:
2.0
See Also:
Constant Field Values

MTY_TERMINALBASED

public static final int MTY_TERMINALBASED

Location method is of type terminal based. This means that the final location result is calculated in the terminal. This bit and MTY_NETWORKBASED bit must not both be set. Only one of these bits may be set or neither to indicate that it is not known where the result is calculated.

MTY_TERMINALBASED = 0x00010000

See Also:
Constant Field Values

MTY_NETWORKBASED

public static final int MTY_NETWORKBASED

Location method is of type network based. This means that the final location result is calculated in the network. This bit and MTY_TERMINALBASED bit must not both be set. Only one of these bits may be set or neither to indicate that it is not known where the result is calculated.

MTY_NETWORKBASED = 0x00020000

See Also:
Constant Field Values

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). This bit and MTA_UNASSISTED bit must not both be set. Only one of these bits may be set or neither to indicate that the assistance information is not known.

MTA_ASSISTED = 0x00040000

See Also:
Constant Field Values

MTA_UNASSISTED

public static final int MTA_UNASSISTED

Location method is unassisted. This bit and MTA_ASSISTED bit must not both be set. Only one of these bits may be set or neither to indicate that the assistance information is not known.

MTA_UNASSISTED = 0x00080000

See Also:
Constant Field Values
Constructor Detail

Location

protected Location()

A protected constructor for the Location to allow implementations of LocationProviders to construct the Location instances.

This method is not intended to be used by applications.

This constructor sets the fields to implementation specific default values. Location providers are expected to set the fields to the correct values after constructing the object instance.

Method Detail

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.

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. If the Location object contains invalid coordinates, the getErrorCode method should return related error code.

Returns:
a boolean value with true indicating that this Location instance is valid and false indicating an invalid Location instance
See Also:
getExtraInfo(String), getErrorCode()

getTimestamp

public long getTimestamp()

Returns the timestamp 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

getQualifiedCoordinates

public QualifiedCoordinates getQualifiedCoordinates()

Returns the coordinates of this location and their accuracy.

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

getSpeed

public 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

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

getLocationMethod

public int getLocationMethod()

Returns information about the location method used. The returned value is a bitwise combination (OR) of the method technology, method type and assistance information. The method technology values are defined as constant values named MTE_* in this class, the method type values are named MTY_* and assistance information values are named MTA_*.

For example, if the location method used is terminal based, network assisted E-OTD, the value 0x00050002 ( = MTY_TERMINALBASED | MTA_ASSISTED | MTE_TIMEDIFFERENCE) would be returned.

If the location is determined by combining several location technologies, the returned value may have several MTE_* bits set. If location technology is known, meaning at least one MTE_* bit is set, one MTY_* and one MTA_* bit must be set.

If the used location method is unknown, the returned value must have all the bits set to zero.

Only bits that have defined constants within this class are allowed to be used. Other bits are reserved and must be set to 0.

Returns:
a bitfield identifying the used location method

getAddressInfo

public AddressInfo getAddressInfo()

Returns the AddressInfo associated with this Location object. If no address is available, null is returned.

Returns:
an AddressInfo associated with this Location object

getExtraInfo

public java.lang.String getExtraInfo(java.lang.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-jsr179-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 [NMEA]. These sentences shall 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-jsr179-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 [MLP] 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.

getErrorCode

public java.lang.String getErrorCode()

If the location information is not valid, this method returns the error code that may indicate the reason the invalid location information. The error codes are platform specific and the ones listed here are only examples.

Example error codes:

If location is valid, null is returned

Returns:
the error code for invalid location, null if location is valid
Since:
2.0
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Copyright © 2003-2008 Nokia Corporation. All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.