1 /*
2  * Copyright (C) 2020 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.timezone;
18 
19 import android.annotation.NonNull;
20 
21 import com.android.internal.annotations.VisibleForTesting;
22 
23 import java.io.IOException;
24 import java.util.Objects;
25 
26 /**
27  * Version information associated with the set of time zone data on a device.
28  *
29  * <p>Time Zone Data Sets have a major ({@link #getFormatMajorVersion()}) and minor
30  * ({@link #currentFormatMinorVersion()}) version number:
31  * <ul>
32  *   <li>Major version numbers are mutually incompatible. e.g. v2 is not compatible with a v1 or a
33  *   v3 device.</li>
34  *   <li>Minor version numbers are backwards compatible. e.g. a v2.2 data set will work
35  *   on a v2.1 device but not a v2.3 device. The minor version is reset to 1 when the major version
36  *   is incremented.</li>
37  * </ul>
38  *
39  * <p>Data sets contain time zone rules and other data associated wtih a tzdb release
40  * ({@link #getRulesVersion()}) and an additional Android-specific revision number
41  * ({@link #getRevision()}).
42  *
43  * <p>See platform/system/timezone/README.android for more information.
44  * @hide
45  */
46 @VisibleForTesting
47 public final class TzDataSetVersion {
48 
49     /**
50      * Returns the major tz data format version supported by this device.
51      */
currentFormatMajorVersion()52     public static int currentFormatMajorVersion() {
53         return libcore.timezone.TzDataSetVersion.currentFormatMajorVersion();
54     }
55 
56     /**
57      * Returns the minor tz data format version supported by this device.
58      */
currentFormatMinorVersion()59     public static int currentFormatMinorVersion() {
60         return libcore.timezone.TzDataSetVersion.currentFormatMinorVersion();
61     }
62 
63     /**
64      * Returns true if the version information provided would be compatible with this device, i.e.
65      * with the current system image, and set of active modules.
66      */
isCompatibleWithThisDevice(TzDataSetVersion tzDataSetVersion)67     public static boolean isCompatibleWithThisDevice(TzDataSetVersion tzDataSetVersion) {
68         return libcore.timezone.TzDataSetVersion.isCompatibleWithThisDevice(
69                 tzDataSetVersion.mDelegate);
70     }
71 
72     /**
73      * Reads the current Android time zone data set version file.
74      */
75     @NonNull
read()76     public static TzDataSetVersion read() throws IOException, TzDataSetException {
77         try {
78             return new TzDataSetVersion(
79                     libcore.timezone.TzDataSetVersion.readTimeZoneModuleVersion());
80         } catch (libcore.timezone.TzDataSetVersion.TzDataSetException e) {
81             throw new TzDataSetException(e.getMessage(), e);
82         }
83     }
84 
85     /**
86      * A checked exception used in connection with time zone data sets.
87      * @hide
88      */
89     public static final class TzDataSetException extends Exception {
90 
91         /** Creates an instance with a message. */
TzDataSetException(String message)92         public TzDataSetException(String message) {
93             super(message);
94         }
95 
96         /** Creates an instance with a message and a cause. */
TzDataSetException(String message, Throwable cause)97         public TzDataSetException(String message, Throwable cause) {
98             super(message, cause);
99         }
100     }
101 
102     @NonNull
103     private final libcore.timezone.TzDataSetVersion mDelegate;
104 
TzDataSetVersion(@onNull libcore.timezone.TzDataSetVersion delegate)105     private TzDataSetVersion(@NonNull libcore.timezone.TzDataSetVersion delegate) {
106         mDelegate = Objects.requireNonNull(delegate);
107     }
108 
109     /** Returns the major version number. See {@link TzDataSetVersion}. */
getFormatMajorVersion()110     public int getFormatMajorVersion() {
111         return mDelegate.getFormatMajorVersion();
112     }
113 
114     /** Returns the minor version number. See {@link TzDataSetVersion}. */
getFormatMinorVersion()115     public int getFormatMinorVersion() {
116         return mDelegate.getFormatMinorVersion();
117     }
118 
119     /** Returns the tzdb version string. See {@link TzDataSetVersion}. */
120     @NonNull
getRulesVersion()121     public String getRulesVersion() {
122         return mDelegate.getRulesVersion();
123     }
124 
125     /** Returns the Android revision. See {@link TzDataSetVersion}. */
getRevision()126     public int getRevision() {
127         return mDelegate.getRevision();
128     }
129 
130     @Override
equals(Object o)131     public boolean equals(Object o) {
132         if (this == o) {
133             return true;
134         }
135         if (o == null || getClass() != o.getClass()) {
136             return false;
137         }
138         TzDataSetVersion that = (TzDataSetVersion) o;
139         return mDelegate.equals(that.mDelegate);
140     }
141 
142     @Override
hashCode()143     public int hashCode() {
144         return Objects.hash(mDelegate);
145     }
146 
147     @Override
toString()148     public String toString() {
149         return mDelegate.toString();
150     }
151 }
152