Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge "API docs tidy up" am: 6aef6673df

Browse Source 
Change-Id: I0be18d5713fa9ad17a53cfbf2ba445a181bc4a0c
This commit is contained in:
Automerger Merge Worker
2020-02-03 18:00:44 +00:00
parent 2f0862964d 6aef6673df
commit 8586776fbf
5 changed files with 145 additions and 99 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
core/java/android/app/timedetector/ManualTimeSuggestion.java
View File

@@ -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);

22
core/java/android/app/timedetector/NetworkTimeSuggestion.java
View File

@@ -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);

67
core/java/android/app/timedetector/PhoneTimeSuggestion.java
View File

@@ -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) {

18
core/java/android/app/timezonedetector/ManualTimeZoneSuggestion.java
View File

@@ -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);

115
core/java/android/app/timezonedetector/PhoneTimeZoneSuggestion.java
View File

@@ -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) {