Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 69c6a42d authored by Neil Fuller's avatar Neil Fuller
Browse files

Switch "UTC time" to "Unix epoch time" 

This is more correct.

Bug: 218802673
Test: Compile only
Merged-In: Ic477c021529a94b4a3665426b7daaf6567fa311a
Change-Id: Ic477c021529a94b4a3665426b7daaf6567fa311a
parent 3fb0bce7

core/java/android/app/time/ExternalTimeSuggestion.java

+17 −15
Original line number Diff line number Diff line
@@ -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

                + '}';

    }

}

core/java/android/app/timedetector/GnssTimeSuggestion.java

+17 −17
Original line number Diff line number Diff line
@@ -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,17 +57,17 @@ 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 */);

        GnssTimeSuggestion suggestion = new GnssTimeSuggestion(utcTime);

        TimestampedValue<Long> unixEpochTime = in.readParcelable(null /* classLoader */);

        GnssTimeSuggestion suggestion = new GnssTimeSuggestion(unixEpochTime);

        @SuppressWarnings("unchecked")

        ArrayList<String> debugInfo = (ArrayList<String>) in.readArrayList(null /* classLoader */);

        suggestion.mDebugInfo = debugInfo;
@@ -81,13 +81,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 +117,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

                + '}';

    }

core/java/android/app/timedetector/ManualTimeSuggestion.java

+15 −15
Original line number Diff line number Diff line
@@ -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,17 +57,17 @@ 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 */);

        ManualTimeSuggestion suggestion = new ManualTimeSuggestion(utcTime);

        TimestampedValue<Long> unixEpochTime = in.readParcelable(null /* classLoader */);

        ManualTimeSuggestion suggestion = new ManualTimeSuggestion(unixEpochTime);

        @SuppressWarnings("unchecked")

        ArrayList<String> debugInfo = (ArrayList<String>) in.readArrayList(null /* classLoader */);

        suggestion.mDebugInfo = debugInfo;
@@ -81,13 +81,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 +117,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

                + '}';

    }

core/java/android/app/timedetector/NetworkTimeSuggestion.java

+18 −17
Original line number Diff line number Diff line
@@ -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,17 +58,17 @@ 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 */);

        NetworkTimeSuggestion suggestion = new NetworkTimeSuggestion(utcTime);

        TimestampedValue<Long> unixEpochTime = in.readParcelable(null /* classLoader */);

        NetworkTimeSuggestion suggestion = new NetworkTimeSuggestion(unixEpochTime);

        @SuppressWarnings("unchecked")

        ArrayList<String> debugInfo = (ArrayList<String>) in.readArrayList(null /* classLoader */);

        suggestion.mDebugInfo = debugInfo;
@@ -81,13 +82,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 +118,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

                + '}';

    }

core/java/android/app/timedetector/TelephonyTimeSuggestion.java

+23 −22
Original line number Diff line number Diff line
@@ -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,19 +65,20 @@ 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 */);

        TelephonyTimeSuggestion suggestion = new TelephonyTimeSuggestion.Builder(slotIndex)

                .setUtcTime(in.readParcelable(null /* classLoader */))

                .setUnixEpochTime(unixEpochTime)

                .build();

        @SuppressWarnings("unchecked")

        ArrayList<String> debugInfo = (ArrayList<String>) in.readArrayList(null /* classLoader */);
@@ -95,7 +96,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 +112,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 +164,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 +188,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 +203,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;

        }