Class LocationDataSource

    • 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.0.0 for Android and 100.9.0 for Java SE
    • Method Detail

      • startAsync

        public final void startAsync()
        Asynchronously initializes the location data source and prepares to begin receiving location updates. Calls the onStart() method of a subclass.
        Since:
        100.0.0 for Android and 100.9.0 for Java SE
      • addStartedListener

        public final void addStartedListener​(java.lang.Runnable listener)
        Registers the given Runnable to be called when the location data source has successfully started, or has failed to start. The Runnable is called immediately if this location data source has already started (isStarted() is true).

        You can also use LocationDisplay.addDataSourceStatusChangedListener(LocationDisplay.DataSourceStatusChangedListener)} in order to be notified when the LocationDataSource associated with a LocationDisplay starts or stops.

        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 Runnable to be called when the location data source has started
        Since:
        100.0.0 for Android and 100.9.0 for Java SE
        See Also:
        removeStartedListener(Runnable)
      • removeStartedListener

        public final boolean removeStartedListener​(java.lang.Runnable listener)
        Unregisters the given Runnable that was previously added using addStartedListener(Runnable).
        Parameters:
        listener - the Runnable to unregister
        Returns:
        true if the Runnable was removed successfully; false otherwise
        Since:
        100.0.0 for Android and 100.9.0 for Java SE
      • 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.6.0 for Android and 100.9.0 for Java SE
        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.6.0 for Android and 100.9.0 for Java SE
        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.6.0 for Android and 100.9.0 for Java SE
        See Also:
        removeStatusChangedListener(StatusChangedListener)
      • getError

        public final java.lang.Throwable getError()
        Gets the error generated during the starting process, if the LocationDataSource failed to start. Returns null if it started successfully.
        Returns:
        the error generated during the starting process, or null if it started successfully
        Since:
        100.0.0 for Android and 100.9.0 for Java SE
      • 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.0.0 for Android and 100.9.0 for Java SE
      • 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.0.0 for Android and 100.9.0 for Java SE
      • stop

        public final void stop()
        Stops receiving the location updates. This method will call the onStop() method implementation of the subclass.
        Since:
        100.0.0 for Android and 100.9.0 for Java SE
      • onStop

        protected abstract void onStop()
        Called from the stop() 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.0.0 for Android and 100.9.0 for Java SE
      • 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.0.0 for Android and 100.9.0 for Java SE
      • 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.0.0 for Android and 100.9.0 for Java SE
        See Also:
        LocationDataSource.Location
      • isStarted

        public final boolean isStarted()
        Indicates if this location data source has started successfully. A started LocationDataSource is one that is receiving location updates.
        Returns:
        true if the data source has started successfully; false otherwise
        Since:
        100.0.0 for Android and 100.9.0 for Java SE