com.mapquest.navigation.location

Class LocationProviderAdapter

java.lang.Object

com.mapquest.navigation.location.LocationProviderAdapter

public abstract class LocationProviderAdapter
extends java.lang.Object

Provides an interface through which locations can be requested without depending directly on specific implementations, such as Android's LocationService, Google's Fused Location Provider or other 3rd party options like Skyhood XPS.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	LocationProviderAdapter.LocationAcquisitionListener Callback for when the device's location has been determined.

Field Summary

Fields

Modifier and Type	Field and Description
protected boolean	mAreLocationUpdatesRunning

Constructor Summary

Constructors

Constructor and Description
LocationProviderAdapter()

Method Summary

Modifier and Type	Method and Description
void	acquireLocation(LocationProviderAdapter.LocationAcquisitionListener listener, long maximumAge, float maximumInaccuracy) Acquire the current location, and will implicitly initiate requests for (future) location updates.
void	addLocationListener(LocationListener listener) Adds a listener that is called when a location update is received.
protected abstract void	cancelLocationUpdates() Stops all location updates.
void	deinitialize() Deinitializes the adapter.
protected long	determineLocationAge(Location location) A convenience for determining how much time has elapsed since the given update's timestamp.
abstract Location	getLastKnownLocation()
protected boolean	hasListeners()
void	initialize() Initialize the adapter.
protected void	notifyListenersLocationChanged(Location location) Called by an implementation when an update has been received from its underlying location provider.
void	removeLocationListener(LocationListener listener) Removes the given listener.
abstract void	requestLocationUpdates() Initiate recurring location updates at a fixed interval.

Methods inherited from class java.lang.Object

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

Field Detail

mAreLocationUpdatesRunning

protected boolean mAreLocationUpdatesRunning

Constructor Detail

LocationProviderAdapter

public LocationProviderAdapter()

Method Detail

initialize

public void initialize()

Initialize the adapter. This is called by the navigation manager when it is initialized.

The base implementation of this method takes no action and is intended to be overridden by subclasses that need to do work that can't be done on demand. For example, a PlayLocationProviderAdapter (uses PlayServices) connects to a Service, which can't be done synchronously, preventing it from being done lazily from a method like getLastKnownLocation().

deinitialize

public void deinitialize()

Deinitializes the adapter. This is done when as soon as possible after the navigation manager is deinitialized. Note that if navigation is in progress, the call to deinitialize the adapter will be deferred until navigation ends. If the manager is reinitialized before the adapter can be deinitialized, the pending adapter deinitialization call will not happen.

addLocationListener

public void addLocationListener(LocationListener listener)

Adds a listener that is called when a location update is received. If no listeners existed, this will cause recurring location updates to be requested from the underlying location service.

requestLocationUpdates

public abstract void requestLocationUpdates()

Initiate recurring location updates at a fixed interval.

Location updates are delivered to each LocationListener added via addLocationListener, above.

The concrete implementation of this method should immediately initiate recurring location updates at an appropriate interval, typically at a minimum interval of approximately once per second.

CAVEAT: If the location update interval is too long, the Navigation Manager might not perform as expected; conversely, if it is much shorter than once per second, this could prove wasteful of battery-life without any real benefits to navigation accuracy or user-experience.

removeLocationListener

public void removeLocationListener(LocationListener listener)

Removes the given listener. If no listeners remain, the adapter will unsubscribe from updates with the underlying location service.

Parameters:

listener - The listener to remove.

cancelLocationUpdates

protected abstract void cancelLocationUpdates()

Stops all location updates.

Cancels the recurring location updates delivered to each LocationListener that were initiated by requestLocationUpdates().

The concrete implementation of this method should immediately cancel all recurring location updates.

hasListeners

protected boolean hasListeners()

notifyListenersLocationChanged

protected void notifyListenersLocationChanged(Location location)

Called by an implementation when an update has been received from its underlying location provider.

getLastKnownLocation

public abstract Location getLastKnownLocation()

Returns:

The last location that was received by the adapter's underlying location service. Because this value can be quite old if the provider is not currently listening for locations, do not assume that the last known location is the device's current location. Be sure to check the location's timestamp. See determineLocationAge(Location).

determineLocationAge

protected long determineLocationAge(Location location)

A convenience for determining how much time has elapsed since the given update's timestamp.

Returns:

The amount of time elapsed, in milliseconds.

acquireLocation

public void acquireLocation(LocationProviderAdapter.LocationAcquisitionListener listener,
                            long maximumAge,
                            float maximumInaccuracy)

Acquire the current location, and will implicitly initiate requests for (future) location updates. Note that the given LocationAcquisitionListener will be called (once) with the current location once it has been successfully acquired. Note that if the underlying provider's "last known location" satisfies the provided requirements of age and accuracy, the given listener will be notified of that location immediately (instead of requesting location updates).