Import Android SDK Platform P [4524038]

/google/data/ro/projects/android/fetch_artifact \
    --bid 4524038 \
    --target sdk_phone_armv7-win_sdk \
    sdk-repo-linux-sources-4524038.zip

AndroidVersion.ApiLevel has been modified to appear as 28

Change-Id: Ic193bf1cf0cae78d4f2bfb4fbddfe42025c5c3c2

1 files changed, 96 insertions, 74 deletions

diff --git a/android/hardware/location/ContextHubTransaction.java b/android/hardware/location/ContextHubTransaction.java
index a8569ef4..a1b743da 100644
--- a/android/hardware/location/ContextHubTransaction.java
+++ b/android/hardware/location/ContextHubTransaction.java
@@ -15,15 +15,16 @@
  */
 package android.hardware.location;
 
+import android.annotation.CallbackExecutor;
 import android.annotation.IntDef;
 import android.annotation.NonNull;
 import android.os.Handler;
-import android.os.Looper;
-import android.util.Log;
+import android.os.HandlerExecutor;
 
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.Executor;
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.TimeoutException;
 
@@ -33,8 +34,8 @@ import java.util.concurrent.TimeoutException;
  * This object is generated as a result of an asynchronous request sent to the Context Hub
  * through the ContextHubManager APIs. The caller can either retrieve the result
  * synchronously through a blocking call ({@link #waitForResponse(long, TimeUnit)}) or
- * asynchronously through a user-defined callback
- * ({@link #setCallbackOnComplete(ContextHubTransaction.Callback, Handler)}).
+ * asynchronously through a user-defined listener
+ * ({@link #setOnCompleteListener(Listener, Executor)} )}).
  *
  * @param <T> the type of the contents in the transaction response
  *
@@ -47,13 +48,15 @@ public class ContextHubTransaction<T> {
      * Constants describing the type of a transaction through the Context Hub Service.
      */
     @Retention(RetentionPolicy.SOURCE)
-    @IntDef({
+    @IntDef(prefix = { "TYPE_" }, value = {
             TYPE_LOAD_NANOAPP,
             TYPE_UNLOAD_NANOAPP,
             TYPE_ENABLE_NANOAPP,
             TYPE_DISABLE_NANOAPP,
-            TYPE_QUERY_NANOAPPS})
-    public @interface Type {}
+            TYPE_QUERY_NANOAPPS
+    })
+    public @interface Type { }
+
     public static final int TYPE_LOAD_NANOAPP = 0;
     public static final int TYPE_UNLOAD_NANOAPP = 1;
     public static final int TYPE_ENABLE_NANOAPP = 2;
@@ -64,45 +67,51 @@ public class ContextHubTransaction<T> {
      * Constants describing the result of a transaction or request through the Context Hub Service.
      */
     @Retention(RetentionPolicy.SOURCE)
-    @IntDef({
-            TRANSACTION_SUCCESS,
-            TRANSACTION_FAILED_UNKNOWN,
-            TRANSACTION_FAILED_BAD_PARAMS,
-            TRANSACTION_FAILED_UNINITIALIZED,
-            TRANSACTION_FAILED_PENDING,
-            TRANSACTION_FAILED_AT_HUB,
-            TRANSACTION_FAILED_TIMEOUT,
-            TRANSACTION_FAILED_SERVICE_INTERNAL_FAILURE})
+    @IntDef(prefix = { "RESULT_" }, value = {
+            RESULT_SUCCESS,
+            RESULT_FAILED_UNKNOWN,
+            RESULT_FAILED_BAD_PARAMS,
+            RESULT_FAILED_UNINITIALIZED,
+            RESULT_FAILED_PENDING,
+            RESULT_FAILED_AT_HUB,
+            RESULT_FAILED_TIMEOUT,
+            RESULT_FAILED_SERVICE_INTERNAL_FAILURE,
+            RESULT_FAILED_HAL_UNAVAILABLE
+    })
     public @interface Result {}
-    public static final int TRANSACTION_SUCCESS = 0;
+    public static final int RESULT_SUCCESS = 0;
     /**
      * Generic failure mode.
      */
-    public static final int TRANSACTION_FAILED_UNKNOWN = 1;
+    public static final int RESULT_FAILED_UNKNOWN = 1;
     /**
      * Failure mode when the request parameters were not valid.
      */
-    public static final int TRANSACTION_FAILED_BAD_PARAMS = 2;
+    public static final int RESULT_FAILED_BAD_PARAMS = 2;
     /**
      * Failure mode when the Context Hub is not initialized.
      */
-    public static final int TRANSACTION_FAILED_UNINITIALIZED = 3;
+    public static final int RESULT_FAILED_UNINITIALIZED = 3;
     /**
      * Failure mode when there are too many transactions pending.
      */
-    public static final int TRANSACTION_FAILED_PENDING = 4;
+    public static final int RESULT_FAILED_PENDING = 4;
     /**
      * Failure mode when the request went through, but failed asynchronously at the hub.
      */
-    public static final int TRANSACTION_FAILED_AT_HUB = 5;
+    public static final int RESULT_FAILED_AT_HUB = 5;
     /**
      * Failure mode when the transaction has timed out.
      */
-    public static final int TRANSACTION_FAILED_TIMEOUT = 6;
+    public static final int RESULT_FAILED_TIMEOUT = 6;
     /**
      * Failure mode when the transaction has failed internally at the service.
      */
-    public static final int TRANSACTION_FAILED_SERVICE_INTERNAL_FAILURE = 7;
+    public static final int RESULT_FAILED_SERVICE_INTERNAL_FAILURE = 7;
+    /**
+     * Failure mode when the Context Hub HAL was not available.
+     */
+    public static final int RESULT_FAILED_HAL_UNAVAILABLE = 8;
 
     /**
      * A class describing the response for a ContextHubTransaction.
@@ -137,20 +146,20 @@ public class ContextHubTransaction<T> {
     }
 
     /**
-     * An interface describing the callback to be invoked when a transaction completes.
+     * An interface describing the listener for a transaction completion.
      *
-     * @param <C> the type of the contents in the transaction response
+     * @param <L> the type of the contents in the transaction response
      */
     @FunctionalInterface
-    public interface Callback<C> {
+    public interface Listener<L> {
         /**
-         * The callback to invoke when the transaction completes.
+         * The listener function to invoke when the transaction completes.
          *
          * @param transaction the transaction that this callback was attached to.
          * @param response the response of the transaction.
          */
         void onComplete(
-                ContextHubTransaction<C> transaction, ContextHubTransaction.Response<C> response);
+                ContextHubTransaction<L> transaction, ContextHubTransaction.Response<L> response);
     }
 
     /*
@@ -165,14 +174,14 @@ public class ContextHubTransaction<T> {
     private ContextHubTransaction.Response<T> mResponse;
 
     /*
-     * The handler to invoke the aynsc response supplied by onComplete.
+     * The executor to invoke the onComplete async callback.
      */
-    private Handler mHandler = null;
+    private Executor mExecutor = null;
 
     /*
-     * The callback to invoke when the transaction completes.
+     * The listener to be invoked when the transaction completes.
      */
-    private ContextHubTransaction.Callback<T> mCallback = null;
+    private ContextHubTransaction.Listener<T> mListener = null;
 
     /*
      * Synchronization latch used to block on response.
@@ -189,6 +198,30 @@ public class ContextHubTransaction<T> {
     }
 
     /**
+     * Converts a transaction type to a human-readable string
+     *
+     * @param type the type of a transaction
+     * @param upperCase {@code true} if upper case the first letter, {@code false} otherwise
+     * @return a string describing the transaction
+     */
+    public static String typeToString(@Type int type, boolean upperCase) {
+        switch (type) {
+            case ContextHubTransaction.TYPE_LOAD_NANOAPP:
+                return upperCase ? "Load" : "load";
+            case ContextHubTransaction.TYPE_UNLOAD_NANOAPP:
+                return upperCase ? "Unload" : "unload";
+            case ContextHubTransaction.TYPE_ENABLE_NANOAPP:
+                return upperCase ? "Enable" : "enable";
+            case ContextHubTransaction.TYPE_DISABLE_NANOAPP:
+                return upperCase ? "Disable" : "disable";
+            case ContextHubTransaction.TYPE_QUERY_NANOAPPS:
+                return upperCase ? "Query" : "query";
+            default:
+                return upperCase ? "Unknown" : "unknown";
+        }
+    }
+
+    /**
      * @return the type of the transaction
      */
     @Type
@@ -226,73 +259,68 @@ public class ContextHubTransaction<T> {
     }
 
     /**
-     * Sets a callback to be invoked when the transaction completes.
+     * Sets the listener to be invoked invoked when the transaction completes.
      *
      * This function provides an asynchronous approach to retrieve the result of the
      * transaction. When the transaction response has been provided by the Context Hub,
-     * the given callback will be posted by the provided handler.
+     * the given listener will be invoked.
      *
-     * If the transaction has already completed at the time of invocation, the callback
-     * will be immediately posted by the handler. If the transaction has been invalidated,
-     * the callback will never be invoked.
+     * If the transaction has already completed at the time of invocation, the listener
+     * will be immediately invoked. If the transaction has been invalidated,
+     * the listener will never be invoked.
      *
      * A transaction can be invalidated if the process owning the transaction is no longer active
      * and the reference to this object is lost.
      *
-     * This method or {@link #setCallbackOnCompletecan(ContextHubTransaction.Callback)} can only be
+     * This method or {@link #setOnCompleteListener(ContextHubTransaction.Listener)} can only be
      * invoked once, or an IllegalStateException will be thrown.
      *
-     * @param callback the callback to be invoked upon completion
-     * @param handler the handler to post the callback
+     * @param listener the listener to be invoked upon completion
+     * @param executor the executor to invoke the callback
      *
      * @throws IllegalStateException if this method is called multiple times
      * @throws NullPointerException if the callback or handler is null
      */
-    public void setCallbackOnComplete(
-            @NonNull ContextHubTransaction.Callback<T> callback, @NonNull Handler handler) {
+    public void setOnCompleteListener(
+            @NonNull ContextHubTransaction.Listener<T> listener,
+            @NonNull @CallbackExecutor Executor executor) {
         synchronized (this) {
-            if (callback == null) {
-                throw new NullPointerException("Callback cannot be null");
+            if (listener == null) {
+                throw new NullPointerException("Listener cannot be null");
             }
-            if (handler == null) {
-                throw new NullPointerException("Handler cannot be null");
+            if (executor == null) {
+                throw new NullPointerException("Executor cannot be null");
             }
-            if (mCallback != null) {
+            if (mListener != null) {
                 throw new IllegalStateException(
-                        "Cannot set ContextHubTransaction callback multiple times");
+                        "Cannot set ContextHubTransaction listener multiple times");
             }
 
-            mCallback = callback;
-            mHandler = handler;
+            mListener = listener;
+            mExecutor = executor;
 
             if (mDoneSignal.getCount() == 0) {
-                boolean callbackPosted = mHandler.post(() -> {
-                    mCallback.onComplete(this, mResponse);
-                });
-
-                if (!callbackPosted) {
-                    Log.e(TAG, "Failed to post callback to Handler");
-                }
+                mExecutor.execute(() -> mListener.onComplete(this, mResponse));
             }
         }
     }
 
     /**
-     * Sets a callback to be invoked when the transaction completes.
+     * Sets the listener to be invoked invoked when the transaction completes.
      *
-     * Equivalent to {@link #setCallbackOnComplete(ContextHubTransaction.Callback, Handler)}
-     * with the handler being that of the main thread's Looper.
+     * Equivalent to {@link #setOnCompleteListener(ContextHubTransaction.Listener, Executor)}
+     * with the executor using the main thread's Looper.
      *
-     * This method or {@link #setCallbackOnComplete(ContextHubTransaction.Callback, Handler)}
+     * This method or {@link #setOnCompleteListener(ContextHubTransaction.Listener, Executor)}
      * can only be invoked once, or an IllegalStateException will be thrown.
      *
-     * @param callback the callback to be invoked upon completion
+     * @param listener the listener to be invoked upon completion
      *
      * @throws IllegalStateException if this method is called multiple times
      * @throws NullPointerException if the callback is null
      */
-    public void setCallbackOnComplete(@NonNull ContextHubTransaction.Callback<T> callback) {
-        setCallbackOnComplete(callback, new Handler(Looper.getMainLooper()));
+    public void setOnCompleteListener(@NonNull ContextHubTransaction.Listener<T> listener) {
+        setOnCompleteListener(listener, new HandlerExecutor(Handler.getMain()));
     }
 
     /**
@@ -307,7 +335,7 @@ public class ContextHubTransaction<T> {
      * @throws IllegalStateException if this method is invoked multiple times
      * @throws NullPointerException if the response is null
      */
-    void setResponse(ContextHubTransaction.Response<T> response) {
+    /* package */ void setResponse(ContextHubTransaction.Response<T> response) {
         synchronized (this) {
             if (response == null) {
                 throw new NullPointerException("Response cannot be null");
@@ -321,14 +349,8 @@ public class ContextHubTransaction<T> {
             mIsResponseSet = true;
 
             mDoneSignal.countDown();
-            if (mCallback != null) {
-                boolean callbackPosted = mHandler.post(() -> {
-                    mCallback.onComplete(this, mResponse);
-                });
-
-                if (!callbackPosted) {
-                    Log.e(TAG, "Failed to post callback to Handler");
-                }
+            if (mListener != null) {
+                mExecutor.execute(() -> mListener.onComplete(this, mResponse));
             }
         }
     }