Package com.esri.arcgisruntime.location

Class AndroidLocationDataSource

java.lang.Object

com.esri.arcgisruntime.location.LocationDataSource

com.esri.arcgisruntime.location.AndroidLocationDataSource

All Implemented Interfaces:

LocationDisplay.AutoPanModeChangedListener

public final class AndroidLocationDataSource
extends LocationDataSource
implements LocationDisplay.AutoPanModeChangedListener

A type of LocationDataSource that requests location updates from the Android platforms location API.

The Android framework's android.location.LocationManager is used to select one or more android.location.LocationProviders based on the parameters passed to the constructor. If both the GPS and the network location providers are disabled, then the AndroidLocationDataSource will fail to start and an IllegalStateException will be returned from LocationDataSource.getError().

To use this class, the app must be granted Location permissions in the Android platform settings.

This class also implements the LocationDisplay.AutoPanModeChangedListener to listen to AutoPanMode change events. When the AutoPanMode is changed to LocationDisplay.AutoPanMode.COMPASS_NAVIGATION mode, the update of heading information is enabled. Heading information is not retrieved by this data source if a different AutoPanMode is set.

Since:

100.0.0

See Also:

LocationDisplay

Nested Class Summary

Nested classes/interfaces inherited from class com.esri.arcgisruntime.location.LocationDataSource

LocationDataSource.ErrorChangedEvent, LocationDataSource.ErrorChangedListener, LocationDataSource.HeadingChangedEvent, LocationDataSource.HeadingChangedListener, LocationDataSource.Location, LocationDataSource.LocationChangedEvent, LocationDataSource.LocationChangedListener, LocationDataSource.Status, LocationDataSource.StatusChangedEvent, LocationDataSource.StatusChangedListener

Constructor Summary

Constructors

Constructor	Description
AndroidLocationDataSource(android.content.Context context)	Creates a new AndroidLocationDataSource with the given Context.
AndroidLocationDataSource(android.content.Context context, android.location.Criteria criteria, long minTime, float minDistance)	Creates a new instance of AndroidLocationDataSource based on the given provider Criteria, with the given minimum update frequency and minimum location distance change.
AndroidLocationDataSource(android.content.Context context, java.lang.String provider, long minTime, float minDistance)	Creates a new instance of AndroidLocationDataSource based on the given provider name, with the given minimum update frequency and minimum location distance change.

Method Summary

Modifier and Type	Method	Description
void	onAutoPanModeChanged(LocationDisplay.AutoPanModeChangedEvent autoPanModeEvent)	Called when the AutoPanMode is changed on the associated LocationDisplay, this method populates the heading (LocationDisplay.getHeading()) on the associated LocationDisplay if the AutoPanMode is changed to LocationDisplay.AutoPanMode.COMPASS_NAVIGATION.
protected void	onStart()	Called when the LocationDataSource is started, by calling LocationDataSource.startAsync(), or indirectly by calling LocationDisplay.startAsync() on the LocationDisplay associated with this data source.
protected void	onStop()	Called when the location data source is stopped, by calling LocationDataSource.stopAsync() or LocationDataSource.stop(), or indirectly by calling LocationDisplay.stop() on the LocationDisplay associated with this data source.
void	requestLocationUpdates(android.location.Criteria criteria, long minTime, float minDistance)	Changes the location update parameters to use the given provider Criteria, minimum update frequency, and minimum location distance change.
void	requestLocationUpdates(java.lang.String provider, long minTime, float minDistance)	Changes the location update parameters to use the given provider name, minimum update frequency, and minimum location distance change.

Methods inherited from class com.esri.arcgisruntime.location.LocationDataSource

addErrorChangedListener, addHeadingChangedListener, addLocationChangedListener, addStartedListener, addStatusChangedListener, getError, getStatus, isStarted, onStartCompleted, removeErrorChangedListener, removeHeadingChangedListener, removeLocationChangedListener, removeStartedListener, removeStatusChangedListener, setLastKnownLocation, startAsync, stop, stopAsync, updateHeading, updateLocation

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AndroidLocationDataSource

public AndroidLocationDataSource(android.content.Context context)

Creates a new AndroidLocationDataSource with the given Context. The platform GPS and network location providers are used, if they are enabled. The minimum time between updates defaults to 100 milliseconds, and the minimum distance between location updates defaults to 0.0 meters.

Parameters:

context - the Context that the MapView of the associated LocationDisplay is running in

Throws:

java.lang.IllegalArgumentException - if context is null

Since:

100.0.0

