From 309ab3bb4983327624a7373b39b7b7818ab50b01 Mon Sep 17 00:00:00 2001 From: Soonil Nagarkar Date: Tue, 10 Aug 2021 09:46:12 -0700 Subject: Log locations received by default and add javadocs Logging received locations was originally removed over fears it would be too spammy, but it is proving too difficult to debug without at least some logs here. Bug: 196053011 Test: manual Change-Id: Ie18baa26daca9ad761125ad07a734f27fabfd89e --- .../java/android/location/LocationListener.java | 23 ++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) (limited to 'location/java') diff --git a/location/java/android/location/LocationListener.java b/location/java/android/location/LocationListener.java index 35a40910e373..031642b752e5 100644 --- a/location/java/android/location/LocationListener.java +++ b/location/java/android/location/LocationListener.java @@ -38,9 +38,9 @@ import java.util.concurrent.Executor; public interface LocationListener { /** - * Called when the location has changed. A wakelock is held on behalf on the listener for some - * brief amount of time as this callback executes. If this callback performs long running - * operations, it is the client's responsibility to obtain their own wakelock. + * Called when the location has changed. A wakelock may be held on behalf on the listener for + * some brief amount of time as this callback executes. If this callback performs long running + * operations, it is the client's responsibility to obtain their own wakelock if necessary. * * @param location the updated location */ @@ -48,7 +48,7 @@ public interface LocationListener { /** * Called when the location has changed and locations are being delivered in batches. The - * default implementation calls through to ({@link #onLocationChanged(Location)} with all + * default implementation calls through to {@link #onLocationChanged(Location)} with all * locations in the batch. The list of locations is always guaranteed to be non-empty, and is * always guaranteed to be ordered from earliest location to latest location (so that the * earliest location in the batch is at index 0 in the list, and the latest location in the @@ -76,6 +76,11 @@ public interface LocationListener { * This callback will never be invoked on Android Q and above, and providers can be considered * as always in the {@link LocationProvider#AVAILABLE} state. * + *

Note that this method only has a default implementation on Android R and + * above, and this method must still be overridden in order to run successfully on Android + * versions below R. LocationListenerCompat from the compat libraries may be used to avoid the + * need to override for older platforms. + * * @deprecated This callback will never be invoked on Android Q and above. */ @Deprecated @@ -84,6 +89,11 @@ public interface LocationListener { /** * Called when a provider this listener is registered with becomes enabled. * + *

Note that this method only has a default implementation on Android R and + * above, and this method must still be overridden in order to run successfully on Android + * versions below R. LocationListenerCompat from the compat libraries may be used to avoid the + * need to override for older platforms. + * * @param provider the name of the location provider */ default void onProviderEnabled(@NonNull String provider) {} @@ -92,6 +102,11 @@ public interface LocationListener { * Called when the provider this listener is registered with becomes disabled. If a provider is * disabled when this listener is registered, this callback will be invoked immediately. * + *

Note that this method only has a default implementation on Android R and + * above, and this method must still be overridden in order to run successfully on Android + * versions below R. LocationListenerCompat from the compat libraries may be used to avoid the + * need to override for older platforms. + * * @param provider the name of the location provider */ default void onProviderDisabled(@NonNull String provider) {} -- cgit v1.2.3-59-g8ed1b