Class LocationDataSource.Location

  • Direct Known Subclasses:
    NmeaLocationDataSource.NmeaLocation
    Enclosing class:
    LocationDataSource

    public static class LocationDataSource.Location
    extends java.lang.Object
    A location update provided by a LocationDataSource, consisting primarily of a 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.0.0 for Android and 100.9.0 for Java SE
    • Constructor Summary

      Constructors 
      Constructor Description
      Location​(Point position)
      Creates 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, java.util.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, java.util.Calendar timeStamp, java.util.Map<java.lang.String,​java.lang.Object> additionalSourceProperties)
      Creates a location object with timestamp and additional source properties.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.util.Map<java.lang.String,​java.lang.Object> getAdditionalSourceProperties()
      Gets a set of unmodifiable key-value pairs providing additional meta-data and properties about the source of this LocationDataSource.Location.
      double getCourse()
      Returns the course of the location in degrees clockwise, 0 being true North.
      double getHorizontalAccuracy()
      Returns the horizontal accuracy of the location in meters.
      Point getPosition()
      A Point representing the geographical position of the Location, defined in the spatial reference used by this LocationDataSource.
      java.util.Calendar getTimeStamp()
      Gets the date and time the location was determined.
      double getVelocity()
      Returns the velocity of the location in meters per seconds.
      double getVerticalAccuracy()
      Gets the vertical accuracy of the location in meters.
      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.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • Location

        public Location​(Point position)
        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:
        java.lang.IllegalArgumentException - if position is null or the spatial reference of position is null
        Since:
        100.0.0 for Android and 100.9.0 for Java SE
      • 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 Location
        horizontalAccuracy - the horizontal accuracy of the new location
        velocity - the current speed of the locations movement
        course - the current direction of the locations movement
        lastKnown - 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 the LocationDisplay.getAcquiringSymbol(), typically a grayed out location symbol.
        Throws:
        java.lang.IllegalArgumentException - if position is null or the spatial reference of position is null
        Since:
        100.0.0 for Android and 100.9.0 for Java SE
      • Location

        public Location​(Point position,
                        double horizontalAccuracy,
                        double verticalAccuracy,
                        double velocity,
                        double course,
                        boolean lastKnown,
                        java.util.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 Location
        horizontalAccuracy - the horizontal accuracy in meters
        verticalAccuracy - the vertical accuracy in meters
        velocity - the current speed of the locations movement in meters per second
        course - the location's course in degrees (clockwise), 0 being true North
        lastKnown - 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 the LocationDisplay.getAcquiringSymbol(), typically a grayed out location symbol.
        timeStamp - the date and time the location was determined
        Throws:
        java.lang.IllegalArgumentException - if position is null or the spatial reference of position is null
        Since:
        100.4.0 for Android and 100.9.0 for Java SE
      • Location

        public Location​(Point position,
                        double horizontalAccuracy,
                        double verticalAccuracy,
                        double velocity,
                        double course,
                        boolean lastKnown,
                        java.util.Calendar timeStamp,
                        java.util.Map<java.lang.String,​java.lang.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 supplying additionalSourceProperties you can allow users of this Location to find out how the data was captured. Information should be provided to {additionalSourceProperties} as a set of key-value pairs, where the String key describes the type of data held in the Object 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 the Runtime SDK recognizes a number of well known keys, which include:

        Keys are case-sensitive.

        Parameters:
        position - a Point object representing the geographical position of the new Location
        horizontalAccuracy - the horizontal accuracy in meters
        verticalAccuracy - the vertical accuracy in meters
        velocity - the current speed of the locations movement in meters per second
        course - the location's course in degrees (clockwise), 0 being true North
        lastKnown - 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 the LocationDisplay.getAcquiringSymbol(), typically a grayed out location symbol.
        timeStamp - a timestamp when location was received. Can be null
        additionalSourceProperties - a set of key-value pairs providing additional meta-data and properties about the source of this Location
        Throws:
        java.lang.IllegalArgumentException - if position is null or the spatial reference of position is null
        java.lang.IllegalArgumentException - if additionalSourceProperties is null
        Since:
        100.10.0
        See Also:
        getAdditionalSourceProperties(), KEY_SATELLITE_COUNT, KEY_POSITION_SOURCE
    • Method Detail

      • getAdditionalSourceProperties

        public java.util.Map<java.lang.String,​java.lang.Object> getAdditionalSourceProperties()
        Gets a set of unmodifiable key-value pairs providing additional meta-data and properties about the source of this LocationDataSource.Location.

        A Location object can be created manually or by a variety of LocationDataSource types - for example from the default platform data source or external GPS. When user code receives a new Location, it can be important to determine how the information was obtained.

        In addition, mobile devices may provide different details about their in-built location services. For example, Android systems can provide data on the number of satellites used to find a position. When a given property is not available to the data source, the entry will be omitted from the additionalSourceProperties.

        These additionalSourceProperties() provide a means for the creator of a Location 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.
        Information is provided as a set of key-value pairs, where the String key describes the type of data held in the Object value. Values MUST be basic data types such as string, numeric, boolean or date. The creator of the Location can use any string for the key - but the Runtime SDK recognizes a number of well known keys, which include: Keys are case-sensitive.
        Returns:
        a set of key-value pairs providing additional meta-data and properties about the source of this Location
        Since:
        100.10.0
      • getTimeStamp

        public java.util.Calendar getTimeStamp()
        Gets the date and time the location was determined.
        Returns:
        a Calendar object representing the time the location was determined
        Since:
        100.4.0 for Android and 100.9.0 for Java SE
      • 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.0.0 for Android and 100.9.0 for Java SE
      • getHorizontalAccuracy

        public double getHorizontalAccuracy()
        Returns the horizontal accuracy of the location in meters.
        Returns:
        the accuracy of the reported location, in meters
        Since:
        100.0.0 for Android and 100.9.0 for Java SE
      • 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.0.0 for Android and 100.9.0 for Java SE
      • getPosition

        public Point 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.0.0 for Android and 100.9.0 for Java SE
      • 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 the Location(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.0.0 for Android and 100.9.0 for Java SE