AndroidLocationDataSource

public AndroidLocationDataSource(android.content.Context context,
                                 android.location.Criteria criteria,
                                 long minTime,
                                 float minDistance)

Creates a new instance of AndroidLocationDataSource based on the given provider Criteria, with the given minimum update frequency and minimum location distance change.

Not all location providers can return all types of location information. Use the criteria parameter to specify what kind of information or properties are required for this AndroidLocationDataSource; for example one that has low power usage, avoids network usage, or that includes bearing or altitude information.

Parameters:

context - the Context that the MapView of the associated LocationDisplay is running in

criteria - the set of requirements that the selected location provider must satisfy

minTime - the minimum time interval at which location updates should be received, in milliseconds

minDistance - the minimum distance between which location updates should be received, in meters

Throws:

java.lang.IllegalArgumentException - if minTime or minDistance is negative

Since:

100.0.0

AndroidLocationDataSource

public AndroidLocationDataSource(android.content.Context context,
                                 java.lang.String provider,
                                 long minTime,
                                 float minDistance)

Creates a new instance of AndroidLocationDataSource based on the given provider name, with the given minimum update frequency and minimum location distance change.

Provider names are defined as constants of the android.location.LocationManager class.

Parameters:

context - the Context that the MapView of the associated LocationDisplay is running in

provider - the name of the underlying Android platform location provider to use, for example 'gps'

minTime - the minimum time interval at which location updates should be received, in milliseconds

minDistance - the minimum distance between which location updates should be received, in meters

Throws:

java.lang.IllegalArgumentException - if minTime or minDistance is negative

Since:

100.0.0

Method Detail

requestLocationUpdates

public void requestLocationUpdates(android.location.Criteria criteria,
                                   long minTime,
                                   float minDistance)

Changes the location update parameters to use the given provider Criteria, minimum update frequency, and minimum location distance change. Applies only when LocationDataSource.isStarted() is true.

Parameters:

criteria - the set of requirements that the selected location provider must satisfy

minTime - the minimum time interval at which location updates should be received, in milliseconds

minDistance - the minimum distance between which location updates should be received, in meters

Throws:

java.lang.IllegalArgumentException - if minTime or minDistance is negative, or criteria is null,or no location provider matches the criteria

java.lang.IllegalStateException - if no location provider is selected by the criteria, or data source is not started

Since:

100.0.0

requestLocationUpdates

public void requestLocationUpdates(java.lang.String provider,
                                   long minTime,
                                   float minDistance)

Changes the location update parameters to use the given provider name, minimum update frequency, and minimum location distance change. Applies only when LocationDataSource.isStarted() is true.

Parameters:

provider - the name of the underlying Android platform location provider to use, for example 'gps'

minTime - the minimum time interval at which location updates should be received, in milliseconds

minDistance - the minimum distance of location change at which location updates should be received, in meters

Throws:

java.lang.IllegalArgumentException - if minTime or minDistance is negative, or criteria is null

java.lang.IllegalStateException - the specified location provider is not found in the location manager, or data source is not started

Since:

100.0.0

onStart

protected void onStart()

Called when the LocationDataSource is started, by calling LocationDataSource.startAsync(), or indirectly by calling LocationDisplay.startAsync() on the LocationDisplay associated with this data source.

This method requests that location updates are received from the underlying Android platform location providers; if there is an error starting the location providers, it will be passed to LocationDataSource.onStartCompleted(Throwable).

Specified by:

onStart in class LocationDataSource

Since:

100.0.0

onStop

protected void onStop()

Called when the location data source is stopped, by calling LocationDataSource.stopAsync() or LocationDataSource.stop(), or indirectly by calling LocationDisplay.stop() on the LocationDisplay associated with this data source.

This method requests that location updates stop being received from the underlying Android platform location providers.

Specified by:

onStop in class LocationDataSource

Since:

100.0.0

onAutoPanModeChanged

public final void onAutoPanModeChanged(LocationDisplay.AutoPanModeChangedEvent autoPanModeEvent)

Called when the AutoPanMode is changed on the associated LocationDisplay, this method populates the heading (LocationDisplay.getHeading()) on the associated LocationDisplay if the AutoPanMode is changed to LocationDisplay.AutoPanMode.COMPASS_NAVIGATION.

Specified by:

onAutoPanModeChanged in interface LocationDisplay.AutoPanModeChangedListener

Parameters:

autoPanModeEvent - event indicating the new AutoPanMode and the LocationDisplay that raised the event

Since:

100.0.0