Location awareness is a common feature for mobile application that enhance the user experience by providing context-specific services.

== Why is this an issue?

The location awareness feature can significantly drain the device's battery.

The recommended way to maximize the battery life is to use the _fused location provider_
which combines signals from GPS, Wi-Fi, and cell networks, as well as accelerometer, gyroscope, magnetometer and other sensors.
The `FusedLocationProviderClient` automatically chooses the best method to retrieve a device's location based on the device's context.

The rule flags an issue when `android.location.LocationManager` or `com.google.android.gms.location.LocationClient`
is used instead of `com.google.android.gms.location.FusedLocationProviderClient`.

=== What is the potential impact?

* _Usability_: the non-optimized location API consumer more battery.
* _Sustainability_: the extra energy required has a negative impact on the environment.

== How to fix it

Replace the usages of `android.location.LocationManager` or `com.google.android.gms.location.LocationClient`
with `com.google.android.gms.location.FusedLocationProviderClient`.

=== Code examples

==== Noncompliant code example

[source,java,diff-id=1,diff-type=noncompliant]
----
public class LocationsActivity extends Activity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        // ...

        LocationManager locationManager = (LocationManager) this.getSystemService(Context.LOCATION_SERVICE); // Noncompliant

        LocationListener locationListener = new LocationListener() {
            public void onLocationChanged(Location location) {
                // Use the location object as needed
            }
        };

        locationManager.requestLocationUpdates(LocationManager.GPS_PROVIDER, 0, 0, locationListener);
    }
}
----

==== Compliant solution

[source,java,diff-id=1,diff-type=compliant]
----
public class LocationsActivity extends Activity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        // ...

        FusedLocationProviderClient fusedLocationClient = LocationServices.getFusedLocationProviderClient(this); // Compliant

        fusedLocationClient.getLastLocation()
            .addOnSuccessListener(this, location -> {
                // Use the location object as needed
            });
    }
}
----


== Resources
=== Documentation

* https://developers.google.com/android/reference/com/google/android/gms/location/FusedLocationProviderClient.html[Google Play Services - FusedLocationProviderClient]
* https://developer.android.com/develop/sensors-and-location/location/battery[Android Developers - Optimize location for battery]
* https://developer.android.com/reference/android/location/package-summary[Android Developers - Android Location]