Module com.esri.arcgisruntime
Package com.esri.arcgisruntime.location

Class LocationDataSource

java.lang.Object
com.esri.arcgisruntime.location.LocationDataSource
Direct Known Subclasses:
NmeaLocationDataSource, SimulatedLocationDataSource
public abstract class LocationDataSource extends Object
The location data source provides location information that can be displayed on a map using the MapView.locationDisplayProperty().

This is a base class for a number of different location data sources, such as NmeaLocationDataSource and SimulatedLocationDataSource. Call startAsync() to receive location updates and display the current location using the MapView.locationDisplayProperty().

Since:
100.9.0

  • Constructor Details

    • 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 Details

    • 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.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:
      IllegalArgumentException - if listener is null
      Since:
      100.9.0
      See Also:

    • removeLocationChangedListener

      public final boolean removeLocationChangedListener(LocationDataSource.LocationChangedListener listener)
      Unregisters the given listener that was previously added using addLocationChangedListener(LocationChangedListener).
      Parameters:
      listener - the listener to unregister
      Returns:
      true if the listener was removed successfully; false otherwise
      Since:
      100.9.0

    • 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.9.0
      See Also:

    • removeHeadingChangedListener

      public final boolean removeHeadingChangedListener(LocationDataSource.HeadingChangedListener listener)
      Unregisters the given listener that was previously added using addHeadingChangedListener(HeadingChangedListener).
      Parameters:
      listener - the listener to unregister
      Returns:
      true if the listener was removed successfully; false otherwise
      Since:
      100.9.0

    • 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.9.0
      See Also:

    • removeStatusChangedListener

      public final boolean removeStatusChangedListener(LocationDataSource.StatusChangedListener listener)
      Unregisters the given listener that was previously added using addStatusChangedListener(StatusChangedListener).
      Parameters:
      listener - the listener to unregister
      Returns:
      true if the listener was removed successfully; false otherwise
      Since:
      100.9.0

    • 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:
      IllegalArgumentException - if listener is null
      Since:
      100.14.0
      See Also:

    • removeErrorChangedListener

      public final boolean removeErrorChangedListener(LocationDataSource.ErrorChangedListener listener)
      Unregisters the given listener that was previously added using addErrorChangedListener(ErrorChangedListener).
      Parameters:
      listener - the listener to unregister
      Returns:
      true if the listener was removed successfully; false otherwise
      Since:
      100.14.0

    • 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.9.0

    • getStatus

      public final LocationDataSource.Status getStatus()
      Gets the current status of the location data source.

      The status indicates if the location data source is starting, started, stopping, stopped, and has failed to start.

      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.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<Void> stopAsync()
      Stops 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)
      Updates the current heading angle.

      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)
      Updates the position of the current 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: