1 files changed, 43 insertions, 8 deletions
diff --git a/android_icu4j/src/main/java/android/icu/util/TimeZone.java b/android_icu4j/src/main/java/android/icu/util/TimeZone.java
index 9a887d95c..62376e684 100644
--- a/android_icu4j/src/main/java/android/icu/util/TimeZone.java
+++ b/android_icu4j/src/main/java/android/icu/util/TimeZone.java
@@ -236,7 +236,7 @@ abstract public class TimeZone implements Serializable, Cloneable, Freezable<Tim
 
     /**
      * Gets the time zone offset, for current date, modified in case of
-     * daylight savings. This is the offset to add *to* UTC to get local time.
+     * daylight savings. This is the offset to add <i>to</i> UTC to get local time.
      * @param era the era of the given date.
      * @param year the year in the given date.
      * @param month the month in the given date.
@@ -244,7 +244,7 @@ abstract public class TimeZone implements Serializable, Cloneable, Freezable<Tim
      * @param day the day-in-month of the given date.
      * @param dayOfWeek the day-of-week of the given date.
      * @param milliseconds the millis in day in <em>standard</em> local time.
-     * @return the offset to add *to* GMT to get local time.
+     * @return the offset to add <i>to</i> GMT to get local time.
      */
     abstract public int getOffset(int era, int year, int month, int day,
                                   int dayOfWeek, int milliseconds);
@@ -278,13 +278,13 @@ abstract public class TimeZone implements Serializable, Cloneable, Freezable<Tim
      *
      * @param date moment in time for which to return offsets, in
      * units of milliseconds from January 1, 1970 0:00 GMT, either GMT
-     * time or local wall time, depending on `local'.
-     * @param local if true, `date' is local wall time; otherwise it
+     * time or local wall time, depending on {@code local}.
+     * @param local if true, {@code date} is local wall time; otherwise it
      * is in GMT time.
      * @param offsets output parameter to receive the raw offset, that
      * is, the offset not including DST adjustments, in offsets[0],
      * and the DST offset, that is, the offset to be added to
-     * `rawOffset' to obtain the total offset between local and GMT
+     * {@code rawOffset} to obtain the total offset between local and GMT
      * time, in offsets[1]. If DST is not in effect, the DST offset is
      * zero; otherwise it is a positive value, typically one hour.
      */
@@ -323,15 +323,15 @@ abstract public class TimeZone implements Serializable, Cloneable, Freezable<Tim
 
     /**
      * Sets the base time zone offset to GMT.
-     * This is the offset to add *to* UTC to get local time.
+     * This is the offset to add <i>to</i> UTC to get local time.
      * @param offsetMillis the given base time zone offset to GMT.
      */
     abstract public void setRawOffset(int offsetMillis);
 
     /**
      * Gets unmodified offset, NOT modified in case of daylight savings.
-     * This is the offset to add *to* UTC to get local time.
-     * @return the unmodified offset to add *to* UTC to get local time.
+     * This is the offset to add <i>to</i> UTC to get local time.
+     * @return the unmodified offset to add <i>to</i> UTC to get local time.
      */
     abstract public int getRawOffset();
 
@@ -1077,6 +1077,41 @@ abstract public class TimeZone implements Serializable, Cloneable, Freezable<Tim
     }
 
     /**
+     * Returns the preferred time zone ID in the IANA database for the given time zone ID.
+     * There are two types of preferred IDs. The first type is the one defined in zone.tab file,
+     * such as "America/Los_Angeles". The second types is the one defined for zones not associated
+     * with a specific region, but not defined with "Link" syntax, such as "Etc/GMT+10".
+     *
+     * <p>Note: For most of system time zone IDs, this method returns an ID same as {@link TimeZone#getCanonicalID(String)}.
+     * {@link TimeZone#getCanonicalID(String)} is based on canonical time zone IDs defined in Unicode CLDR.
+     * These canonical time zone IDs in CLDR were based on very old version of the time zone database.
+     * In the IANA time zone database, some IDs were updated since then. This API returns a newer
+     * time zone ID. For example, CLDR defines "Asia/Calcutta" as the canonical time zone ID. This
+     * method returns "Asia/Kolkata" instead.
+     * <p> "Etc/Unknown" is a special time zone ID defined by CLDR. There are no corresponding zones
+     * in the IANA time zone database. when the input is "Etc/Unknown", this method returns "Etc/Unknown",
+     * but it really means no mappings available. Caller of this method should interpret "Etc/Unknown"
+     * as an error.
+     *
+     * @param id    The input time zone ID.
+     * @return  The preferred time zone ID in the IANA time zone database, or {@link TimeZone#UNKNOWN_ZONE_ID}
+     * if the input ID is not a system ID.
+     * @see #getCanonicalID(String)
+     * @hide draft / provisional / internal are hidden on Android
+     */
+    public static String getIanaID(String id) {
+        String ianaId = TimeZone.UNKNOWN_ZONE_ID;
+        if (id == null || id.length() == 0 || id.equals(TimeZone.UNKNOWN_ZONE)) {
+            return ianaId;
+        }
+        String tmpIanaId = ZoneMeta.getIanaID(id);
+        if (tmpIanaId != null) {
+            ianaId = tmpIanaId;
+        }
+        return ianaId;
+    }
+
+    /**
      * <strong>[icu]</strong> Returns the region code associated with the given
      * system time zone ID. The region code is either ISO 3166
      * 2-letter country code or UN M.49 3-digit area code.