Merge "API docs tidy up" am: 6aef6673df (8586776f) · Commits · e / os / android_frameworks_base

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

+14 −8

Original line number	Diff line number	Diff line
		@@ -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.
		*
		* <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 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<Long> mUtcTime;
		@Nullable
		private ArrayList<String> mDebugInfo;
		@NonNull private final TimestampedValue<Long> mUtcTime;
		@Nullable private ArrayList<String> mDebugInfo;

		public ManualTimeSuggestion(@NonNull TimestampedValue<Long> utcTime) {
		mUtcTime = Objects.requireNonNull(utcTime);

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

+14 −8

Original line number	Diff line number	Diff line
		@@ -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.
		*
		* <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 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<Long> mUtcTime;
		@Nullable
		private ArrayList<String> mDebugInfo;
		@NonNull private final TimestampedValue<Long> mUtcTime;
		@Nullable private ArrayList<String> mDebugInfo;

		public NetworkTimeSuggestion(@NonNull TimestampedValue<Long> utcTime) {
		mUtcTime = Objects.requireNonNull(utcTime);

core/java/android/app/timedetector/PhoneTimeSuggestion.java

+46 −21

Original line number	Diff line number	Diff line
		@@ -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.
		*
		* <p>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.
		* <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.
		* 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.
		*
		* <p>{@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.
		*
		* <p>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.
		*
		* <p>See {@link PhoneTimeSuggestion} for more information about {@code utcTime}.
		*/
		@Nullable
		public TimestampedValue<Long> 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.
		*
		* <p>See {@link PhoneTimeSuggestion} for more information about {@code debugInfo}.
		*/
		@NonNull
		public List<String> 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.
		*
		* <p>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.
		*
		* <p>See {@link PhoneTimeSuggestion} for more information about {@code debugInfo}.
		*/
		public void addDebugInfo(@NonNull List<String> debugInfo) {
		if (mDebugInfo == null) {
		@@ -181,12 +194,20 @@ public final class PhoneTimeSuggestion implements Parcelable {
		@Nullable private TimestampedValue<Long> mUtcTime;
		@Nullable private List<String> mDebugInfo;

		/** Creates a builder with the specified {@code slotIndex}. */
		/**
		* Creates a builder with the specified {@code slotIndex}.
		*
		* <p>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.
		*
		* <p>See {@link PhoneTimeSuggestion} for more information about {@code utcTime}.
		*/
		@NonNull
		public Builder setUtcTime(@Nullable TimestampedValue<Long> 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.
		*
		* <p>See {@link PhoneTimeSuggestion} for more information about {@code debugInfo}.
		*/
		@NonNull
		public Builder addDebugInfo(@NonNull String debugInfo) {
		if (mDebugInfo == null) {

core/java/android/app/timezonedetector/ManualTimeZoneSuggestion.java

+10 −8

Original line number	Diff line number	Diff line
		@@ -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.
		*
		* <p>{@code zoneId} contains the suggested time zone ID, e.g. "America/Los_Angeles".
		*
		* <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
		* 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<String> mDebugInfo;
		@NonNull private final String mZoneId;
		@Nullable private ArrayList<String> mDebugInfo;

		public ManualTimeZoneSuggestion(@NonNull String zoneId) {
		mZoneId = Objects.requireNonNull(zoneId);

core/java/android/app/timezonedetector/PhoneTimeZoneSuggestion.java

+61 −54

Original line number	Diff line number	Diff line
		@@ -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.
		*
		* <p>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.
		* <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 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.
		*
		* <p>{@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;
		* <p>{@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}.
		*
		* <p>{@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<String> mDebugInfo;
		@Nullable private final String mZoneId;
		@MatchType private final int mMatchType;
		@Quality private final int mQuality;
		@Nullable private List<String> 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.
		*
		* <p>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.
		*
		* <p>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.
		*
		* <p>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.
		*
		* <p>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.
		*
		* <p>See {@link PhoneTimeZoneSuggestion} for more information about {@code debugInfo}.
		*/
		@NonNull
		public List<String> 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.
		*
		* <p>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.
		*
		* <p>See {@link PhoneTimeZoneSuggestion} for more information about {@code debugInfo}.
		*/
		public void addDebugInfo(@NonNull List<String> debugInfo) {
		if (mDebugInfo == null) {
		@@ -317,12 +305,19 @@ public final class PhoneTimeZoneSuggestion implements Parcelable {
		@Quality private int mQuality;
		@Nullable private List<String> mDebugInfo;

		/**
		* Creates a builder with the specified {@code slotIndex}.
		*
		* <p>See {@link PhoneTimeZoneSuggestion} for more information about {@code slotIndex}.
		*/
		public Builder(int slotIndex) {
		mSlotIndex = slotIndex;
		}

		/**
		* Returns the builder for call chaining.
		*
		* <p>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.
		*
		* <p>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.
		*
		* <p>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.
		*
		* <p>See {@link PhoneTimeZoneSuggestion} for more information about {@code debugInfo}.
		*/
		@NonNull
		public Builder addDebugInfo(@NonNull String debugInfo) {
		if (mDebugInfo == null) {