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 public final class TimestampedValue<T> implements Parcelable {
39     private final long mReferenceTimeMillis;
40     @Nullable
41     private final T mValue;
42 
TimestampedValue(long referenceTimeMillis, @Nullable T value)43     public TimestampedValue(long referenceTimeMillis, @Nullable T value) {
44         mReferenceTimeMillis = referenceTimeMillis;
45         mValue = value;
46     }
47 
48     /** Returns the reference time value. See {@link TimestampedValue} for more information. */
getReferenceTimeMillis()49     public long getReferenceTimeMillis() {
50         return mReferenceTimeMillis;
51     }
52 
53     /**
54      * Returns the value associated with the timestamp. See {@link TimestampedValue} for more
55      * information.
56      */
57     @Nullable
getValue()58     public T getValue() {
59         return mValue;
60     }
61 
62     @Override
equals(Object o)63     public boolean equals(Object o) {
64         if (this == o) {
65             return true;
66         }
67         if (o == null || getClass() != o.getClass()) {
68             return false;
69         }
70         TimestampedValue<?> that = (TimestampedValue<?>) o;
71         return mReferenceTimeMillis == that.mReferenceTimeMillis
72                 && Objects.equals(mValue, that.mValue);
73     }
74 
75     @Override
hashCode()76     public int hashCode() {
77         return Objects.hash(mReferenceTimeMillis, mValue);
78     }
79 
80     @Override
toString()81     public String toString() {
82         return "TimestampedValue{"
83                 + "mReferenceTimeMillis=" + mReferenceTimeMillis
84                 + ", mValue=" + mValue
85                 + '}';
86     }
87 
88     /**
89      * Returns the difference in milliseconds between two instance's reference times.
90      */
referenceTimeDifference( @onNull TimestampedValue<?> one, @NonNull TimestampedValue<?> two)91     public static long referenceTimeDifference(
92             @NonNull TimestampedValue<?> one, @NonNull TimestampedValue<?> two) {
93         return one.mReferenceTimeMillis - two.mReferenceTimeMillis;
94     }
95 
96     /** @hide */
97     public static final @NonNull Parcelable.Creator<TimestampedValue<?>> CREATOR =
98             new Parcelable.ClassLoaderCreator<TimestampedValue<?>>() {
99 
100                 @Override
101                 public TimestampedValue<?> createFromParcel(@NonNull Parcel source) {
102                     return createFromParcel(source, null);
103                 }
104 
105                 @Override
106                 public TimestampedValue<?> createFromParcel(
107                         @NonNull Parcel source, @Nullable ClassLoader classLoader) {
108                     long referenceTimeMillis = source.readLong();
109                     Object value = source.readValue(classLoader);
110                     return new TimestampedValue<>(referenceTimeMillis, value);
111                 }
112 
113                 @Override
114                 public TimestampedValue[] newArray(int size) {
115                     return new TimestampedValue[size];
116                 }
117             };
118 
119     @Override
describeContents()120     public int describeContents() {
121         return 0;
122     }
123 
124     @Override
writeToParcel(@onNull Parcel dest, int flags)125     public void writeToParcel(@NonNull Parcel dest, int flags) {
126         dest.writeLong(mReferenceTimeMillis);
127         dest.writeValue(mValue);
128     }
129 }
130