LocationEngine (libandroid-telemetry 2.2.10 API)

java.lang.Object
- com.mapbox.services.android.telemetry.location.LocationEngine

Direct Known Subclasses:

AndroidLocationEngine, GoogleLocationEngine, LostLocationEngine
```
public abstract class LocationEngine
extends java.lang.Object
```
Abstract implementation of a location engine. A location engine makes it simple to switch between providers without the hassle of including boilerplate inside your code. This allows developers to use Google Play Services location provider or the default LOST location provider, among others. For a good example setting up a location engine from this abstract class, have a look at the LostLocationEngine found inside the libandroid-services module.

Since:

2.0.0

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class LocationEngine.Type

Nested Classes
Modifier and Type	Class and Description
`static class`	`LocationEngine.Type`

Field Summary

Fields
Modifier and Type	Field and Description
`protected java.lang.Integer`	`fastestInterval`
`protected java.lang.Integer`	`interval`
`protected java.util.concurrent.CopyOnWriteArrayList<LocationEngineListener>`	`locationListeners`
`protected int`	`priority`
`protected java.lang.Float`	`smallestDisplacement`

Constructor Summary

Constructors
Constructor and Description

LocationEngine()
Construct a location engine.

Constructors
Constructor and Description
`LocationEngine()` Construct a location engine.

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`abstract void`	`activate()` Activate the location engine which will connect whichever location provider you are using.
`void`	`addLocationEngineListener(LocationEngineListener listener)` Useful when you'd like to add a location listener to handle location connections and update events.
`abstract void`	`deactivate()` Disconnect the location engine, useful when you no longer need location updates or requesting the users `getLastLocation()`.
`int`	`getFastestInterval()` Get the current fastest interval being used to receive location updates.
`int`	`getInterval()` Get the current interval being used to receive location updates.
`abstract android.location.Location`	`getLastLocation()` When first initializing the location engine the location updates oftentimes aren't immediate and your user experience might diminish since they are forced to wait till a more accurate update arrives.
`int`	`getPriority()` Get the current priority being used.
`float`	`getSmallestDisplacement()` Get the current smallest displacement being used to receive location updates.
`protected static boolean`	`isBetterLocation(android.location.Location location, android.location.Location currentBestLocation)` Determines whether one Location reading is better than the current Location fix.
`abstract boolean`	`isConnected()` Check if your location provider has been activated/connected.
`abstract LocationEngine.Type`	`obtainType()` Get the current `LocationEngine` `LocationEngine.Type` being used.
`boolean`	`removeLocationEngineListener(LocationEngineListener listener)` If you no longer need your `LocationEngineListener` to be invoked with every location update, use this method to remove it.
`abstract void`	`removeLocationUpdates()` When you no longer wish to receive location updates, you should call this method to prevent the devices battery from draining.
`abstract void`	`requestLocationUpdates()` if a `LocationEngineListener` is setup, registering for location updates will tell the provider to begin sending updates.
`void`	`setFastestInterval(int fastestInterval)` Set the fastest rate in milliseconds at which your application can handle location updates.
`void`	`setInterval(int interval)` Set the rate in milliseconds at which your app prefers to receive location updates.
`void`	`setPriority(int priority)` This method sets the priority of the request, providing this will help the location provide know which location sources to use.
`void`	`setSmallestDisplacement(float smallestDisplacement)` Set the smallest distance value in meters at which the user must move before a new location update comes in.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - priority
```
protected int priority
```
  - interval
```
protected java.lang.Integer interval
```
  - fastestInterval
```
protected java.lang.Integer fastestInterval
```
  - smallestDisplacement
```
protected java.lang.Float smallestDisplacement
```
  - locationListeners
```
protected java.util.concurrent.CopyOnWriteArrayList<LocationEngineListener> locationListeners
```
- Constructor Detail
  - LocationEngine
```
public LocationEngine()
```
    Construct a location engine.
    
    Since:
    
    2.0.0
- Method Detail
  - activate
```
public abstract void activate()
```
    Activate the location engine which will connect whichever location provider you are using. You'll need to call this before requesting user location updates using requestLocationUpdates().
    
    Since:
    
    2.0.0
  - deactivate
```
public abstract void deactivate()
```
    Disconnect the location engine, useful when you no longer need location updates or requesting the users getLastLocation(). Before deactivating you'll need to stop request user location updates using removeLocationUpdates().
    
    Since:
    
    2.0.0
  - isConnected
```
public abstract boolean isConnected()
```
    Check if your location provider has been activated/connected. This is mainly used internally but is also useful in the rare cases when you'd like to know if your location engine is connected or not.
    
    Returns:
    
    boolean true if the location engine has been activated/connected, else false.
    
    Since:
    
    2.0.0
  - getLastLocation
```
public abstract android.location.Location getLastLocation()
```
    When first initializing the location engine the location updates oftentimes aren't immediate and your user experience might diminish since they are forced to wait till a more accurate update arrives. A solution to this is to request the last known user location. There are no guarantees this won't return null since the Location object is simply stored in cache.
    
    Returns:
    
    The last known user location as a Location object.
    
    Since:
    
    2.0.0
  - requestLocationUpdates
```
public abstract void requestLocationUpdates()
```
    if a LocationEngineListener is setup, registering for location updates will tell the provider to begin sending updates.
    
    Since:
    
    2.0.0
  - removeLocationUpdates
