1 /*
2  * Copyright (C) 2018 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package android.os;
18 
19 import android.annotation.NonNull;
20 import android.annotation.Nullable;
21 
22 import java.util.Objects;
23 
24 /**
25  * A value with an associated reference time. The reference time will typically be provided by the
26  * elapsed realtime clock. The elapsed realtime clock can be obtained using methods like
27  * {@link SystemClock#elapsedRealtime()} or {@link SystemClock#elapsedRealtimeClock()}.
28  * If a suitable clock is used the reference time can be used to identify the age of a value or
29  * ordering between values.
30  *
31  * <p>This class implements {@link Parcelable} for convenience but instances will only actually be
32  * parcelable if the value type held is {@code null}, {@link Parcelable}, or one of the other types
33  * supported by {@link Parcel#writeValue(Object)} / {@link Parcel#readValue(ClassLoader)}.
34  *
35  * @param <T> the type of the value with an associated timestamp
36  * @hide
37  */
38 @android.ravenwood.annotation.RavenwoodKeepWholeClass
39 public final class TimestampedValue<T> implements Parcelable {
40     private final long mReferenceTimeMillis;
41     @Nullable
42     private final T mValue;
43 
TimestampedValue(long referenceTimeMillis, @Nullable T value)44     public TimestampedValue(long referenceTimeMillis, @Nullable T value) {
45         mReferenceTimeMillis = referenceTimeMillis;
46         mValue = value;
47     }
48 
49     /** Returns the reference time value. See {@link TimestampedValue} for more information. */
getReferenceTimeMillis()50     public long getReferenceTimeMillis() {
51         return mReferenceTimeMillis;
52     }
53 
54     /**
55      * Returns the value associated with the timestamp. See {@link TimestampedValue} for more
56      * information.
57      */
58     @Nullable
getValue()59     public T getValue() {
60         return mValue;
61     }
62 
63     @Override
equals(@ullable Object o)64     public boolean equals(@Nullable Object o) {
65         if (this == o) {
66             return true;
67         }
68         if (o == null || getClass() != o.getClass()) {
69             return false;
70         }
71         TimestampedValue<?> that = (TimestampedValue<?>) o;
72         return mReferenceTimeMillis == that.mReferenceTimeMillis
73                 && Objects.equals(mValue, that.mValue);
74     }
75 
76     @Override
hashCode()77     public int hashCode() {
78         return Objects.hash(mReferenceTimeMillis, mValue);
79     }
80 
81     @Override
toString()82     public String toString() {
83         return "TimestampedValue{"
84                 + "mReferenceTimeMillis=" + mReferenceTimeMillis
85                 + ", mValue=" + mValue
86                 + '}';
87     }
88 
89     /**
90      * Returns the difference in milliseconds between two instance's reference times.
91      */
referenceTimeDifference( @onNull TimestampedValue<?> one, @NonNull TimestampedValue<?> two)92     public static long referenceTimeDifference(
93             @NonNull TimestampedValue<?> one, @NonNull TimestampedValue<?> two) {
94         return one.mReferenceTimeMillis - two.mReferenceTimeMillis;
95     }
96 
97     /** @hide */
98     public static final @NonNull Parcelable.Creator<TimestampedValue<?>> CREATOR =
99             new Parcelable.ClassLoaderCreator<TimestampedValue<?>>() {
100 
101                 @Override
102                 public TimestampedValue<?> createFromParcel(@NonNull Parcel source) {
103                     return createFromParcel(source, null);
104                 }
105 
106                 @Override
107                 public TimestampedValue<?> createFromParcel(
108                         @NonNull Parcel source, @Nullable ClassLoader classLoader) {
109                     long referenceTimeMillis = source.readLong();
110                     Object value = source.readValue(classLoader);
111                     return new TimestampedValue<>(referenceTimeMillis, value);
112                 }
113 
114                 @Override
115                 public TimestampedValue[] newArray(int size) {
116                     return new TimestampedValue[size];
117                 }
118             };
119 
120     @Override
describeContents()121     public int describeContents() {
122         return 0;
123     }
124 
125     @Override
writeToParcel(@onNull Parcel dest, int flags)126     public void writeToParcel(@NonNull Parcel dest, int flags) {
127         dest.writeLong(mReferenceTimeMillis);
128         dest.writeValue(mValue);
129     }
130 }
131