Package com.esri.arcgisruntime.location

Class LocationDataSource

  • Direct Known Subclasses:
    NmeaLocationDataSource, SimulatedLocationDataSource
    public abstract class LocationDataSource
extends Object
    An abstract data source that provides location updates to the associated MapView's LocationDisplay.
    Since:
    100.0.0 for Android and 100.9.0 for Java SE

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

      • addStartedListener

        @Deprecated
public final void addStartedListener​(Runnable listener)
        Deprecated.
        as of 100.14.0, use the ListenableFuture returned from startAsync() or the StatusChangedListener to get notified when the LocationDataSource has started.
        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

        @Deprecated
public final boolean removeStartedListener​(Runnable listener)
        Deprecated.
        as of 100.14.0, use addStatusChangedListener(StatusChangedListener) to get notified when the LocationDataSource has started.
        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:
        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:
        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:
        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 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.0.0 for Android and 100.9.0 for Java SE

      • 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​(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

        @Deprecated
public final void stop()
        Deprecated.
        as of 100.14.0, use stopAsync() instead.
        Stops the LocationDataSource. This method will call the onStop() method implementation of the subclass.
        Since:
        100.0.0 for Android and 100.9.0 for Java SE

      • stopAsync

        public final ListenableFuture<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() or 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

        @Deprecated
public final boolean isStarted()
        Deprecated.
        as of 100.14.0, use getStatus() to check if the LocationDataSource has started.
        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