Class LocationDataSource.Location
- Direct Known Subclasses:
NmeaLocationDataSource.NmeaLocation
- Enclosing class:
LocationDataSource
Point
representing a
geographical location, and attributes of location change such as the course (direction of travel), and the velocity
(speed of location change).
Also provides information about the accuracy of the location - the possible difference between the true ground
location and that reported by the data source from getPosition()
.
- Since:
- 100.9.0
-
Field Summary
Modifier and TypeFieldDescriptionstatic final String
The key to use withgetAdditionalSourceProperties()
to retrieve the determined floor used to create the Location object.static final String
The key to use with theMap
returned bygetAdditionalSourceProperties()
to retrieve a String that indicates the source provider of the location.static final String
The key to use with theMap
returned bygetAdditionalSourceProperties()
to retrieve the number of satellites used to create the Location object.static final String
The key to use withgetAdditionalSourceProperties()
to retrieve the number of transmitters (iBeacons) used to create the Location object.static final String
Value associated with the keyKEY_POSITION_SOURCE
when location data is acquired from a wireless (Bluetooth) network.static final String
Value associated with the keyKEY_POSITION_SOURCE
when location data is acquired from a cellular network.static final String
Value associated with the keyKEY_POSITION_SOURCE
when location data is acquired from gps.static final String
Value associated with the keyKEY_POSITION_SOURCE
when location data is acquired from a wireless local network. -
Constructor Summary
ConstructorDescriptionCreates a new Location with given Point.Location
(Point position, double horizontalAccuracy, double velocity, double course, boolean lastKnown) Creates a new Location with given Point, accuracy, velocity, course, and whether the location represents a last known location or not.Location
(Point position, double horizontalAccuracy, double verticalAccuracy, double velocity, double course, boolean lastKnown, Calendar timeStamp) Creates a new location with the given Point, horizontal accuracy, vertical accuracy, velocity, course, whether the location represents a last known location or not, and timeStamp.Location
(Point position, double horizontalAccuracy, double verticalAccuracy, double velocity, double course, boolean lastKnown, Calendar timeStamp, Map<String, Object> additionalSourceProperties) Creates a location object with timestamp and additional source properties. -
Method Summary
Modifier and TypeMethodDescriptionGets a set of unmodifiable key-value pairs providing additional meta-data and properties about the source of thisLocationDataSource.Location
.double
Returns the course of the location in degrees clockwise, 0 being true North.double
Returns the horizontal accuracy of the location in meters.A Point representing the geographical position of the Location, defined in the spatial reference used by this LocationDataSource.Gets the date and time the location was determined.double
Returns the velocity of the location in meters per seconds.double
Gets the vertical accuracy of the location in meters.boolean
Indicates whether this is an outdated position retrieved and cached earlier (last known position) and therefore not guaranteed to represent the current location.
-
Field Details
-
POSITION_SOURCE_GNSS
Value associated with the keyKEY_POSITION_SOURCE
when location data is acquired from gps.- Since:
- 100.10.0
- See Also:
-
POSITION_SOURCE_WIFI
Value associated with the keyKEY_POSITION_SOURCE
when location data is acquired from a wireless local network.- Since:
- 100.10.0
- See Also:
-
POSITION_SOURCE_CELL
Value associated with the keyKEY_POSITION_SOURCE
when location data is acquired from a cellular network.- Since:
- 100.10.0
- See Also:
-
POSITION_SOURCE_BLUETOOTH
Value associated with the keyKEY_POSITION_SOURCE
when location data is acquired from a wireless (Bluetooth) network.- Since:
- 100.14.0
- See Also:
-
KEY_POSITION_SOURCE
The key to use with theMap
returned bygetAdditionalSourceProperties()
to retrieve a String that indicates the source provider of the location. If the key is present in theMap
, the associated value will be one of:-
POSITION_SOURCE_GNSS
. GNSS indicates global navigation satellite system. -
POSITION_SOURCE_WIFI
-
POSITION_SOURCE_CELL
-
POSITION_SOURCE_BLUETOOTH
KEY_POSITION_SOURCE
is a concatenated String of comma-separated values.- Since:
- 100.10.0
-
-
KEY_SATELLITE_COUNT
The key to use with theMap
returned bygetAdditionalSourceProperties()
to retrieve the number of satellites used to create the Location object.- Since:
- 100.10.0
-
KEY_FLOOR
The key to use withgetAdditionalSourceProperties()
to retrieve the determined floor used to create the Location object.- Since:
- 100.14.0
-
KEY_TRANSMITTER_COUNT
The key to use withgetAdditionalSourceProperties()
to retrieve the number of transmitters (iBeacons) used to create the Location object.- Since:
- 100.14.0
-
-
Constructor Details
-
Location
Creates a new Location with given Point. Other properties will have default values.- Parameters:
position
- a Point object representing the geographical position of the new Location- Throws:
IllegalArgumentException
- if position is null or the spatial reference of position is null- Since:
- 100.9.0
-
Location
public Location(Point position, double horizontalAccuracy, double velocity, double course, boolean lastKnown) Creates a new Location with given Point, accuracy, velocity, course, and whether the location represents a last known location or not.- Parameters:
position
- a Point object representing the geographical position of the new LocationhorizontalAccuracy
- the horizontal accuracy of the new locationvelocity
- the current speed of the locations movementcourse
- the current direction of the locations movementlastKnown
- Indicates whether this is an outdated position retrieved and cached earlier (last known position) and therefore not guaranteed to represent the current location. True if the location represents a last known position; false if the position information is current. Setting this to true will render with theLocationDisplay.getAcquiringSymbol()
, typically a grayed out location symbol.- Throws:
IllegalArgumentException
- if position is null or the spatial reference of position is null- Since:
- 100.9.0
-
Location
public Location(Point position, double horizontalAccuracy, double verticalAccuracy, double velocity, double course, boolean lastKnown, Calendar timeStamp) Creates a new location with the given Point, horizontal accuracy, vertical accuracy, velocity, course, whether the location represents a last known location or not, and timeStamp.- Parameters:
position
- a Point object representing the geographical position of the new LocationhorizontalAccuracy
- the horizontal accuracy in metersverticalAccuracy
- the vertical accuracy in metersvelocity
- the current speed of the locations movement in meters per secondcourse
- the location's course in degrees (clockwise), 0 being true NorthlastKnown
- Indicates whether this is an outdated position retrieved and cached earlier (last known position) and therefore not guaranteed to represent the current location. True if the location represents a last known position; false if the position information is current. Setting this to true will render with theLocationDisplay.getAcquiringSymbol()
, typically a grayed out location symbol.timeStamp
- the date and time the location was determined- Throws:
IllegalArgumentException
- if position is null or the spatial reference of position is null- Since:
- 100.9.0
-
Location
public Location(Point position, double horizontalAccuracy, double verticalAccuracy, double velocity, double course, boolean lastKnown, Calendar timeStamp, Map<String, Object> additionalSourceProperties) Creates a location object with timestamp and additional source properties.A
Location
can be created from a variety of sources and using different technologies. By supplyingadditionalSourceProperties
you can allow users of thisLocation
to find out how the data was captured. Information should be provided to {additionalSourceProperties
} as a set of key-value pairs, where theString
key describes the type of data held in theObject
value. Values MUST be basic data types such as string, floating point, integer, boolean or date. You can use any string for the key — but this API recognizes a number of well known keys, which include:- "satelliteCount" key; use
KEY_SATELLITE_COUNT
. Associated value, an integer, is the number of satellites used to fix theLocation
. - "positionSource" key; use
KEY_POSITION_SOURCE
. Associated value, a String, can be:POSITION_SOURCE_GNSS
,POSITION_SOURCE_WIFI
,POSITION_SOURCE_CELL
, orPOSITION_SOURCE_BLUETOOTH
. (GNSS indicates global navigation satellite system.) It is possible to have multiple position sources. In that case, the associated value ofKEY_POSITION_SOURCE
is a concatenated String of comma-separated values. - "transmitterCount" key; use
KEY_TRANSMITTER_COUNT
. The number of transmitters used to fix theLocation
. - "floor" key; use
KEY_FLOOR
. The floor used to fix theLocation
.
Keys are case-sensitive.
- Parameters:
position
- a Point object representing the geographical position of the new LocationhorizontalAccuracy
- the horizontal accuracy in metersverticalAccuracy
- the vertical accuracy in metersvelocity
- the current speed of the locations movement in meters per secondcourse
- the location's course in degrees (clockwise), 0 being true NorthlastKnown
- Indicates whether this is an outdated position retrieved and cached earlier (last known position) and therefore not guaranteed to represent the current location. True if the location represents a last known position; false if the position information is current. Setting this to true will render with theLocationDisplay.getAcquiringSymbol()
, typically a grayed out location symbol.timeStamp
- a timestamp when location was received. Can be nulladditionalSourceProperties
- a set of key-value pairs providing additional meta-data and properties about the source of this Location- Throws:
IllegalArgumentException
- if position is null or the spatial reference of position is nullIllegalArgumentException
- if additionalSourceProperties is null- Since:
- 100.10.0
- See Also:
- "satelliteCount" key; use
-
-
Method Details
-
getAdditionalSourceProperties
Gets a set of unmodifiable key-value pairs providing additional meta-data and properties about the source of thisLocationDataSource.Location
.A
Location
object can be created manually or by a variety ofLocationDataSource
types - for example from the default platform data source or external GPS. When user code receives a newLocation
, it can be important to determine how the information was obtained.These
additionalSourceProperties()
provide a means for the creator of aLocation
object to record flexible information such as:- The confidence level associated with the location.
- The method used to obtain the location.
- The provenance of the location.
String
key describes the type of data held in theObject
value. Values MUST be basic data types such as string, numeric, boolean or date. The creator of theLocation
can use any string for the key - but this API recognizes a number of well known keys, which include:- "satelliteCount" key; use
KEY_SATELLITE_COUNT
. Associated value, an integer, is the number of satellites used to fix theLocation
. - "positionSource" key; use
KEY_POSITION_SOURCE
. Associated value, a String, can be:POSITION_SOURCE_GNSS
,POSITION_SOURCE_WIFI
,POSITION_SOURCE_CELL
, orPOSITION_SOURCE_BLUETOOTH
. (GNSS indicates global navigation satellite system.) It is possible to have multiple position sources. In that case, the associated value ofKEY_POSITION_SOURCE
is a concatenated String of comma-separated values. - "transmitterCount" key; use
KEY_TRANSMITTER_COUNT
. The number of transmitters used to fix theLocation
. - "floor" key; use
KEY_FLOOR
. The floor used to fix theLocation
.
- Returns:
- a set of key-value pairs providing additional meta-data and properties about the source of this
Location
- Since:
- 100.10.0
-
getTimeStamp
Gets the date and time the location was determined.- Returns:
- a Calendar object representing the time the location was determined
- Since:
- 100.9.0
-
getCourse
public double getCourse()Returns the course of the location in degrees clockwise, 0 being true North.- Returns:
- a double value representing the direction the device is moving, in degrees clockwise from north
- Since:
- 100.9.0
-
getHorizontalAccuracy
public double getHorizontalAccuracy()Returns the horizontal accuracy of the location in meters.- Returns:
- the accuracy of the reported location, in meters
- Since:
- 100.9.0
-
getVerticalAccuracy
public double getVerticalAccuracy()Gets the vertical accuracy of the location in meters.- Returns:
- the vertical accuracy of the location in meters, Double.NaN if no vertical accuracy is available for the location.
- Since:
- 100.3.0
-
getVelocity
public double getVelocity()Returns the velocity of the location in meters per seconds. Default value is 0.0.- Returns:
- the current speed of the locations movement
- Since:
- 100.9.0
-
getPosition
A Point representing the geographical position of the Location, defined in the spatial reference used by this LocationDataSource.You can find out which spatial reference is used by calling
getPosition()
.- Returns:
- the geographical position of the Location
- Since:
- 100.9.0
-
isLastKnown
public boolean isLastKnown()Indicates whether this is an outdated position retrieved and cached earlier (last known position) and therefore not guaranteed to represent the current location. True if the location represents a last known position; false if the position information is current. Default value is false if this object was created by theLocation(Point)
constructor.For many types of location provider, it may take a while to receive the first location update. Last known locations can provide a suitable surrogate until current location information can be retrieved.
- Returns:
- true if this location represents a last known position; false if the location is current
- Since:
- 100.9.0
-