Merge "Log locations received by default and add javadocs" into sc-dev am: 35260c6f60 am: b4c5930034

Original change: https://googleplex-android-review.googlesource.com/c/platform/frameworks/base/+/15517616

Change-Id: I6856edaea26cc2356a13471c1c9810946da2bb12

1 files changed, 19 insertions, 4 deletions

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.
      *
+     * <p class="note">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.
      *
+     * <p class="note">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.
      *
+     * <p class="note">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) {}