Merge "Ensure UWB conforms to API guidelines" am: 0070e26a5e am: a0e1666a74

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

MUST ONLY BE SUBMITTED BY AUTOMERGER

Change-Id: I561ea72833cbadcae45cff01edf310fee80c6532

core/java/android/uwb/AngleMeasurement.java

@@ -17,6 +17,7 @@
 package android.uwb;
 
 import android.annotation.FloatRange;
+import android.annotation.NonNull;
 import android.os.Parcel;
 import android.os.Parcelable;
 
@@ -109,7 +110,7 @@ public final class AngleMeasurement implements Parcelable {
     }
 
     @Override
-    public void writeToParcel(Parcel dest, int flags) {
+    public void writeToParcel(@NonNull Parcel dest, int flags) {
         dest.writeDouble(mRadians);
         dest.writeDouble(mErrorRadians);
         dest.writeDouble(mConfidenceLevel);
@@ -146,6 +147,7 @@ public final class AngleMeasurement implements Parcelable {
          * @param radians angle in radians
          * @throws IllegalArgumentException if angle exceeds allowed limits of [-Math.PI, +Math.PI]
          */
+        @NonNull
         public Builder setRadians(double radians) {
             if (radians < -Math.PI || radians > Math.PI) {
                 throw new IllegalArgumentException("Invalid radians: " + radians);
@@ -160,6 +162,7 @@ public final class AngleMeasurement implements Parcelable {
          * @param errorRadians error of the angle in radians
          * @throws IllegalArgumentException if the error exceeds the allowed limits of [0, +Math.PI]
          */
+        @NonNull
         public Builder setErrorRadians(double errorRadians) {
             if (errorRadians < 0.0 || errorRadians > Math.PI) {
                 throw new IllegalArgumentException(
@@ -175,6 +178,7 @@ public final class AngleMeasurement implements Parcelable {
          * @param confidenceLevel level of confidence of the angle measurement
          * @throws IllegalArgumentException if the error exceeds the allowed limits of [0.0, 1.0]
          */
+        @NonNull
         public Builder setConfidenceLevel(double confidenceLevel) {
             if (confidenceLevel < 0.0 || confidenceLevel > 1.0) {
                 throw new IllegalArgumentException(
@@ -189,6 +193,7 @@ public final class AngleMeasurement implements Parcelable {
          *
          * @throws IllegalStateException if angle, error, or confidence values are missing
          */
+        @NonNull
         public AngleMeasurement build() {
             if (Double.isNaN(mRadians)) {
                 throw new IllegalStateException("Angle is not set");

core/java/android/uwb/AngleOfArrivalMeasurement.java

@@ -53,7 +53,7 @@ public final class AngleOfArrivalMeasurement implements Parcelable {
      * @return the azimuth {@link AngleMeasurement}
      */
     @NonNull
-    public AngleMeasurement getAzimuth() {
+    public AngleMeasurement getAzimuthAngleMeasurement() {
         return mAzimuthAngleMeasurement;
     }
 
@@ -70,7 +70,7 @@ public final class AngleOfArrivalMeasurement implements Parcelable {
      * @return altitude {@link AngleMeasurement} or null when this is not available
      */
     @Nullable
-    public AngleMeasurement getAltitude() {
+    public AngleMeasurement getAltitudeAngleMeasurement() {
         return mAltitudeAngleMeasurement;
     }
 
@@ -85,8 +85,8 @@ public final class AngleOfArrivalMeasurement implements Parcelable {
 
         if (obj instanceof AngleOfArrivalMeasurement) {
             AngleOfArrivalMeasurement other = (AngleOfArrivalMeasurement) obj;
-            return mAzimuthAngleMeasurement.equals(other.getAzimuth())
+            return mAzimuthAngleMeasurement.equals(other.getAzimuthAngleMeasurement())
-                    && mAltitudeAngleMeasurement.equals(other.getAltitude());
+                    && mAltitudeAngleMeasurement.equals(other.getAltitudeAngleMeasurement());
         }
         return false;
     }
@@ -105,7 +105,7 @@ public final class AngleOfArrivalMeasurement implements Parcelable {
     }
 
     @Override
-    public void writeToParcel(Parcel dest, int flags) {
+    public void writeToParcel(@NonNull Parcel dest, int flags) {
         dest.writeParcelable(mAzimuthAngleMeasurement, flags);
         dest.writeParcelable(mAltitudeAngleMeasurement, flags);
     }
@@ -143,6 +143,7 @@ public final class AngleOfArrivalMeasurement implements Parcelable {
          *
          * @param azimuthAngle azimuth angle
          */
+        @NonNull
         public Builder setAzimuthAngleMeasurement(@NonNull AngleMeasurement azimuthAngle) {
             mAzimuthAngleMeasurement = azimuthAngle;
             return this;
@@ -153,6 +154,7 @@ public final class AngleOfArrivalMeasurement implements Parcelable {
          *
          * @param altitudeAngle altitude angle
          */
+        @NonNull
         public Builder setAltitudeAngleMeasurement(@NonNull AngleMeasurement altitudeAngle) {
             mAltitudeAngleMeasurement = altitudeAngle;
             return this;
@@ -163,6 +165,7 @@ public final class AngleOfArrivalMeasurement implements Parcelable {
          *
          * @throws IllegalStateException if the required azimuth angle is not provided
          */
+        @NonNull
         public AngleOfArrivalMeasurement build() {
             if (mAzimuthAngleMeasurement == null) {
                 throw new IllegalStateException("Azimuth angle measurement is not set");

core/java/android/uwb/DistanceMeasurement.java

@@ -17,6 +17,7 @@
 package android.uwb;
 
 import android.annotation.FloatRange;
+import android.annotation.NonNull;
 import android.annotation.Nullable;
 import android.os.Parcel;
 import android.os.Parcelable;
@@ -106,7 +107,7 @@ public final class DistanceMeasurement implements Parcelable {
     }
 
     @Override
-    public void writeToParcel(Parcel dest, int flags) {
+    public void writeToParcel(@NonNull Parcel dest, int flags) {
         dest.writeDouble(mMeters);
         dest.writeDouble(mErrorMeters);
         dest.writeDouble(mConfidenceLevel);
@@ -143,6 +144,7 @@ public final class DistanceMeasurement implements Parcelable {
          * @param meters distance in meters
          * @throws IllegalArgumentException if meters is NaN
          */
+        @NonNull
         public Builder setMeters(double meters) {
             if (Double.isNaN(meters)) {
                 throw new IllegalArgumentException("meters cannot be NaN");
@@ -157,6 +159,7 @@ public final class DistanceMeasurement implements Parcelable {
          * @param errorMeters distance error in meters
          * @throws IllegalArgumentException if error is negative or NaN
          */
+        @NonNull
         public Builder setErrorMeters(double errorMeters) {
             if (Double.isNaN(errorMeters) || errorMeters < 0.0) {
                 throw new IllegalArgumentException(
@@ -172,6 +175,7 @@ public final class DistanceMeasurement implements Parcelable {
          * @param confidenceLevel the confidence level in the distance measurement
          * @throws IllegalArgumentException if confidence level is not in the range of [0.0, 1.0]
          */
+        @NonNull
         public Builder setConfidenceLevel(double confidenceLevel) {
             if (confidenceLevel < 0.0 || confidenceLevel > 1.0) {
                 throw new IllegalArgumentException(
@@ -186,6 +190,7 @@ public final class DistanceMeasurement implements Parcelable {
          *
          * @throws IllegalStateException if meters, error, or confidence are not set
          */
+        @NonNull
         public DistanceMeasurement build() {
             if (Double.isNaN(mMeters)) {
                 throw new IllegalStateException("Meters cannot be NaN");

core/java/android/uwb/RangingMeasurement.java

@@ -60,6 +60,9 @@ public final class RangingMeasurement implements Parcelable {
         return mRemoteDeviceAddress;
     }
 
+    /**
+     * @hide
+     */
     @Retention(RetentionPolicy.SOURCE)
     @IntDef(value = {
             RANGING_STATUS_SUCCESS,
@@ -115,7 +118,7 @@ public final class RangingMeasurement implements Parcelable {
      *         {@link #RANGING_STATUS_SUCCESS}
      */
     @Nullable
-    public DistanceMeasurement getDistance() {
+    public DistanceMeasurement getDistanceMeasurement() {
         return mDistanceMeasurement;
     }
 
@@ -126,7 +129,7 @@ public final class RangingMeasurement implements Parcelable {
      *         {@link #RANGING_STATUS_SUCCESS}
      */
     @Nullable
-    public AngleOfArrivalMeasurement getAngleOfArrival() {
+    public AngleOfArrivalMeasurement getAngleOfArrivalMeasurement() {
         return mAngleOfArrivalMeasurement;
     }
 
@@ -144,8 +147,8 @@ public final class RangingMeasurement implements Parcelable {
             return mRemoteDeviceAddress.equals(other.getRemoteDeviceAddress())
                     && mStatus == other.getStatus()
                     && mElapsedRealtimeNanos == other.getElapsedRealtimeNanos()
-                    && mDistanceMeasurement.equals(other.getDistance())
+                    && mDistanceMeasurement.equals(other.getDistanceMeasurement())
-                    && mAngleOfArrivalMeasurement.equals(other.getAngleOfArrival());
+                    && mAngleOfArrivalMeasurement.equals(other.getAngleOfArrivalMeasurement());
         }
         return false;
     }
@@ -165,7 +168,7 @@ public final class RangingMeasurement implements Parcelable {
     }
 
     @Override
-    public void writeToParcel(Parcel dest, int flags) {
+    public void writeToParcel(@NonNull Parcel dest, int flags) {
         dest.writeParcelable(mRemoteDeviceAddress, flags);
         dest.writeInt(mStatus);
         dest.writeLong(mElapsedRealtimeNanos);
@@ -210,6 +213,7 @@ public final class RangingMeasurement implements Parcelable {
          *
          * @param remoteDeviceAddress remote device's address
          */
+        @NonNull
         public Builder setRemoteDeviceAddress(@NonNull UwbAddress remoteDeviceAddress) {
             mRemoteDeviceAddress = remoteDeviceAddress;
             return this;
@@ -220,6 +224,7 @@ public final class RangingMeasurement implements Parcelable {
          *
          * @param status the status of the ranging measurement
          */
+        @NonNull
         public Builder setStatus(@Status int status) {
             mStatus = status;
             return this;
@@ -230,6 +235,7 @@ public final class RangingMeasurement implements Parcelable {
          *
          * @param elapsedRealtimeNanos time the ranging measurement occurred
          */
+        @NonNull
         public Builder setElapsedRealtimeNanos(long elapsedRealtimeNanos) {
             if (elapsedRealtimeNanos < 0) {
                 throw new IllegalArgumentException("elapsedRealtimeNanos must be >= 0");
@@ -243,6 +249,7 @@ public final class RangingMeasurement implements Parcelable {
          *
          * @param distanceMeasurement the distance measurement for this ranging measurement
          */
+        @NonNull
         public Builder setDistanceMeasurement(@NonNull DistanceMeasurement distanceMeasurement) {
             mDistanceMeasurement = distanceMeasurement;
             return this;
@@ -254,6 +261,7 @@ public final class RangingMeasurement implements Parcelable {
          * @param angleOfArrivalMeasurement the angle of arrival measurement for this ranging
          *                                  measurement
          */
+        @NonNull
         public Builder setAngleOfArrivalMeasurement(
                 @NonNull AngleOfArrivalMeasurement angleOfArrivalMeasurement) {
             mAngleOfArrivalMeasurement = angleOfArrivalMeasurement;
@@ -268,6 +276,7 @@ public final class RangingMeasurement implements Parcelable {
          *                               elapsedRealtimeNanos of the measurement is invalid, or
          *                               if no remote device address is set
          */
+        @NonNull
         public RangingMeasurement build() {
             if (mStatus != RANGING_STATUS_SUCCESS) {
                 if (mDistanceMeasurement != null) {

core/java/android/uwb/RangingReport.java

@@ -83,7 +83,7 @@ public final class RangingReport implements Parcelable {
     }
 
     @Override
-    public void writeToParcel(Parcel dest, int flags) {
+    public void writeToParcel(@NonNull Parcel dest, int flags) {
         dest.writeTypedList(mRangingMeasurements);
     }
 
@@ -113,6 +113,7 @@ public final class RangingReport implements Parcelable {
          *
          * @param rangingMeasurement a ranging measurement
          */
+        @NonNull
         public Builder addMeasurement(@NonNull RangingMeasurement rangingMeasurement) {
             mMeasurements.add(rangingMeasurement);
             return this;
@@ -123,6 +124,7 @@ public final class RangingReport implements Parcelable {
          *
          * @param rangingMeasurements {@link List} of {@link RangingMeasurement}s to add
          */
+        @NonNull
         public Builder addMeasurements(@NonNull List<RangingMeasurement> rangingMeasurements) {
             mMeasurements.addAll(rangingMeasurements);
             return this;
@@ -133,6 +135,7 @@ public final class RangingReport implements Parcelable {
          *
          * @throws IllegalStateException if measurements are not in monotonically increasing order
          */
+        @NonNull
         public RangingReport build() {
             // Verify that all measurement timestamps are monotonically increasing
             RangingMeasurement prevMeasurement = null;

core/java/android/uwb/RangingSession.java

@@ -17,6 +17,7 @@
 package android.uwb;
 
 import android.annotation.IntDef;
+import android.annotation.NonNull;
 import android.os.PersistableBundle;
 
 import java.lang.annotation.Retention;
@@ -50,8 +51,11 @@ public final class RangingSession implements AutoCloseable {
          * @param session the newly opened {@link RangingSession}
          * @param sessionInfo session specific parameters from lower layers
          */
-        void onOpenSuccess(RangingSession session, PersistableBundle sessionInfo);
+        void onOpenSuccess(@NonNull RangingSession session, @NonNull PersistableBundle sessionInfo);
 
+        /**
+         * @hide
+         */
         @Retention(RetentionPolicy.SOURCE)
         @IntDef(value = {
                 CLOSE_REASON_UNKNOWN,
@@ -125,7 +129,7 @@ public final class RangingSession implements AutoCloseable {
          *
          * @param rangingReport ranging report for this interval's measurements
          */
-        void onReportReceived(RangingReport rangingReport);
+        void onReportReceived(@NonNull RangingReport rangingReport);
     }
 
     /**

core/java/android/uwb/UwbAddress.java

@@ -51,7 +51,7 @@ public final class UwbAddress implements Parcelable {
      *       {@link #SHORT_ADDRESS_BYTE_LENGTH} or {@link #EXTENDED_ADDRESS_BYTE_LENGTH} bytes
      */
     @NonNull
-    public static UwbAddress fromBytes(@NonNull byte[] address) throws IllegalArgumentException {
+    public static UwbAddress fromBytes(@NonNull byte[] address) {
         if (address.length != SHORT_ADDRESS_BYTE_LENGTH
                 && address.length != EXTENDED_ADDRESS_BYTE_LENGTH) {
             throw new IllegalArgumentException("Invalid UwbAddress length " + address.length);
@@ -107,7 +107,7 @@ public final class UwbAddress implements Parcelable {
     }
 
     @Override
-    public void writeToParcel(Parcel dest, int flags) {
+    public void writeToParcel(@NonNull Parcel dest, int flags) {
         dest.writeInt(mAddressBytes.length);
         dest.writeByteArray(mAddressBytes);
     }

core/java/android/uwb/UwbManager.java

@@ -55,6 +55,9 @@ public final class UwbManager {
      * Interface for receiving UWB adapter state changes
      */
     public interface AdapterStateCallback {
+        /**
+         * @hide
+         */
         @Retention(RetentionPolicy.SOURCE)
         @IntDef(value = {
                 STATE_CHANGED_REASON_SESSION_STARTED,
@@ -195,6 +198,9 @@ public final class UwbManager {
         }
     }
 
+    /**
+     * @hide
+     */
     @Retention(RetentionPolicy.SOURCE)
     @IntDef(value = {
             ANGLE_OF_ARRIVAL_SUPPORT_TYPE_NONE,
@@ -387,7 +393,7 @@ public final class UwbManager {
      */
     @NonNull
     public AutoCloseable openRangingSession(@NonNull PersistableBundle parameters,
-            @NonNull Executor executor,
+            @NonNull @CallbackExecutor Executor executor,
             @NonNull RangingSession.Callback callbacks) {
         throw new UnsupportedOperationException();
     }

core/tests/uwbtests/src/android/uwb/AngleOfArrivalMeasurementTest.java

@@ -48,8 +48,8 @@ public class AngleOfArrivalMeasurementTest {
         builder.setAzimuthAngleMeasurement(azimuth);
         AngleOfArrivalMeasurement measurement = tryBuild(builder, true);
 
-        assertEquals(azimuth, measurement.getAzimuth());
+        assertEquals(azimuth, measurement.getAzimuthAngleMeasurement());
-        assertEquals(altitude, measurement.getAltitude());
+        assertEquals(altitude, measurement.getAltitudeAngleMeasurement());
     }
 
     private AngleMeasurement getAngleMeasurement(double radian, double error, double confidence) {

core/tests/uwbtests/src/android/uwb/RangingMeasurementTest.java

@@ -63,8 +63,8 @@ public class RangingMeasurementTest {
         assertEquals(status, measurement.getStatus());
         assertEquals(address, measurement.getRemoteDeviceAddress());
         assertEquals(time, measurement.getElapsedRealtimeNanos());
-        assertEquals(angleMeasurement, measurement.getAngleOfArrival());
+        assertEquals(angleMeasurement, measurement.getAngleOfArrivalMeasurement());
-        assertEquals(distanceMeasurement, measurement.getDistance());
+        assertEquals(distanceMeasurement, measurement.getDistanceMeasurement());
     }
 
     private RangingMeasurement tryBuild(RangingMeasurement.Builder builder,