```
public abstract void removeLocationUpdates()
```
    When you no longer wish to receive location updates, you should call this method to prevent the devices battery from draining. It's important to note that your location listeners will remain intake until you call removeLocationEngineListener(LocationEngineListener).
    
    Since:
    
    2.0.0
  - obtainType
```
public abstract LocationEngine.Type obtainType()
```
    Get the current LocationEngine LocationEngine.Type being used.
    
    Returns:
    
    one of the location engine types listed inside the LocationEngine.Type enum.
    
    Since:
    
    2.2.6
  - getPriority
```
public int getPriority()
```
    Get the current priority being used.
    
    Returns:
    
    Integer representing one of the priorities listed inside the LocationEnginePriority file.
    
    Since:
    
    2.0.0
  - setPriority
```
public void setPriority(int priority)
```
    This method sets the priority of the request, providing this will help the location provide know which location sources to use. You'll find more information on the different priority values inside the LocationEnginePriority file.
    
    Parameters:
    
    priority - One of the LocationEnginePrioritys listed.
    
    Since:
    
    2.0.0
  - getInterval
```
public int getInterval()
```
    Get the current interval being used to receive location updates. Default is 1 second.
    
    Returns:
    
    the current interval value being used in milliseconds.
    
    Since:
    
    2.1.0
  - setInterval
```
public void setInterval(int interval)
```
    Set the rate in milliseconds at which your app prefers to receive location updates. Note that the location updates may be faster than this rate if another app is receiving updates at a faster rate, or slower than this rate, or there may be no updates at all (if the device has no connectivity, for example).
    
    Parameters:
    
    interval - integer in milliseconds defining the rate in which you'd like to receive location updates.
    
    Since:
    
    2.1.0
  - getFastestInterval
```
public int getFastestInterval()
```
    Get the current fastest interval being used to receive location updates. Default is 1 second.
    
    Returns:
    
    the current fastest interval value being used in milliseconds.
    
    Since:
    
    2.1.0
  - setFastestInterval
```
public void setFastestInterval(int fastestInterval)
```
    Set the fastest rate in milliseconds at which your application can handle location updates. You need to set this rate because other apps also affect the rate at which updates are sent. If this rate is faster than your app can handle, you may encounter problems with UI flicker or data overflow. To prevent this, use this method to set an upper limit to the update rate.
    
    Parameters:
    
    fastestInterval - in milliseconds at which your app can handle location updates.
    
    Since:
    
    2.1.0
  - getSmallestDisplacement
```
public float getSmallestDisplacement()
```
    Get the current smallest displacement being used to receive location updates. Default is 3 meters.
    
    Returns:
    
    the current smallest displacement value being used in meters.
    
    Since:
    
    2.1.0
  - setSmallestDisplacement
```
public void setSmallestDisplacement(float smallestDisplacement)
```
    Set the smallest distance value in meters at which the user must move before a new location update comes in.
    
    Parameters:
    
    smallestDisplacement - in meters which the user must move before a new location update's supplied.
    
    Since:
    
    2.1.0
  - addLocationEngineListener
```
public void addLocationEngineListener(LocationEngineListener listener)
```
    Useful when you'd like to add a location listener to handle location connections and update events. It is important to note, that the callback will continue getting called even when your application isn't in the foreground. Therefore, it is a good idea to use removeLocationEngineListener(LocationEngineListener) inside your activities onStop() method.
    
    Parameters:
    
    listener - A LocationEngineListener which you'd like to add to your location engine.
    
    Since:
    
    2.0.0
  - removeLocationEngineListener
```
public boolean removeLocationEngineListener(LocationEngineListener listener)
```
    If you no longer need your LocationEngineListener to be invoked with every location update, use this method to remove it. It's also important to remove your listeners before the activity is destroyed to prevent any potential memory leaks.
    
    Parameters:
    
    listener - the LocationEngineListener you'd like to remove from this LocationEngine.
    
    Returns:
    
    true if the listener has been removed, else false.
    
    Since:
    
    2.0.0
  - isBetterLocation
```
protected static boolean isBetterLocation(android.location.Location location,
                                          android.location.Location currentBestLocation)
```
    Determines whether one Location reading is better than the current Location fix. This is great to check whether the most recent location fix is more accurate then a previous. The result of this criteria also varies depending on the use-cases of the application and field testing. More specifically, this method checks if the location retrieved is significantly newer than the previous estimate, checks if the accuracy claimed by the location is better or worse than the previous estimate, and check which provider the new location is from and determine if you trust it more.
    
    Parameters:
    
    location - The new Location that you want to evaluate.
    
    currentBestLocation - The current Location fix, to which you want to compare the new one.
    
    Since:
    
    2.0.0

Class LocationEngine

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

priority

interval

fastestInterval

smallestDisplacement

locationListeners

Constructor Detail

LocationEngine

Method Detail

activate

deactivate

isConnected

getLastLocation

requestLocationUpdates

removeLocationUpdates

obtainType

getPriority

setPriority

getInterval

setInterval

getFastestInterval

setFastestInterval

getSmallestDisplacement

setSmallestDisplacement

addLocationEngineListener

removeLocationEngineListener

isBetterLocation