Merge "Switch "UTC time" to "Unix epoch time"" (1ecf1d24) · Commits · e / os / android_frameworks_base

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;
		}