Add new module-lib APIs for MTS testing

Several android.timezone classes have already been exposed for the
telephony module work, so these tests provide coverage for those.
Additional APIs have been exposed for MTS testing, i.e. to provide
greater confidence that the tzdata module data is correct / is
being read correctly.

Also, small changes to existing code to make them consistent with new
classes. Small docs improvements.

Bug: 147884233
Test: see system/timezone change
Change-Id: I047b29f17a41993f859947a6d6c3685896fe4cb6

1 files changed, 154 insertions, 0 deletions

diff --git a/core/java/android/timezone/TzDataSetVersion.java b/core/java/android/timezone/TzDataSetVersion.java
new file mode 100644
index 000000000000..aba7c4c15903
--- /dev/null
+++ b/core/java/android/timezone/TzDataSetVersion.java
@@ -0,0 +1,154 @@
+/*
+ * Copyright (C) 2020 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package android.timezone;
+
+import android.annotation.NonNull;
+import android.annotation.SystemApi;
+
+import com.android.internal.annotations.VisibleForTesting;
+
+import java.io.IOException;
+import java.util.Objects;
+
+/**
+ * Version information associated with the set of time zone data on a device.
+ *
+ * <p>Time Zone Data Sets have a major ({@link #getFormatMajorVersion()}) and minor
+ * ({@link #currentFormatMinorVersion()}) version number:
+ * <ul>
+ *   <li>Major version numbers are mutually incompatible. e.g. v2 is not compatible with a v1 or a
+ *   v3 device.</li>
+ *   <li>Minor version numbers are backwards compatible. e.g. a v2.2 data set will work
+ *   on a v2.1 device but not a v2.3 device. The minor version is reset to 1 when the major version
+ *   is incremented.</li>
+ * </ul>
+ *
+ * <p>Data sets contain time zone rules and other data associated wtih a tzdb release
+ * ({@link #getRulesVersion()}) and an additional Android-specific revision number
+ * ({@link #getRevision()}).
+ *
+ * <p>See platform/system/timezone/README.android for more information.
+ * @hide
+ */
+@VisibleForTesting
+@SystemApi(client = SystemApi.Client.MODULE_LIBRARIES)
+public final class TzDataSetVersion {
+
+    /**
+     * Returns the major tz data format version supported by this device.
+     */
+    public static int currentFormatMajorVersion() {
+        return libcore.timezone.TzDataSetVersion.currentFormatMajorVersion();
+    }
+
+    /**
+     * Returns the minor tz data format version supported by this device.
+     */
+    public static int currentFormatMinorVersion() {
+        return libcore.timezone.TzDataSetVersion.currentFormatMinorVersion();
+    }
+
+    /**
+     * Returns true if the version information provided would be compatible with this device, i.e.
+     * with the current system image, and set of active modules.
+     */
+    public static boolean isCompatibleWithThisDevice(TzDataSetVersion tzDataSetVersion) {
+        return libcore.timezone.TzDataSetVersion.isCompatibleWithThisDevice(
+                tzDataSetVersion.mDelegate);
+    }
+
+    /**
+     * Reads the current Android time zone data set version file.
+     */
+    @NonNull
+    public static TzDataSetVersion read() throws IOException, TzDataSetException {
+        try {
+            return new TzDataSetVersion(
+                    libcore.timezone.TzDataSetVersion.readTimeZoneModuleVersion());
+        } catch (libcore.timezone.TzDataSetVersion.TzDataSetException e) {
+            throw new TzDataSetException(e.getMessage(), e);
+        }
+    }
+
+    /**
+     * A checked exception used in connection with time zone data sets.
+     * @hide
+     */
+    @SystemApi(client = SystemApi.Client.MODULE_LIBRARIES)
+    public static class TzDataSetException extends Exception {
+
+        /** Creates an instance with a message. */
+        public TzDataSetException(String message) {
+            super(message);
+        }
+
+        /** Creates an instance with a message and a cause. */
+        public TzDataSetException(String message, Throwable cause) {
+            super(message, cause);
+        }
+    }
+
+    @NonNull
+    private final libcore.timezone.TzDataSetVersion mDelegate;
+
+    private TzDataSetVersion(@NonNull libcore.timezone.TzDataSetVersion delegate) {
+        mDelegate = Objects.requireNonNull(delegate);
+    }
+
+    /** Returns the major version number. See {@link TzDataSetVersion}. */
+    public int getFormatMajorVersion() {
+        return mDelegate.formatMajorVersion;
+    }
+
+    /** Returns the minor version number. See {@link TzDataSetVersion}. */
+    public int getFormatMinorVersion() {
+        return mDelegate.formatMinorVersion;
+    }
+
+    /** Returns the tzdb version string. See {@link TzDataSetVersion}. */
+    @NonNull
+    public String getRulesVersion() {
+        return mDelegate.rulesVersion;
+    }
+
+    /** Returns the Android revision. See {@link TzDataSetVersion}. */
+    public int getRevision() {
+        return mDelegate.revision;
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) {
+            return true;
+        }
+        if (o == null || getClass() != o.getClass()) {
+            return false;
+        }
+        TzDataSetVersion that = (TzDataSetVersion) o;
+        return mDelegate.equals(that.mDelegate);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(mDelegate);
+    }
+
+    @Override
+    public String toString() {
+        return mDelegate.toString();
+    }
+}