diff --git a/core/java/android/app/timedetector/ManualTimeSuggestion.java b/core/java/android/app/timedetector/ManualTimeSuggestion.java index 50de738555113..da51ce2a6aff1 100644 --- a/core/java/android/app/timedetector/ManualTimeSuggestion.java +++ b/core/java/android/app/timedetector/ManualTimeSuggestion.java @@ -29,10 +29,18 @@ import java.util.List; import java.util.Objects; /** - * A time signal from a manual (user provided) source. The value consists of the number of - * milliseconds elapsed since 1/1/1970 00:00:00 UTC and the time according to the elapsed realtime - * clock when that number was established. The elapsed realtime clock is considered accurate but - * volatile, so time signals must not be persisted across device resets. + * A time signal from a manual (user provided) source. + * + *

{@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. + * + *

{@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 + * debugging and therefore is used by {@link #toString()}, but it is not for use in detection + * logic and is not considered in {@link #hashCode()} or {@link #equals(Object)}. * * @hide */ @@ -49,10 +57,8 @@ public final class ManualTimeSuggestion implements Parcelable { } }; - @NonNull - private final TimestampedValue mUtcTime; - @Nullable - private ArrayList mDebugInfo; + @NonNull private final TimestampedValue mUtcTime; + @Nullable private ArrayList mDebugInfo; public ManualTimeSuggestion(@NonNull TimestampedValue utcTime) { mUtcTime = Objects.requireNonNull(utcTime); diff --git a/core/java/android/app/timedetector/NetworkTimeSuggestion.java b/core/java/android/app/timedetector/NetworkTimeSuggestion.java index 17e9c5a79fa57..89fd6f31e0424 100644 --- a/core/java/android/app/timedetector/NetworkTimeSuggestion.java +++ b/core/java/android/app/timedetector/NetworkTimeSuggestion.java @@ -29,10 +29,18 @@ import java.util.List; import java.util.Objects; /** - * A time signal from a network time source like NTP. The value consists of the number of - * milliseconds elapsed since 1/1/1970 00:00:00 UTC and the time according to the elapsed realtime - * clock when that number was established. The elapsed realtime clock is considered accurate but - * volatile, so time signals must not be persisted across device resets. + * A time signal from a network time source like NTP. + * + *

{@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. + * + *

{@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 + * in debugging and therefore is used by {@link #toString()}, but it is not for use in detection + * logic and is not considered in {@link #hashCode()} or {@link #equals(Object)}. * * @hide */ @@ -49,10 +57,8 @@ public final class NetworkTimeSuggestion implements Parcelable { } }; - @NonNull - private final TimestampedValue mUtcTime; - @Nullable - private ArrayList mDebugInfo; + @NonNull private final TimestampedValue mUtcTime; + @Nullable private ArrayList mDebugInfo; public NetworkTimeSuggestion(@NonNull TimestampedValue utcTime) { mUtcTime = Objects.requireNonNull(utcTime); diff --git a/core/java/android/app/timedetector/PhoneTimeSuggestion.java b/core/java/android/app/timedetector/PhoneTimeSuggestion.java index eab88383fa1d6..16288e82d4524 100644 --- a/core/java/android/app/timedetector/PhoneTimeSuggestion.java +++ b/core/java/android/app/timedetector/PhoneTimeSuggestion.java @@ -32,12 +32,22 @@ import java.util.Objects; * A time suggestion from an identified telephony source. e.g. from NITZ information from a specific * radio. * - *

The time value can be {@code null} to indicate that the telephony source has entered an - * "un-opinionated" state and any previous suggestions from the source are being withdrawn. When not - * {@code null}, the value consists of the number of milliseconds elapsed since 1/1/1970 00:00:00 - * UTC and the time according to the elapsed realtime clock when that number was established. The - * elapsed realtime clock is considered accurate but volatile, so time suggestions must not be - * persisted across device resets. + *

{@code slotIndex} identifies the suggestion source. This enables detection logic to identify + * suggestions from the same source when there are several in use. + * + *

{@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. + * 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 + * suggestion from the source is being withdrawn. + * + *

{@code debugInfo} contains debugging metadata associated with the suggestion. This is used to + * record why the suggestion exists, e.g. what triggered it to be made and what heuristic was used + * to determine the time or its absence. This information exists only to aid in debugging and + * therefore is used by {@link #toString()}, but it is not for use in detection logic and is not + * considered in {@link #hashCode()} or {@link #equals(Object)}. * * @hide */ @@ -93,16 +103,18 @@ public final class PhoneTimeSuggestion implements Parcelable { } /** - * Returns an identifier for the source of this suggestion. When a device has several sim slots - * or equivalent, it is used to identify which one the suggestion is from. + * Returns an identifier for the source of this suggestion. + * + *

See {@link PhoneTimeSuggestion} for more information about {@code slotIndex}. */ public int getSlotIndex() { return mSlotIndex; } /** - * Returns the suggestion. {@code null} means that the caller is no longer sure what time it - * is. + * Returns the suggested time or {@code null} if there isn't one. + * + *

See {@link PhoneTimeSuggestion} for more information about {@code utcTime}. */ @Nullable public TimestampedValue getUtcTime() { @@ -110,8 +122,9 @@ public final class PhoneTimeSuggestion implements Parcelable { } /** - * Returns debug metadata for the suggestion. The information is present in {@link #toString()} - * but is not considered for {@link #equals(Object)} and {@link #hashCode()}. + * Returns debug metadata for the suggestion. + * + *

See {@link PhoneTimeSuggestion} for more information about {@code debugInfo}. */ @NonNull public List getDebugInfo() { @@ -120,9 +133,9 @@ public final class PhoneTimeSuggestion implements Parcelable { } /** - * Associates information with the instance that can be useful for debugging / logging. The - * information is present in {@link #toString()} but is not considered for - * {@link #equals(Object)} and {@link #hashCode()}. + * Associates information with the instance that can be useful for debugging / logging. + * + *

See {@link PhoneTimeSuggestion} for more information about {@code debugInfo}. */ public void addDebugInfo(@NonNull String debugInfo) { if (mDebugInfo == null) { @@ -132,9 +145,9 @@ public final class PhoneTimeSuggestion implements Parcelable { } /** - * Associates information with the instance that can be useful for debugging / logging. The - * information is present in {@link #toString()} but is not considered for - * {@link #equals(Object)} and {@link #hashCode()}. + * Associates information with the instance that can be useful for debugging / logging. + * + *

See {@link PhoneTimeSuggestion} for more information about {@code debugInfo}. */ public void addDebugInfo(@NonNull List debugInfo) { if (mDebugInfo == null) { @@ -181,12 +194,20 @@ public final class PhoneTimeSuggestion implements Parcelable { @Nullable private TimestampedValue mUtcTime; @Nullable private List mDebugInfo; - /** Creates a builder with the specified {@code slotIndex}. */ + /** + * Creates a builder with the specified {@code slotIndex}. + * + *

See {@link PhoneTimeSuggestion} for more information about {@code slotIndex}. + */ public Builder(int slotIndex) { mSlotIndex = slotIndex; } - /** Returns the builder for call chaining. */ + /** + * Returns the builder for call chaining. + * + *

See {@link PhoneTimeSuggestion} for more information about {@code utcTime}. + */ @NonNull public Builder setUtcTime(@Nullable TimestampedValue utcTime) { if (utcTime != null) { @@ -198,7 +219,11 @@ public final class PhoneTimeSuggestion implements Parcelable { return this; } - /** Returns the builder for call chaining. */ + /** + * Returns the builder for call chaining. + * + *

See {@link PhoneTimeSuggestion} for more information about {@code debugInfo}. + */ @NonNull public Builder addDebugInfo(@NonNull String debugInfo) { if (mDebugInfo == null) { diff --git a/core/java/android/app/timezonedetector/ManualTimeZoneSuggestion.java b/core/java/android/app/timezonedetector/ManualTimeZoneSuggestion.java index a6b953b42f8fc..3a9adc72aab16 100644 --- a/core/java/android/app/timezonedetector/ManualTimeZoneSuggestion.java +++ b/core/java/android/app/timezonedetector/ManualTimeZoneSuggestion.java @@ -28,10 +28,14 @@ import java.util.List; import java.util.Objects; /** - * A time signal from a manual (user provided) source. The value consists of the number of - * milliseconds elapsed since 1/1/1970 00:00:00 UTC and the time according to the elapsed realtime - * clock when that number was established. The elapsed realtime clock is considered accurate but - * volatile, so time signals must not be persisted across device resets. + * A time signal from a manual (user provided) source. + * + *

{@code zoneId} contains the suggested time zone ID, e.g. "America/Los_Angeles". + * + *

{@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 + * debugging and therefore is used by {@link #toString()}, but it is not for use in detection logic + * and is not considered in {@link #hashCode()} or {@link #equals(Object)}. * * @hide */ @@ -48,10 +52,8 @@ public final class ManualTimeZoneSuggestion implements Parcelable { } }; - @NonNull - private final String mZoneId; - @Nullable - private ArrayList mDebugInfo; + @NonNull private final String mZoneId; + @Nullable private ArrayList mDebugInfo; public ManualTimeZoneSuggestion(@NonNull String zoneId) { mZoneId = Objects.requireNonNull(zoneId); diff --git a/core/java/android/app/timezonedetector/PhoneTimeZoneSuggestion.java b/core/java/android/app/timezonedetector/PhoneTimeZoneSuggestion.java index ebaf951130ca2..0544ccd3f4c59 100644 --- a/core/java/android/app/timezonedetector/PhoneTimeZoneSuggestion.java +++ b/core/java/android/app/timezonedetector/PhoneTimeZoneSuggestion.java @@ -34,10 +34,14 @@ import java.util.Objects; * A time zone suggestion from an identified telephony source, e.g. from MCC and NITZ information * associated with a specific radio. * - *

The time zone ID can be {@code null} to indicate that the telephony source has entered an - * "un-opinionated" state and any previous suggestions from that source are being withdrawn. - * When not {@code null}, the value consists of a suggested time zone ID and metadata that can be - * used to judge quality / certainty of the suggestion. + *

{@code slotIndex} identifies the suggestion source. This enables detection logic to identify + * suggestions from the same source when there are several in use. + * + *

{@code zoneId}. When not {@code null}, {@code zoneId} contains the suggested time zone ID, + * e.g. "America/Los_Angeles". Suggestion metadata like {@code matchType} and {@code quality} can be + * used to judge quality / certainty of the suggestion. {@code zoneId} can be {@code null} to + * indicate that the telephony source has entered an "un-opinionated" state and any previous + * suggestion from the same source is being withdrawn. * *

{@code matchType} must be set to {@link #MATCH_TYPE_NA} when {@code zoneId} is {@code null}, * and one of the other {@code MATCH_TYPE_} values when it is not {@code null}. @@ -45,6 +49,12 @@ import java.util.Objects; *

{@code quality} must be set to {@link #QUALITY_NA} when {@code zoneId} is {@code null}, * and one of the other {@code QUALITY_} values when it is not {@code null}. * + *

{@code debugInfo} contains debugging metadata associated with the suggestion. This is used to + * record why the suggestion exists, e.g. what triggered it to be made and what heuristic was used + * to determine the time zone or its absence. This information exists only to aid in debugging and + * therefore is used by {@link #toString()}, but it is not for use in detection logic and is not + * considered in {@link #hashCode()} or {@link #equals(Object)}. + * * @hide */ @SystemApi(client = SystemApi.Client.MODULE_LIBRARIES) @@ -131,38 +141,11 @@ public final class PhoneTimeZoneSuggestion implements Parcelable { */ public static final int QUALITY_MULTIPLE_ZONES_WITH_DIFFERENT_OFFSETS = 3; - /** - * The ID of the phone this suggestion is associated with. For multiple-sim devices this - * helps to establish source so filtering / stickiness can be implemented. - */ private final int mSlotIndex; - - /** - * The suggestion. {@code null} means there is no current suggestion and any previous suggestion - * should be forgotten. - */ - @Nullable - private final String mZoneId; - - /** - * The type of "match" used to establish the time zone. - */ - @MatchType - private final int mMatchType; - - /** - * A measure of the quality of the time zone suggestion, i.e. how confident one could be in - * it. - */ - @Quality - private final int mQuality; - - /** - * Free-form debug information about how the suggestion was derived. Used for debug only, - * intentionally not used in equals(), etc. - */ - @Nullable - private List mDebugInfo; + @Nullable private final String mZoneId; + @MatchType private final int mMatchType; + @Quality private final int mQuality; + @Nullable private List mDebugInfo; private PhoneTimeZoneSuggestion(Builder builder) { mSlotIndex = builder.mSlotIndex; @@ -203,8 +186,9 @@ public final class PhoneTimeZoneSuggestion implements Parcelable { } /** - * Returns an identifier for the source of this suggestion. When a device has several sim slots - * or equivalent, it is used to identify which one the suggestion is from. + * Returns an identifier for the source of this suggestion. + * + *

See {@link PhoneTimeZoneSuggestion} for more information about {@code slotIndex}. */ public int getSlotIndex() { return mSlotIndex; @@ -212,8 +196,9 @@ public final class PhoneTimeZoneSuggestion implements Parcelable { /** * Returns the suggested time zone Olson ID, e.g. "America/Los_Angeles". {@code null} means that - * the caller is no longer sure what the current time zone is. See - * {@link PhoneTimeZoneSuggestion} for the associated {@code matchType} / {@code quality} rules. + * the caller is no longer sure what the current time zone is. + * + *

See {@link PhoneTimeZoneSuggestion} for more information about {@code zoneId}. */ @Nullable public String getZoneId() { @@ -222,8 +207,9 @@ public final class PhoneTimeZoneSuggestion implements Parcelable { /** * Returns information about how the suggestion was determined which could be used to rank - * suggestions when several are available from different sources. See - * {@link PhoneTimeZoneSuggestion} for the associated rules. + * suggestions when several are available from different sources. + * + *

See {@link PhoneTimeZoneSuggestion} for more information about {@code matchType}. */ @MatchType public int getMatchType() { @@ -231,8 +217,9 @@ public final class PhoneTimeZoneSuggestion implements Parcelable { } /** - * Returns information about the likelihood of the suggested zone being correct. See - * {@link PhoneTimeZoneSuggestion} for the associated rules. + * Returns information about the likelihood of the suggested zone being correct. + * + *

See {@link PhoneTimeZoneSuggestion} for more information about {@code quality}. */ @Quality public int getQuality() { @@ -240,8 +227,9 @@ public final class PhoneTimeZoneSuggestion implements Parcelable { } /** - * Returns debug metadata for the suggestion. The information is present in {@link #toString()} - * but is not considered for {@link #equals(Object)} and {@link #hashCode()}. + * Returns debug metadata for the suggestion. + * + *

See {@link PhoneTimeZoneSuggestion} for more information about {@code debugInfo}. */ @NonNull public List getDebugInfo() { @@ -250,9 +238,9 @@ public final class PhoneTimeZoneSuggestion implements Parcelable { } /** - * Associates information with the instance that can be useful for debugging / logging. The - * information is present in {@link #toString()} but is not considered for - * {@link #equals(Object)} and {@link #hashCode()}. + * Associates information with the instance that can be useful for debugging / logging. + * + *

See {@link PhoneTimeZoneSuggestion} for more information about {@code debugInfo}. */ public void addDebugInfo(@NonNull String debugInfo) { if (mDebugInfo == null) { @@ -262,9 +250,9 @@ public final class PhoneTimeZoneSuggestion implements Parcelable { } /** - * Associates information with the instance that can be useful for debugging / logging. The - * information is present in {@link #toString()} but is not considered for - * {@link #equals(Object)} and {@link #hashCode()}. + * Associates information with the instance that can be useful for debugging / logging. + * + *

See {@link PhoneTimeZoneSuggestion} for more information about {@code debugInfo}. */ public void addDebugInfo(@NonNull List debugInfo) { if (mDebugInfo == null) { @@ -317,12 +305,19 @@ public final class PhoneTimeZoneSuggestion implements Parcelable { @Quality private int mQuality; @Nullable private List mDebugInfo; + /** + * Creates a builder with the specified {@code slotIndex}. + * + *

See {@link PhoneTimeZoneSuggestion} for more information about {@code slotIndex}. + */ public Builder(int slotIndex) { mSlotIndex = slotIndex; } /** * Returns the builder for call chaining. + * + *

See {@link PhoneTimeZoneSuggestion} for more information about {@code zoneId}. */ @NonNull public Builder setZoneId(@Nullable String zoneId) { @@ -330,21 +325,33 @@ public final class PhoneTimeZoneSuggestion implements Parcelable { return this; } - /** Returns the builder for call chaining. */ + /** + * Returns the builder for call chaining. + * + *

See {@link PhoneTimeZoneSuggestion} for more information about {@code matchType}. + */ @NonNull public Builder setMatchType(@MatchType int matchType) { mMatchType = matchType; return this; } - /** Returns the builder for call chaining. */ + /** + * Returns the builder for call chaining. + * + *

See {@link PhoneTimeZoneSuggestion} for more information about {@code quality}. + */ @NonNull public Builder setQuality(@Quality int quality) { mQuality = quality; return this; } - /** Returns the builder for call chaining. */ + /** + * Returns the builder for call chaining. + * + *

See {@link PhoneTimeZoneSuggestion} for more information about {@code debugInfo}. + */ @NonNull public Builder addDebugInfo(@NonNull String debugInfo) { if (mDebugInfo == null) {