Class LocationDataSource

  • Direct Known Subclasses:
    NmeaLocationDataSource, SimulatedLocationDataSource

    public abstract class LocationDataSource
    extends java.lang.Object
    An abstract data source that provides location updates to the associated MapView's LocationDisplay.
    Since:
    100.9.0
    • Constructor Detail

      • LocationDataSource

        public LocationDataSource()
        Creates a default LocationDataSource, and sets up the status changed listeners. This method should be called by the subclass constructor before performing other work.
        Since:
        100.9.0
    • Method Detail

      • startAsync

        public final ListenableFuture<java.lang.Void> startAsync()
        Asynchronously initializes the location data source and prepares to begin receiving location updates. Calls the onStart() method of a subclass.
        Returns:
        a ListenableFuture indicating when the LocationDataSource has started.
        Since:
        100.9.0
      • addLocationChangedListener

        public final void addLocationChangedListener​(LocationDataSource.LocationChangedListener listener)
        Registers the given listener to be called when the location has changed.

        This listener will be invoked on the UI thread if it is added from the UI thread, otherwise it is not guaranteed on which thread the listener is invoked.

        Parameters:
        listener - a listener to be called when the location has changed
        Throws:
        java.lang.IllegalArgumentException - if listener is null
        Since:
        100.9.0
        See Also:
        removeLocationChangedListener(LocationChangedListener)
      • addHeadingChangedListener

        public final void addHeadingChangedListener​(LocationDataSource.HeadingChangedListener listener)
        Registers the given listener to be called when the heading has changed.

        This listener will be invoked on the UI thread if it is added from the UI thread, otherwise it is not guaranteed on which thread the listener is invoked.

        Parameters:
        listener - a listener to be called when the heading has changed
        Throws:
        java.lang.IllegalArgumentException - if listener is null
        Since:
        100.9.0
        See Also:
        removeHeadingChangedListener(HeadingChangedListener)
      • addStatusChangedListener

        public final void addStatusChangedListener​(LocationDataSource.StatusChangedListener listener)
        Registers the given listener to be called when the status has changed.

        This listener will be invoked on the UI thread if it is added from the UI thread, otherwise it is not guaranteed on which thread the listener is invoked.

        Parameters:
        listener - a listener to be called when the status has changed
        Throws:
        java.lang.IllegalArgumentException - if listener is null
        Since:
        100.9.0
        See Also:
        removeStatusChangedListener(StatusChangedListener)
      • addErrorChangedListener

        public final void addErrorChangedListener​(LocationDataSource.ErrorChangedListener listener)
        Registers the given listener to be called when the error property has changed.

        This listener will be invoked on the UI thread if it is added from the UI thread, otherwise it is not guaranteed on which thread the listener is invoked.

        Parameters:
        listener - a listener to be called when the error has changed
        Throws:
        java.lang.IllegalArgumentException - if listener is null
        Since:
        100.14.0
        See Also:
        removeErrorChangedListener(ErrorChangedListener)
      • getError

        public final java.lang.Throwable getError()
        Gets an error that describes a problem encountered while starting or running the LocationDataSource.

        This property is used to notify the user about errors that occur in LocationDataSource. Such errors are critical for LocationDataSource and will cause it to stop. If LocationDataSource cannot be started, or it stopped after a successful start, this property will store information related to what caused LocationDataSource to stop.

        Returns:
        an error that describes a problem encountered while starting or running the LocationDataSource, or null if none
        Since:
        100.9.0
      • getStatus

        public final LocationDataSource.Status getStatus()
        Gets the status of the LocationDataSource.
        Returns:
        the current status of the LocationDataSource
        Since:
        100.14.0
      • onStartCompleted

        protected final void onStartCompleted​(java.lang.Throwable throwable)
        Sets the result status of the starting process, and any error generated during it. This method must be called by the subclass once the location data source has finished its starting process.
        Parameters:
        throwable - the error generated during the starting process, or null if it started successfully
        Since:
        100.9.0
      • setLastKnownLocation

        protected final void setLastKnownLocation​(LocationDataSource.Location location)
        Sets the last known Location, which will be displayed as soon as the data source has been started, until a new location update is received.

        The last known location may not accurately represent the true current location, but indicates to the user that the LocationDataSource is waiting for updated location data. It will be displayed using the LocationDisplay.getAcquiringSymbol().

        Parameters:
        location - the last known location
      • onStart

        protected abstract void onStart()
        Called from startAsync(). Subclasses should implement this method to prepare for starting the data source. The onStartCompleted(Throwable) method must be called by the subclass once the location data source has finished its starting process.
        Since:
        100.9.0
      • stopAsync

        public final ListenableFuture<java.lang.Void> stopAsync()
        Stop the location data source asynchronously. This method will call the onStop() method implementation of the subclass.
        Returns:
        a ListenableFuture indicating when the LocationDataSource has stopped.
        Since:
        100.14.0
      • onStop

        protected abstract void onStop()
        Called from the stopAsync() method, subclasses should perform any necessary clean-up in this method; for example, stop streaming the location data, release resources, and so on.
        Since:
        100.9.0
      • updateHeading

        protected final void updateHeading​(double heading)
        Called when the data source has a new heading value. The LocationDisplay.getHeading() associated with this LocationDataSource will be updated with this value and any HeadingChangedListener added will also be notified.
        Parameters:
        heading - the heading angle, in degrees clockwise, relative to north
        Since:
        100.9.0
      • updateLocation

        protected final void updateLocation​(LocationDataSource.Location location)
        Called when the data source has new location information. The LocationDisplay.getLocation() associated with this LocationDataSource will be updated with this value and any LocationChangedListener added will also be notified.
        Parameters:
        location - the updated Location
        Since:
        100.9.0
        See Also:
        LocationDataSource.Location