Merge "Switch "UTC time" to "Unix epoch time""

5 files changed, 102 insertions, 90 deletions

diff --git a/core/java/android/app/time/ExternalTimeSuggestion.java b/core/java/android/app/time/ExternalTimeSuggestion.java
index 0f98b4451983..c1185584b4ed 100644
--- a/core/java/android/app/time/ExternalTimeSuggestion.java
+++ b/core/java/android/app/time/ExternalTimeSuggestion.java
@@ -50,16 +50,17 @@ import java.util.Objects;
  * <p>The creator of an external suggestion is expected to be separate Android process, e.g. a
  * process integrating with the external time source via a HAL or local network. The creator must
  * capture the elapsed realtime reference clock, e.g. via {@link SystemClock#elapsedRealtime()},
- * when the UTC time is first obtained (usually under a wakelock). This enables Android to adjust
- * for latency introduced between suggestion creation and eventual use. Adjustments for other
+ * when the Unix epoch time is first obtained (usually under a wakelock). This enables Android to
+ * adjust for latency introduced between suggestion creation and eventual use. Adjustments for other
  * sources of latency, i.e. those before the external time suggestion is created, must be handled by
  * the creator.
  *
  * <p>{@code elapsedRealtimeMillis} and {@code suggestionMillis} represent the suggested time.
- * {@code suggestionMillis} is the number of milliseconds elapsed since 1/1/1970 00:00:00 UTC.
- * {@code elapsedRealtimeMillis} is the value of the elapsed realtime clock when {@code
- * suggestionMillis} was established. Note that the elapsed realtime clock is considered accurate
- * but it is volatile, so time suggestions cannot be persisted across device resets.
+ * {@code suggestionMillis} is the number of milliseconds elapsed since 1/1/1970 00:00:00 UTC
+ * according to the Unix time scale. {@code elapsedRealtimeMillis} is the value of the elapsed
+ * realtime clock when {@code suggestionMillis} was established. Note that the elapsed realtime
+ * clock is considered accurate but it is volatile, so time suggestions cannot be persisted across
+ * device resets.
  *
  * <p>{@code debugInfo} contains debugging metadata associated with the suggestion. This is used to
  * record why the suggestion exists and how it was entered. This information exists only to aid in
@@ -83,7 +84,7 @@ public final class ExternalTimeSuggestion implements Parcelable {
             };
 
     @NonNull
-    private final TimestampedValue<Long> mUtcTime;
+    private final TimestampedValue<Long> mUnixEpochTime;
     @Nullable
     private ArrayList<String> mDebugInfo;
 
@@ -92,12 +93,12 @@ public final class ExternalTimeSuggestion implements Parcelable {
      * ExternalTimeSuggestion} for more details.
      *
      * @param elapsedRealtimeMillis the elapsed realtime clock reference for the suggestion
-     * @param suggestionMillis      the suggested UTC time in milliseconds since the start of the
+     * @param suggestionMillis      the suggested time in milliseconds since the start of the
      *                              Unix epoch
      */
     public ExternalTimeSuggestion(@ElapsedRealtimeLong long elapsedRealtimeMillis,
             @CurrentTimeMillisLong long suggestionMillis) {
-        mUtcTime = new TimestampedValue(elapsedRealtimeMillis, suggestionMillis);
+        mUnixEpochTime = new TimestampedValue(elapsedRealtimeMillis, suggestionMillis);
     }
 
     private static ExternalTimeSuggestion createFromParcel(Parcel in) {
@@ -117,7 +118,7 @@ public final class ExternalTimeSuggestion implements Parcelable {
 
     @Override
     public void writeToParcel(@NonNull Parcel dest, int flags) {
-        dest.writeParcelable(mUtcTime, 0);
+        dest.writeParcelable(mUnixEpochTime, 0);
         dest.writeList(mDebugInfo);
     }
 
@@ -125,8 +126,8 @@ public final class ExternalTimeSuggestion implements Parcelable {
      * {@hide}
      */
     @NonNull
-    public TimestampedValue<Long> getUtcTime() {
-        return mUtcTime;
+    public TimestampedValue<Long> getUnixEpochTime() {
+        return mUnixEpochTime;
     }
 
     /**
@@ -160,17 +161,18 @@ public final class ExternalTimeSuggestion implements Parcelable {
             return false;
         }
         ExternalTimeSuggestion that = (ExternalTimeSuggestion) o;
-        return Objects.equals(mUtcTime, that.mUtcTime);
+        return Objects.equals(mUnixEpochTime, that.mUnixEpochTime);
     }
 
     @Override
     public int hashCode() {
-        return Objects.hash(mUtcTime);
+        return Objects.hash(mUnixEpochTime);
     }
 
     @Override
     public String toString() {
-        return "ExternalTimeSuggestion{" + "mUtcTime=" + mUtcTime + ", mDebugInfo=" + mDebugInfo
+        return "ExternalTimeSuggestion{" + "mUnixEpochTime=" + mUnixEpochTime
+                + ", mDebugInfo=" + mDebugInfo
                 + '}';
     }
 }
diff --git a/core/java/android/app/timedetector/GnssTimeSuggestion.java b/core/java/android/app/timedetector/GnssTimeSuggestion.java
index 8ccff6227c79..463e5f081c4f 100644
--- a/core/java/android/app/timedetector/GnssTimeSuggestion.java
+++ b/core/java/android/app/timedetector/GnssTimeSuggestion.java
@@ -31,11 +31,11 @@ import java.util.Objects;
 /**
  * A time signal from a GNSS source.
  *
- * <p>{@code utcTime} is the suggested time. The {@code utcTime.value} is the number of milliseconds
- * elapsed since 1/1/1970 00:00:00 UTC. The {@code utcTime.referenceTimeMillis} is the value of the
- * elapsed realtime clock when the {@code utcTime.value} was established.
- * Note that the elapsed realtime clock is considered accurate but it is volatile, so time
- * suggestions cannot be persisted across device resets.
+ * <p>{@code unixEpochTime} is the suggested time. The {@code unixEpochTime.value} is the number of
+ * milliseconds elapsed since 1/1/1970 00:00:00 UTC according to the Unix time system. The {@code
+ * unixEpochTime.referenceTimeMillis} is the value of the elapsed realtime clock when the {@code
+ * unixEpochTime.value} was established. Note that the elapsed realtime clock is considered accurate
+ * but it is volatile, so time suggestions cannot be persisted across device resets.
  *
  * <p>{@code debugInfo} contains debugging metadata associated with the suggestion. This is used to
  * record why the suggestion exists and how it was entered. This information exists only to aid in
@@ -57,19 +57,21 @@ public final class GnssTimeSuggestion implements Parcelable {
                 }
             };
 
-    @NonNull private final TimestampedValue<Long> mUtcTime;
+    @NonNull private final TimestampedValue<Long> mUnixEpochTime;
     @Nullable private ArrayList<String> mDebugInfo;
 
-    public GnssTimeSuggestion(@NonNull TimestampedValue<Long> utcTime) {
-        mUtcTime = Objects.requireNonNull(utcTime);
-        Objects.requireNonNull(utcTime.getValue());
+    public GnssTimeSuggestion(@NonNull TimestampedValue<Long> unixEpochTime) {
+        mUnixEpochTime = Objects.requireNonNull(unixEpochTime);
+        Objects.requireNonNull(unixEpochTime.getValue());
     }
 
     private static GnssTimeSuggestion createFromParcel(Parcel in) {
-        TimestampedValue<Long> utcTime = in.readParcelable(null /* classLoader */, android.os.TimestampedValue.class);
-        GnssTimeSuggestion suggestion = new GnssTimeSuggestion(utcTime);
+        TimestampedValue<Long> unixEpochTime =
+                in.readParcelable(null /* classLoader */, android.os.TimestampedValue.class);
+        GnssTimeSuggestion suggestion = new GnssTimeSuggestion(unixEpochTime);
         @SuppressWarnings("unchecked")
-        ArrayList<String> debugInfo = (ArrayList<String>) in.readArrayList(null /* classLoader */, java.lang.String.class);
+        ArrayList<String> debugInfo = (ArrayList<String>) in.readArrayList(
+                null /* classLoader */, java.lang.String.class);
         suggestion.mDebugInfo = debugInfo;
         return suggestion;
     }
@@ -81,13 +83,13 @@ public final class GnssTimeSuggestion implements Parcelable {
 
     @Override
     public void writeToParcel(@NonNull Parcel dest, int flags) {
-        dest.writeParcelable(mUtcTime, 0);
+        dest.writeParcelable(mUnixEpochTime, 0);
         dest.writeList(mDebugInfo);
     }
 
     @NonNull
-    public TimestampedValue<Long> getUtcTime() {
-        return mUtcTime;
+    public TimestampedValue<Long> getUnixEpochTime() {
+        return mUnixEpochTime;
     }
 
     @NonNull
@@ -117,18 +119,18 @@ public final class GnssTimeSuggestion implements Parcelable {
             return false;
         }
         GnssTimeSuggestion that = (GnssTimeSuggestion) o;
-        return Objects.equals(mUtcTime, that.mUtcTime);
+        return Objects.equals(mUnixEpochTime, that.mUnixEpochTime);
     }
 
     @Override
     public int hashCode() {
-        return Objects.hash(mUtcTime);
+        return Objects.hash(mUnixEpochTime);
     }
 
     @Override
     public String toString() {
         return "GnssTimeSuggestion{"
-                + "mUtcTime=" + mUtcTime
+                + "mUnixEpochTime=" + mUnixEpochTime
                 + ", mDebugInfo=" + mDebugInfo
                 + '}';
     }
diff --git a/core/java/android/app/timedetector/ManualTimeSuggestion.java b/core/java/android/app/timedetector/ManualTimeSuggestion.java
index 1699a5f8c8ae..247d97190d0c 100644
--- a/core/java/android/app/timedetector/ManualTimeSuggestion.java
+++ b/core/java/android/app/timedetector/ManualTimeSuggestion.java
@@ -31,9 +31,9 @@ import java.util.Objects;
 /**
  * A time signal from a manual (user provided) source.
  *
- * <p>{@code utcTime} is the suggested time. The {@code utcTime.value} is the number of milliseconds
- * elapsed since 1/1/1970 00:00:00 UTC. The {@code utcTime.referenceTimeMillis} is the value of the
- * elapsed realtime clock when the {@code utcTime.value} was established.
+ * <p>{@code unixEpochTime} is the suggested time. The {@code unixEpochTime.value} is the number of
+ * milliseconds elapsed since 1/1/1970 00:00:00 UTC. The {@code unixEpochTime.referenceTimeMillis}
+ * is the value of the elapsed realtime clock when the {@code unixEpochTime.value} was established.
  * Note that the elapsed realtime clock is considered accurate but it is volatile, so time
  * suggestions cannot be persisted across device resets.
  *
@@ -57,19 +57,21 @@ public final class ManualTimeSuggestion implements Parcelable {
                 }
             };
 
-    @NonNull private final TimestampedValue<Long> mUtcTime;
+    @NonNull private final TimestampedValue<Long> mUnixEpochTime;
     @Nullable private ArrayList<String> mDebugInfo;
 
-    public ManualTimeSuggestion(@NonNull TimestampedValue<Long> utcTime) {
-        mUtcTime = Objects.requireNonNull(utcTime);
-        Objects.requireNonNull(utcTime.getValue());
+    public ManualTimeSuggestion(@NonNull TimestampedValue<Long> unixEpochTime) {
+        mUnixEpochTime = Objects.requireNonNull(unixEpochTime);
+        Objects.requireNonNull(unixEpochTime.getValue());
     }
 
     private static ManualTimeSuggestion createFromParcel(Parcel in) {
-        TimestampedValue<Long> utcTime = in.readParcelable(null /* classLoader */, android.os.TimestampedValue.class);
-        ManualTimeSuggestion suggestion = new ManualTimeSuggestion(utcTime);
+        TimestampedValue<Long> unixEpochTime =
+                in.readParcelable(null /* classLoader */, android.os.TimestampedValue.class);
+        ManualTimeSuggestion suggestion = new ManualTimeSuggestion(unixEpochTime);
         @SuppressWarnings("unchecked")
-        ArrayList<String> debugInfo = (ArrayList<String>) in.readArrayList(null /* classLoader */, java.lang.String.class);
+        ArrayList<String> debugInfo = (ArrayList<String>) in.readArrayList(
+                null /* classLoader */, java.lang.String.class);
         suggestion.mDebugInfo = debugInfo;
         return suggestion;
     }
@@ -81,13 +83,13 @@ public final class ManualTimeSuggestion implements Parcelable {
 
     @Override
     public void writeToParcel(@NonNull Parcel dest, int flags) {
-        dest.writeParcelable(mUtcTime, 0);
+        dest.writeParcelable(mUnixEpochTime, 0);
         dest.writeList(mDebugInfo);
     }
 
     @NonNull
-    public TimestampedValue<Long> getUtcTime() {
-        return mUtcTime;
+    public TimestampedValue<Long> getUnixEpochTime() {
+        return mUnixEpochTime;
     }
 
     @NonNull
@@ -117,18 +119,18 @@ public final class ManualTimeSuggestion implements Parcelable {
             return false;
         }
         ManualTimeSuggestion that = (ManualTimeSuggestion) o;
-        return Objects.equals(mUtcTime, that.mUtcTime);
+        return Objects.equals(mUnixEpochTime, that.mUnixEpochTime);
     }
 
     @Override
     public int hashCode() {
-        return Objects.hash(mUtcTime);
+        return Objects.hash(mUnixEpochTime);
     }
 
     @Override
     public String toString() {
         return "ManualTimeSuggestion{"
-                + "mUtcTime=" + mUtcTime
+                + "mUnixEpochTime=" + mUnixEpochTime
                 + ", mDebugInfo=" + mDebugInfo
                 + '}';
     }
diff --git a/core/java/android/app/timedetector/NetworkTimeSuggestion.java b/core/java/android/app/timedetector/NetworkTimeSuggestion.java
index 20300832d2fc..f620bc912ec9 100644
--- a/core/java/android/app/timedetector/NetworkTimeSuggestion.java
+++ b/core/java/android/app/timedetector/NetworkTimeSuggestion.java
@@ -31,11 +31,12 @@ import java.util.Objects;
 /**
  * A time signal from a network time source like NTP.
  *
- * <p>{@code utcTime} contains the suggested time. The {@code utcTime.value} is the number of
- * milliseconds elapsed since 1/1/1970 00:00:00 UTC. The {@code utcTime.referenceTimeMillis} is the
- * value of the elapsed realtime clock when the {@code utcTime.value} was established.
- * Note that the elapsed realtime clock is considered accurate but it is volatile, so time
- * suggestions cannot be persisted across device resets.
+ * <p>{@code unixEpochTime} contains the suggested time. The {@code unixEpochTime.value} is the
+ * number of milliseconds elapsed since 1/1/1970 00:00:00 UTC according to the Unix time system.
+ * The {@code unixEpochTime.referenceTimeMillis} is the value of the elapsed realtime clock when
+ * the {@code unixEpochTime.value} was established. Note that the elapsed realtime clock is
+ * considered accurate but it is volatile, so time suggestions cannot be persisted across device
+ * resets.
  *
  * <p>{@code debugInfo} contains debugging metadata associated with the suggestion. This is used to
  * record why the suggestion exists and how it was determined. This information exists only to aid
@@ -57,19 +58,21 @@ public final class NetworkTimeSuggestion implements Parcelable {
                 }
             };
 
-    @NonNull private final TimestampedValue<Long> mUtcTime;
+    @NonNull private final TimestampedValue<Long> mUnixEpochTime;
     @Nullable private ArrayList<String> mDebugInfo;
 
-    public NetworkTimeSuggestion(@NonNull TimestampedValue<Long> utcTime) {
-        mUtcTime = Objects.requireNonNull(utcTime);
-        Objects.requireNonNull(utcTime.getValue());
+    public NetworkTimeSuggestion(@NonNull TimestampedValue<Long> unixEpochTime) {
+        mUnixEpochTime = Objects.requireNonNull(unixEpochTime);
+        Objects.requireNonNull(unixEpochTime.getValue());
     }
 
     private static NetworkTimeSuggestion createFromParcel(Parcel in) {
-        TimestampedValue<Long> utcTime = in.readParcelable(null /* classLoader */, android.os.TimestampedValue.class);
-        NetworkTimeSuggestion suggestion = new NetworkTimeSuggestion(utcTime);
+        TimestampedValue<Long> unixEpochTime =
+                in.readParcelable(null /* classLoader */, android.os.TimestampedValue.class);
+        NetworkTimeSuggestion suggestion = new NetworkTimeSuggestion(unixEpochTime);
         @SuppressWarnings("unchecked")
-        ArrayList<String> debugInfo = (ArrayList<String>) in.readArrayList(null /* classLoader */, java.lang.String.class);
+        ArrayList<String> debugInfo = (ArrayList<String>) in.readArrayList(
+                null /* classLoader */, java.lang.String.class);
         suggestion.mDebugInfo = debugInfo;
         return suggestion;
     }
@@ -81,13 +84,13 @@ public final class NetworkTimeSuggestion implements Parcelable {
 
     @Override
     public void writeToParcel(@NonNull Parcel dest, int flags) {
-        dest.writeParcelable(mUtcTime, 0);
+        dest.writeParcelable(mUnixEpochTime, 0);
         dest.writeList(mDebugInfo);
     }
 
     @NonNull
-    public TimestampedValue<Long> getUtcTime() {
-        return mUtcTime;
+    public TimestampedValue<Long> getUnixEpochTime() {
+        return mUnixEpochTime;
     }
 
     @NonNull
@@ -117,18 +120,18 @@ public final class NetworkTimeSuggestion implements Parcelable {
             return false;
         }
         NetworkTimeSuggestion that = (NetworkTimeSuggestion) o;
-        return Objects.equals(mUtcTime, that.mUtcTime);
+        return Objects.equals(mUnixEpochTime, that.mUnixEpochTime);
     }
 
     @Override
     public int hashCode() {
-        return Objects.hash(mUtcTime);
+        return Objects.hash(mUnixEpochTime);
     }
 
     @Override
     public String toString() {
         return "NetworkTimeSuggestion{"
-                + "mUtcTime=" + mUtcTime
+                + "mUnixEpochTime=" + mUnixEpochTime
                 + ", mDebugInfo=" + mDebugInfo
                 + '}';
     }
diff --git a/core/java/android/app/timedetector/TelephonyTimeSuggestion.java b/core/java/android/app/timedetector/TelephonyTimeSuggestion.java
index 52d0bbea701e..1fa392a701d1 100644
--- a/core/java/android/app/timedetector/TelephonyTimeSuggestion.java
+++ b/core/java/android/app/timedetector/TelephonyTimeSuggestion.java
@@ -34,12 +34,12 @@ import java.util.Objects;
  * <p>{@code slotIndex} identifies the suggestion source. This enables detection logic to identify
  * suggestions from the same source when there are several in use.
  *
- * <p>{@code utcTime}. When not {@code null}, the {@code utcTime.value} is the number of
- * milliseconds elapsed since 1/1/1970 00:00:00 UTC. The {@code utcTime.referenceTimeMillis} is the
- * value of the elapsed realtime clock when the {@code utcTime.value} was established.
+ * <p>{@code unixEpochTime}. When not {@code null}, the {@code unixEpochTime.value} is the number of
+ * milliseconds elapsed since 1/1/1970 00:00:00 UTC. The {@code unixEpochTime.referenceTimeMillis}
+ * is the value of the elapsed realtime clock when the {@code unixEpochTime.value} was established.
  * Note that the elapsed realtime clock is considered accurate but it is volatile, so time
- * suggestions cannot be persisted across device resets. {@code utcTime} can be {@code null} to
- * indicate that the telephony source has entered an "un-opinionated" state and any previous
+ * suggestions cannot be persisted across device resets. {@code unixEpochTime} can be {@code null}
+ * to indicate that the telephony source has entered an "un-opinionated" state and any previous
  * suggestion from the source is being withdrawn.
  *
  * <p>{@code debugInfo} contains debugging metadata associated with the suggestion. This is used to
@@ -65,22 +65,25 @@ public final class TelephonyTimeSuggestion implements Parcelable {
             };
 
     private final int mSlotIndex;
-    @Nullable private final TimestampedValue<Long> mUtcTime;
+    @Nullable private final TimestampedValue<Long> mUnixEpochTime;
     @Nullable private ArrayList<String> mDebugInfo;
 
     private TelephonyTimeSuggestion(Builder builder) {
         mSlotIndex = builder.mSlotIndex;
-        mUtcTime = builder.mUtcTime;
+        mUnixEpochTime = builder.mUnixEpochTime;
         mDebugInfo = builder.mDebugInfo != null ? new ArrayList<>(builder.mDebugInfo) : null;
     }
 
     private static TelephonyTimeSuggestion createFromParcel(Parcel in) {
         int slotIndex = in.readInt();
+        TimestampedValue<Long> unixEpochTime =
+                in.readParcelable(null /* classLoader */, android.os.TimestampedValue.class);
         TelephonyTimeSuggestion suggestion = new TelephonyTimeSuggestion.Builder(slotIndex)
-                .setUtcTime(in.readParcelable(null /* classLoader */, android.os.TimestampedValue.class))
+                .setUnixEpochTime(unixEpochTime)
                 .build();
         @SuppressWarnings("unchecked")
-        ArrayList<String> debugInfo = (ArrayList<String>) in.readArrayList(null /* classLoader */, java.lang.String.class);
+        ArrayList<String> debugInfo = (ArrayList<String>) in.readArrayList(
+                null /* classLoader */, java.lang.String.class);
         if (debugInfo != null) {
             suggestion.addDebugInfo(debugInfo);
         }
@@ -95,7 +98,7 @@ public final class TelephonyTimeSuggestion implements Parcelable {
     @Override
     public void writeToParcel(@NonNull Parcel dest, int flags) {
         dest.writeInt(mSlotIndex);
-        dest.writeParcelable(mUtcTime, 0);
+        dest.writeParcelable(mUnixEpochTime, 0);
         dest.writeList(mDebugInfo);
     }
 
@@ -111,11 +114,11 @@ public final class TelephonyTimeSuggestion implements Parcelable {
     /**
      * Returns the suggested time or {@code null} if there isn't one.
      *
-     * <p>See {@link TelephonyTimeSuggestion} for more information about {@code utcTime}.
+     * <p>See {@link TelephonyTimeSuggestion} for more information about {@code unixEpochTime}.
      */
     @Nullable
-    public TimestampedValue<Long> getUtcTime() {
-        return mUtcTime;
+    public TimestampedValue<Long> getUnixEpochTime() {
+        return mUnixEpochTime;
     }
 
     /**
@@ -163,19 +166,19 @@ public final class TelephonyTimeSuggestion implements Parcelable {
         }
         TelephonyTimeSuggestion that = (TelephonyTimeSuggestion) o;
         return mSlotIndex == that.mSlotIndex
-                && Objects.equals(mUtcTime, that.mUtcTime);
+                && Objects.equals(mUnixEpochTime, that.mUnixEpochTime);
     }
 
     @Override
     public int hashCode() {
-        return Objects.hash(mSlotIndex, mUtcTime);
+        return Objects.hash(mSlotIndex, mUnixEpochTime);
     }
 
     @Override
     public String toString() {
         return "TelephonyTimeSuggestion{"
                 + "mSlotIndex='" + mSlotIndex + '\''
-                + ", mUtcTime=" + mUtcTime
+                + ", mUnixEpochTime=" + mUnixEpochTime
                 + ", mDebugInfo=" + mDebugInfo
                 + '}';
     }
@@ -187,7 +190,7 @@ public final class TelephonyTimeSuggestion implements Parcelable {
      */
     public static final class Builder {
         private final int mSlotIndex;
-        @Nullable private TimestampedValue<Long> mUtcTime;
+        @Nullable private TimestampedValue<Long> mUnixEpochTime;
         @Nullable private List<String> mDebugInfo;
 
         /**
@@ -202,16 +205,16 @@ public final class TelephonyTimeSuggestion implements Parcelable {
         /**
          * Returns the builder for call chaining.
          *
-         * <p>See {@link TelephonyTimeSuggestion} for more information about {@code utcTime}.
+         * <p>See {@link TelephonyTimeSuggestion} for more information about {@code unixEpochTime}.
          */
         @NonNull
-        public Builder setUtcTime(@Nullable TimestampedValue<Long> utcTime) {
-            if (utcTime != null) {
-                // utcTime can be null, but the value it holds cannot.
-                Objects.requireNonNull(utcTime.getValue());
+        public Builder setUnixEpochTime(@Nullable TimestampedValue<Long> unixEpochTime) {
+            if (unixEpochTime != null) {
+                // unixEpochTime can be null, but the value it holds cannot.
+                Objects.requireNonNull(unixEpochTime.getValue());
             }
 
-            mUtcTime = utcTime;
+            mUnixEpochTime = unixEpochTime;
             return this;
         }