1 /*
   2  * Copyright (c) 1996, 2014, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 /*
  27  * (C) Copyright Taligent, Inc. 1996 - All Rights Reserved
  28  * (C) Copyright IBM Corp. 1996 - All Rights Reserved
  29  *
  30  *   The original version of this source code and documentation is copyrighted
  31  * and owned by Taligent, Inc., a wholly-owned subsidiary of IBM. These
  32  * materials are provided under terms of a License Agreement between Taligent
  33  * and Sun. This technology is protected by multiple US and International
  34  * patents. This notice and attribution to Taligent may not be removed.
  35  *   Taligent is a registered trademark of Taligent, Inc.
  36  *
  37  */
  38 
  39 package java.util;
  40 
  41 import java.io.Serializable;
  42 import java.security.AccessController;
  43 import java.security.PrivilegedAction;
  44 import java.time.ZoneId;
  45 import sun.security.action.GetPropertyAction;
  46 import sun.util.calendar.ZoneInfo;
  47 import sun.util.calendar.ZoneInfoFile;
  48 import sun.util.locale.provider.TimeZoneNameUtility;
  49 
  50 /**
  51  * <code>TimeZone</code> represents a time zone offset, and also figures out daylight
  52  * savings.
  53  *
  54  * <p>
  55  * Typically, you get a <code>TimeZone</code> using <code>getDefault</code>
  56  * which creates a <code>TimeZone</code> based on the time zone where the program
  57  * is running. For example, for a program running in Japan, <code>getDefault</code>
  58  * creates a <code>TimeZone</code> object based on Japanese Standard Time.
  59  *
  60  * <p>
  61  * You can also get a <code>TimeZone</code> using <code>getTimeZone</code>
  62  * along with a time zone ID. For instance, the time zone ID for the
  63  * U.S. Pacific Time zone is "America/Los_Angeles". So, you can get a
  64  * U.S. Pacific Time <code>TimeZone</code> object with:
  65  * <blockquote><pre>
  66  * TimeZone tz = TimeZone.getTimeZone("America/Los_Angeles");
  67  * </pre></blockquote>
  68  * You can use the <code>getAvailableIDs</code> method to iterate through
  69  * all the supported time zone IDs. You can then choose a
  70  * supported ID to get a <code>TimeZone</code>.
  71  * If the time zone you want is not represented by one of the
  72  * supported IDs, then a custom time zone ID can be specified to
  73  * produce a TimeZone. The syntax of a custom time zone ID is:
  74  *
  75  * <blockquote><pre>
  76  * <a name="CustomID"><i>CustomID:</i></a>
  77  *         <code>GMT</code> <i>Sign</i> <i>Hours</i> <code>:</code> <i>Minutes</i>
  78  *         <code>GMT</code> <i>Sign</i> <i>Hours</i> <i>Minutes</i>
  79  *         <code>GMT</code> <i>Sign</i> <i>Hours</i>
  80  * <i>Sign:</i> one of
  81  *         <code>+ -</code>
  82  * <i>Hours:</i>
  83  *         <i>Digit</i>
  84  *         <i>Digit</i> <i>Digit</i>
  85  * <i>Minutes:</i>
  86  *         <i>Digit</i> <i>Digit</i>
  87  * <i>Digit:</i> one of
  88  *         <code>0 1 2 3 4 5 6 7 8 9</code>
  89  * </pre></blockquote>
  90  *
  91  * <i>Hours</i> must be between 0 to 23 and <i>Minutes</i> must be
  92  * between 00 to 59.  For example, "GMT+10" and "GMT+0010" mean ten
  93  * hours and ten minutes ahead of GMT, respectively.
  94  * <p>
  95  * The format is locale independent and digits must be taken from the
  96  * Basic Latin block of the Unicode standard. No daylight saving time
  97  * transition schedule can be specified with a custom time zone ID. If
  98  * the specified string doesn't match the syntax, <code>"GMT"</code>
  99  * is used.
 100  * <p>
 101  * When creating a <code>TimeZone</code>, the specified custom time
 102  * zone ID is normalized in the following syntax:
 103  * <blockquote><pre>
 104  * <a name="NormalizedCustomID"><i>NormalizedCustomID:</i></a>
 105  *         <code>GMT</code> <i>Sign</i> <i>TwoDigitHours</i> <code>:</code> <i>Minutes</i>
 106  * <i>Sign:</i> one of
 107  *         <code>+ -</code>
 108  * <i>TwoDigitHours:</i>
 109  *         <i>Digit</i> <i>Digit</i>
 110  * <i>Minutes:</i>
 111  *         <i>Digit</i> <i>Digit</i>
 112  * <i>Digit:</i> one of
 113  *         <code>0 1 2 3 4 5 6 7 8 9</code>
 114  * </pre></blockquote>
 115  * For example, TimeZone.getTimeZone("GMT-8").getID() returns "GMT-08:00".
 116  *
 117  * <h3>Three-letter time zone IDs</h3>
 118  *
 119  * For compatibility with JDK 1.1.x, some other three-letter time zone IDs
 120  * (such as "PST", "CTT", "AST") are also supported. However, <strong>their
 121  * use is deprecated</strong> because the same abbreviation is often used
 122  * for multiple time zones (for example, "CST" could be U.S. "Central Standard
 123  * Time" and "China Standard Time"), and the Java platform can then only
 124  * recognize one of them.
 125  *
 126  *
 127  * @see          Calendar
 128  * @see          GregorianCalendar
 129  * @see          SimpleTimeZone
 130  * @author       Mark Davis, David Goldsmith, Chen-Lieh Huang, Alan Liu
 131  * @since        1.1
 132  */
 133 abstract public class TimeZone implements Serializable, Cloneable {
 134     /**
 135      * Sole constructor.  (For invocation by subclass constructors, typically
 136      * implicit.)
 137      */
 138     public TimeZone() {
 139     }
 140 
 141     /**
 142      * A style specifier for <code>getDisplayName()</code> indicating
 143      * a short name, such as "PST."
 144      * @see #LONG
 145      * @since 1.2
 146      */
 147     public static final int SHORT = 0;
 148 
 149     /**
 150      * A style specifier for <code>getDisplayName()</code> indicating
 151      * a long name, such as "Pacific Standard Time."
 152      * @see #SHORT
 153      * @since 1.2
 154      */
 155     public static final int LONG  = 1;
 156 
 157     // Constants used internally; unit is milliseconds
 158     private static final int ONE_MINUTE = 60*1000;
 159     private static final int ONE_HOUR   = 60*ONE_MINUTE;
 160     private static final int ONE_DAY    = 24*ONE_HOUR;
 161 
 162     // Proclaim serialization compatibility with JDK 1.1
 163     static final long serialVersionUID = 3581463369166924961L;
 164 
 165     /**
 166      * Gets the time zone offset, for current date, modified in case of
 167      * daylight savings. This is the offset to add to UTC to get local time.
 168      * <p>
 169      * This method returns a historically correct offset if an
 170      * underlying <code>TimeZone</code> implementation subclass
 171      * supports historical Daylight Saving Time schedule and GMT
 172      * offset changes.
 173      *
 174      * @param era the era of the given date.
 175      * @param year the year in the given date.
 176      * @param month the month in the given date.
 177      * Month is 0-based. e.g., 0 for January.
 178      * @param day the day-in-month of the given date.
 179      * @param dayOfWeek the day-of-week of the given date.
 180      * @param milliseconds the milliseconds in day in <em>standard</em>
 181      * local time.
 182      *
 183      * @return the offset in milliseconds to add to GMT to get local time.
 184      *
 185      * @see Calendar#ZONE_OFFSET
 186      * @see Calendar#DST_OFFSET
 187      */
 188     public abstract int getOffset(int era, int year, int month, int day,
 189                                   int dayOfWeek, int milliseconds);
 190 
 191     /**
 192      * Returns the offset of this time zone from UTC at the specified
 193      * date. If Daylight Saving Time is in effect at the specified
 194      * date, the offset value is adjusted with the amount of daylight
 195      * saving.
 196      * <p>
 197      * This method returns a historically correct offset value if an
 198      * underlying TimeZone implementation subclass supports historical
 199      * Daylight Saving Time schedule and GMT offset changes.
 200      *
 201      * @param date the date represented in milliseconds since January 1, 1970 00:00:00 GMT
 202      * @return the amount of time in milliseconds to add to UTC to get local time.
 203      *
 204      * @see Calendar#ZONE_OFFSET
 205      * @see Calendar#DST_OFFSET
 206      * @since 1.4
 207      */
 208     public int getOffset(long date) {
 209         if (inDaylightTime(new Date(date))) {
 210             return getRawOffset() + getDSTSavings();
 211         }
 212         return getRawOffset();
 213     }
 214 
 215     /**
 216      * Gets the raw GMT offset and the amount of daylight saving of this
 217      * time zone at the given time.
 218      * @param date the milliseconds (since January 1, 1970,
 219      * 00:00:00.000 GMT) at which the time zone offset and daylight
 220      * saving amount are found
 221      * @param offsets an array of int where the raw GMT offset
 222      * (offset[0]) and daylight saving amount (offset[1]) are stored,
 223      * or null if those values are not needed. The method assumes that
 224      * the length of the given array is two or larger.
 225      * @return the total amount of the raw GMT offset and daylight
 226      * saving at the specified date.
 227      *
 228      * @see Calendar#ZONE_OFFSET
 229      * @see Calendar#DST_OFFSET
 230      */
 231     int getOffsets(long date, int[] offsets) {
 232         int rawoffset = getRawOffset();
 233         int dstoffset = 0;
 234         if (inDaylightTime(new Date(date))) {
 235             dstoffset = getDSTSavings();
 236         }
 237         if (offsets != null) {
 238             offsets[0] = rawoffset;
 239             offsets[1] = dstoffset;
 240         }
 241         return rawoffset + dstoffset;
 242     }
 243 
 244     /**
 245      * Sets the base time zone offset to GMT.
 246      * This is the offset to add to UTC to get local time.
 247      * <p>
 248      * If an underlying <code>TimeZone</code> implementation subclass
 249      * supports historical GMT offset changes, the specified GMT
 250      * offset is set as the latest GMT offset and the difference from
 251      * the known latest GMT offset value is used to adjust all
 252      * historical GMT offset values.
 253      *
 254      * @param offsetMillis the given base time zone offset to GMT.
 255      */
 256     abstract public void setRawOffset(int offsetMillis);
 257 
 258     /**
 259      * Returns the amount of time in milliseconds to add to UTC to get
 260      * standard time in this time zone. Because this value is not
 261      * affected by daylight saving time, it is called <I>raw
 262      * offset</I>.
 263      * <p>
 264      * If an underlying <code>TimeZone</code> implementation subclass
 265      * supports historical GMT offset changes, the method returns the
 266      * raw offset value of the current date. In Honolulu, for example,
 267      * its raw offset changed from GMT-10:30 to GMT-10:00 in 1947, and
 268      * this method always returns -36000000 milliseconds (i.e., -10
 269      * hours).
 270      *
 271      * @return the amount of raw offset time in milliseconds to add to UTC.
 272      * @see Calendar#ZONE_OFFSET
 273      */
 274     public abstract int getRawOffset();
 275 
 276     /**
 277      * Gets the ID of this time zone.
 278      * @return the ID of this time zone.
 279      */
 280     public String getID()
 281     {
 282         return ID;
 283     }
 284 
 285     /**
 286      * Sets the time zone ID. This does not change any other data in
 287      * the time zone object.
 288      * @param ID the new time zone ID.
 289      */
 290     public void setID(String ID)
 291     {
 292         if (ID == null) {
 293             throw new NullPointerException();
 294         }
 295         this.ID = ID;
 296         this.zoneId = null;   // invalidate cache
 297     }
 298 
 299     /**
 300      * Returns a long standard time name of this {@code TimeZone} suitable for
 301      * presentation to the user in the default locale.
 302      *
 303      * <p>This method is equivalent to:
 304      * <blockquote><pre>
 305      * getDisplayName(false, {@link #LONG},
 306      *                Locale.getDefault({@link Locale.Category#DISPLAY}))
 307      * </pre></blockquote>
 308      *
 309      * @return the human-readable name of this time zone in the default locale.
 310      * @since 1.2
 311      * @see #getDisplayName(boolean, int, Locale)
 312      * @see Locale#getDefault(Locale.Category)
 313      * @see Locale.Category
 314      */
 315     public final String getDisplayName() {
 316         return getDisplayName(false, LONG,
 317                               Locale.getDefault(Locale.Category.DISPLAY));
 318     }
 319 
 320     /**
 321      * Returns a long standard time name of this {@code TimeZone} suitable for
 322      * presentation to the user in the specified {@code locale}.
 323      *
 324      * <p>This method is equivalent to:
 325      * <blockquote><pre>
 326      * getDisplayName(false, {@link #LONG}, locale)
 327      * </pre></blockquote>
 328      *
 329      * @param locale the locale in which to supply the display name.
 330      * @return the human-readable name of this time zone in the given locale.
 331      * @exception NullPointerException if {@code locale} is {@code null}.
 332      * @since 1.2
 333      * @see #getDisplayName(boolean, int, Locale)
 334      */
 335     public final String getDisplayName(Locale locale) {
 336         return getDisplayName(false, LONG, locale);
 337     }
 338 
 339     /**
 340      * Returns a name in the specified {@code style} of this {@code TimeZone}
 341      * suitable for presentation to the user in the default locale. If the
 342      * specified {@code daylight} is {@code true}, a Daylight Saving Time name
 343      * is returned (even if this {@code TimeZone} doesn't observe Daylight Saving
 344      * Time). Otherwise, a Standard Time name is returned.
 345      *
 346      * <p>This method is equivalent to:
 347      * <blockquote><pre>
 348      * getDisplayName(daylight, style,
 349      *                Locale.getDefault({@link Locale.Category#DISPLAY}))
 350      * </pre></blockquote>
 351      *
 352      * @param daylight {@code true} specifying a Daylight Saving Time name, or
 353      *                 {@code false} specifying a Standard Time name
 354      * @param style either {@link #LONG} or {@link #SHORT}
 355      * @return the human-readable name of this time zone in the default locale.
 356      * @exception IllegalArgumentException if {@code style} is invalid.
 357      * @since 1.2
 358      * @see #getDisplayName(boolean, int, Locale)
 359      * @see Locale#getDefault(Locale.Category)
 360      * @see Locale.Category
 361      * @see java.text.DateFormatSymbols#getZoneStrings()
 362      */
 363     public final String getDisplayName(boolean daylight, int style) {
 364         return getDisplayName(daylight, style,
 365                               Locale.getDefault(Locale.Category.DISPLAY));
 366     }
 367 
 368     /**
 369      * Returns a name in the specified {@code style} of this {@code TimeZone}
 370      * suitable for presentation to the user in the specified {@code
 371      * locale}. If the specified {@code daylight} is {@code true}, a Daylight
 372      * Saving Time name is returned (even if this {@code TimeZone} doesn't
 373      * observe Daylight Saving Time). Otherwise, a Standard Time name is
 374      * returned.
 375      *
 376      * <p>When looking up a time zone name, the {@linkplain
 377      * ResourceBundle.Control#getCandidateLocales(String,Locale) default
 378      * <code>Locale</code> search path of <code>ResourceBundle</code>} derived
 379      * from the specified {@code locale} is used. (No {@linkplain
 380      * ResourceBundle.Control#getFallbackLocale(String,Locale) fallback
 381      * <code>Locale</code>} search is performed.) If a time zone name in any
 382      * {@code Locale} of the search path, including {@link Locale#ROOT}, is
 383      * found, the name is returned. Otherwise, a string in the
 384      * <a href="#NormalizedCustomID">normalized custom ID format</a> is returned.
 385      *
 386      * @param daylight {@code true} specifying a Daylight Saving Time name, or
 387      *                 {@code false} specifying a Standard Time name
 388      * @param style either {@link #LONG} or {@link #SHORT}
 389      * @param locale   the locale in which to supply the display name.
 390      * @return the human-readable name of this time zone in the given locale.
 391      * @exception IllegalArgumentException if {@code style} is invalid.
 392      * @exception NullPointerException if {@code locale} is {@code null}.
 393      * @since 1.2
 394      * @see java.text.DateFormatSymbols#getZoneStrings()
 395      */
 396     public String getDisplayName(boolean daylight, int style, Locale locale) {
 397         if (style != SHORT && style != LONG) {
 398             throw new IllegalArgumentException("Illegal style: " + style);
 399         }
 400         String id = getID();
 401         String name = TimeZoneNameUtility.retrieveDisplayName(id, daylight, style, locale);
 402         if (name != null) {
 403             return name;
 404         }
 405 
 406         if (id.startsWith("GMT") && id.length() > 3) {
 407             char sign = id.charAt(3);
 408             if (sign == '+' || sign == '-') {
 409                 return id;
 410             }
 411         }
 412         int offset = getRawOffset();
 413         if (daylight) {
 414             offset += getDSTSavings();
 415         }
 416         return ZoneInfoFile.toCustomID(offset);
 417     }
 418 
 419     private static String[] getDisplayNames(String id, Locale locale) {
 420         return TimeZoneNameUtility.retrieveDisplayNames(id, locale);
 421     }
 422 
 423     /**
 424      * Returns the amount of time to be added to local standard time
 425      * to get local wall clock time.
 426      *
 427      * <p>The default implementation returns 3600000 milliseconds
 428      * (i.e., one hour) if a call to {@link #useDaylightTime()}
 429      * returns {@code true}. Otherwise, 0 (zero) is returned.
 430      *
 431      * <p>If an underlying {@code TimeZone} implementation subclass
 432      * supports historical and future Daylight Saving Time schedule
 433      * changes, this method returns the amount of saving time of the
 434      * last known Daylight Saving Time rule that can be a future
 435      * prediction.
 436      *
 437      * <p>If the amount of saving time at any given time stamp is
 438      * required, construct a {@link Calendar} with this {@code
 439      * TimeZone} and the time stamp, and call {@link Calendar#get(int)
 440      * Calendar.get}{@code (}{@link Calendar#DST_OFFSET}{@code )}.
 441      *
 442      * @return the amount of saving time in milliseconds
 443      * @since 1.4
 444      * @see #inDaylightTime(Date)
 445      * @see #getOffset(long)
 446      * @see #getOffset(int,int,int,int,int,int)
 447      * @see Calendar#ZONE_OFFSET
 448      */
 449     public int getDSTSavings() {
 450         if (useDaylightTime()) {
 451             return 3600000;
 452         }
 453         return 0;
 454     }
 455 
 456     /**
 457      * Queries if this {@code TimeZone} uses Daylight Saving Time.
 458      *
 459      * <p>If an underlying {@code TimeZone} implementation subclass
 460      * supports historical and future Daylight Saving Time schedule
 461      * changes, this method refers to the last known Daylight Saving Time
 462      * rule that can be a future prediction and may not be the same as
 463      * the current rule. Consider calling {@link #observesDaylightTime()}
 464      * if the current rule should also be taken into account.
 465      *
 466      * @return {@code true} if this {@code TimeZone} uses Daylight Saving Time,
 467      *         {@code false}, otherwise.
 468      * @see #inDaylightTime(Date)
 469      * @see Calendar#DST_OFFSET
 470      */
 471     public abstract boolean useDaylightTime();
 472 
 473     /**
 474      * Returns {@code true} if this {@code TimeZone} is currently in
 475      * Daylight Saving Time, or if a transition from Standard Time to
 476      * Daylight Saving Time occurs at any future time.
 477      *
 478      * <p>The default implementation returns {@code true} if
 479      * {@code useDaylightTime()} or {@code inDaylightTime(new Date())}
 480      * returns {@code true}.
 481      *
 482      * @return {@code true} if this {@code TimeZone} is currently in
 483      * Daylight Saving Time, or if a transition from Standard Time to
 484      * Daylight Saving Time occurs at any future time; {@code false}
 485      * otherwise.
 486      * @since 1.7
 487      * @see #useDaylightTime()
 488      * @see #inDaylightTime(Date)
 489      * @see Calendar#DST_OFFSET
 490      */
 491     public boolean observesDaylightTime() {
 492         return useDaylightTime() || inDaylightTime(new Date());
 493     }
 494 
 495     /**
 496      * Queries if the given {@code date} is in Daylight Saving Time in
 497      * this time zone.
 498      *
 499      * @param date the given Date.
 500      * @return {@code true} if the given date is in Daylight Saving Time,
 501      *         {@code false}, otherwise.
 502      */
 503     abstract public boolean inDaylightTime(Date date);
 504 
 505     /**
 506      * Gets the <code>TimeZone</code> for the given ID.
 507      *
 508      * @param ID the ID for a <code>TimeZone</code>, either an abbreviation
 509      * such as "PST", a full name such as "America/Los_Angeles", or a custom
 510      * ID such as "GMT-8:00". Note that the support of abbreviations is
 511      * for JDK 1.1.x compatibility only and full names should be used.
 512      *
 513      * @return the specified <code>TimeZone</code>, or the GMT zone if the given ID
 514      * cannot be understood.
 515      */
 516     public static synchronized TimeZone getTimeZone(String ID) {
 517         return getTimeZone(ID, true);
 518     }
 519 
 520     /**
 521      * Gets the {@code TimeZone} for the given {@code zoneId}.
 522      *
 523      * @param zoneId a {@link ZoneId} from which the time zone ID is obtained
 524      * @return the specified {@code TimeZone}, or the GMT zone if the given ID
 525      *         cannot be understood.
 526      * @throws NullPointerException if {@code zoneId} is {@code null}
 527      * @since 1.8
 528      */
 529     public static TimeZone getTimeZone(ZoneId zoneId) {
 530         String tzid = zoneId.getId(); // throws an NPE if null
 531         char c = tzid.charAt(0);
 532         if (c == '+' || c == '-') {
 533             tzid = "GMT" + tzid;
 534         } else if (c == 'Z' && tzid.length() == 1) {
 535             tzid = "UTC";
 536         }
 537         return getTimeZone(tzid, true);
 538     }
 539 
 540     /**
 541      * Converts this {@code TimeZone} object to a {@code ZoneId}.
 542      *
 543      * @return a {@code ZoneId} representing the same time zone as this
 544      *         {@code TimeZone}
 545      * @since 1.8
 546      */
 547     public ZoneId toZoneId() {
 548         ZoneId zId = zoneId;
 549         if (zId == null) {
 550             zoneId = zId = toZoneId0();
 551         }
 552         return zId;
 553     }
 554 
 555     private ZoneId toZoneId0() {
 556         String id = getID();
 557         TimeZone defaultZone = defaultTimeZone;
 558         // are we not defaultTimeZone but our id is equal to default's?
 559         if (defaultZone != this &&
 560             defaultZone != null && id.equals(defaultZone.getID())) {
 561             // delegate to default TZ
 562             return defaultZone.toZoneId();
 563         }
 564         // derive it ourselves
 565         if (ZoneInfoFile.useOldMapping() && id.length() == 3) {
 566             if ("EST".equals(id))
 567                 return ZoneId.of("America/New_York");
 568             if ("MST".equals(id))
 569                 return ZoneId.of("America/Denver");
 570             if ("HST".equals(id))
 571                 return ZoneId.of("America/Honolulu");
 572         }
 573         return ZoneId.of(id, ZoneId.SHORT_IDS);
 574     }
 575 
 576     private static TimeZone getTimeZone(String ID, boolean fallback) {
 577         TimeZone tz = ZoneInfo.getTimeZone(ID);
 578         if (tz == null) {
 579             tz = parseCustomTimeZone(ID);
 580             if (tz == null && fallback) {
 581                 tz = new ZoneInfo(GMT_ID, 0);
 582             }
 583         }
 584         return tz;
 585     }
 586 
 587     /**
 588      * Gets the available IDs according to the given time zone offset in milliseconds.
 589      *
 590      * @param rawOffset the given time zone GMT offset in milliseconds.
 591      * @return an array of IDs, where the time zone for that ID has
 592      * the specified GMT offset. For example, "America/Phoenix" and "America/Denver"
 593      * both have GMT-07:00, but differ in daylight saving behavior.
 594      * @see #getRawOffset()
 595      */
 596     public static synchronized String[] getAvailableIDs(int rawOffset) {
 597         return ZoneInfo.getAvailableIDs(rawOffset);
 598     }
 599 
 600     /**
 601      * Gets all the available IDs supported.
 602      * @return an array of IDs.
 603      */
 604     public static synchronized String[] getAvailableIDs() {
 605         return ZoneInfo.getAvailableIDs();
 606     }
 607 
 608     /**
 609      * Gets the platform defined TimeZone ID.
 610      **/
 611     private static native String getSystemTimeZoneID(String javaHome);
 612 
 613     /**
 614      * Gets the custom time zone ID based on the GMT offset of the
 615      * platform. (e.g., "GMT+08:00")
 616      */
 617     private static native String getSystemGMTOffsetID();
 618 
 619     /**
 620      * Gets the default {@code TimeZone} of the Java virtual machine. If the
 621      * cached default {@code TimeZone} is available, its clone is returned.
 622      * Otherwise, the method takes the following steps to determine the default
 623      * time zone.
 624      *
 625      * <ul>
 626      * <li>Use the {@code user.timezone} property value as the default
 627      * time zone ID if it's available.</li>
 628      * <li>Detect the platform time zone ID. The source of the
 629      * platform time zone and ID mapping may vary with implementation.</li>
 630      * <li>Use {@code GMT} as the last resort if the given or detected
 631      * time zone ID is unknown.</li>
 632      * </ul>
 633      *
 634      * <p>The default {@code TimeZone} created from the ID is cached,
 635      * and its clone is returned. The {@code user.timezone} property
 636      * value is set to the ID upon return.
 637      *
 638      * @return the default {@code TimeZone}
 639      * @see #setDefault(TimeZone)
 640      */
 641     public static TimeZone getDefault() {
 642         return (TimeZone) getDefaultRef().clone();
 643     }
 644 
 645     /**
 646      * Returns the reference to the default TimeZone object. This
 647      * method doesn't create a clone.
 648      */
 649     static TimeZone getDefaultRef() {
 650         TimeZone defaultZone = defaultTimeZone;
 651         if (defaultZone == null) {
 652             // Need to initialize the default time zone.
 653             defaultZone = setDefaultZone();
 654             assert defaultZone != null;
 655         }
 656         // Don't clone here.
 657         return defaultZone;
 658     }
 659 
 660     private static synchronized TimeZone setDefaultZone() {
 661         TimeZone tz;
 662         // get the time zone ID from the system properties
 663         String zoneID = AccessController.doPrivileged(
 664                 new GetPropertyAction("user.timezone"));
 665 
 666         // if the time zone ID is not set (yet), perform the
 667         // platform to Java time zone ID mapping.
 668         if (zoneID == null || zoneID.isEmpty()) {
 669             String javaHome = AccessController.doPrivileged(
 670                     new GetPropertyAction("java.home"));
 671             try {
 672                 zoneID = getSystemTimeZoneID(javaHome);
 673                 if (zoneID == null) {
 674                     zoneID = GMT_ID;
 675                 }
 676             } catch (NullPointerException e) {
 677                 zoneID = GMT_ID;
 678             }
 679         }
 680 
 681         // Get the time zone for zoneID. But not fall back to
 682         // "GMT" here.
 683         tz = getTimeZone(zoneID, false);
 684 
 685         if (tz == null) {
 686             // If the given zone ID is unknown in Java, try to
 687             // get the GMT-offset-based time zone ID,
 688             // a.k.a. custom time zone ID (e.g., "GMT-08:00").
 689             String gmtOffsetID = getSystemGMTOffsetID();
 690             if (gmtOffsetID != null) {
 691                 zoneID = gmtOffsetID;
 692             }
 693             tz = getTimeZone(zoneID, true);
 694         }
 695         assert tz != null;
 696 
 697         final String id = zoneID;
 698         AccessController.doPrivileged(new PrivilegedAction<Void>() {
 699             @Override
 700                 public Void run() {
 701                     System.setProperty("user.timezone", id);
 702                     return null;
 703                 }
 704             });
 705 
 706         defaultTimeZone = tz;
 707         return tz;
 708     }
 709 
 710     /**
 711      * Sets the {@code TimeZone} that is returned by the {@code getDefault}
 712      * method. {@code zone} is cached. If {@code zone} is null, the cached
 713      * default {@code TimeZone} is cleared. This method doesn't change the value
 714      * of the {@code user.timezone} property.
 715      *
 716      * @param zone the new default {@code TimeZone}, or null
 717      * @throws SecurityException if the security manager's {@code checkPermission}
 718      *                           denies {@code PropertyPermission("user.timezone",
 719      *                           "write")}
 720      * @see #getDefault
 721      * @see PropertyPermission
 722      */
 723     public static void setDefault(TimeZone zone)
 724     {
 725         SecurityManager sm = System.getSecurityManager();
 726         if (sm != null) {
 727             sm.checkPermission(new PropertyPermission
 728                                ("user.timezone", "write"));
 729         }
 730         // defensive clone
 731         defaultTimeZone = (zone == null) ? null : (TimeZone) zone.clone();
 732     }
 733 
 734     /**
 735      * Returns true if this zone has the same rule and offset as another zone.
 736      * That is, if this zone differs only in ID, if at all.  Returns false
 737      * if the other zone is null.
 738      * @param other the <code>TimeZone</code> object to be compared with
 739      * @return true if the other zone is not null and is the same as this one,
 740      * with the possible exception of the ID
 741      * @since 1.2
 742      */
 743     public boolean hasSameRules(TimeZone other) {
 744         return other != null && getRawOffset() == other.getRawOffset() &&
 745             useDaylightTime() == other.useDaylightTime();
 746     }
 747 
 748     /**
 749      * Creates a copy of this <code>TimeZone</code>.
 750      *
 751      * @return a clone of this <code>TimeZone</code>
 752      */
 753     public Object clone()
 754     {
 755         try {
 756             return super.clone();
 757         } catch (CloneNotSupportedException e) {
 758             throw new InternalError(e);
 759         }
 760     }
 761 
 762     /**
 763      * The null constant as a TimeZone.
 764      */
 765     static final TimeZone NO_TIMEZONE = null;
 766 
 767     // =======================privates===============================
 768 
 769     /**
 770      * The string identifier of this <code>TimeZone</code>.  This is a
 771      * programmatic identifier used internally to look up <code>TimeZone</code>
 772      * objects from the system table and also to map them to their localized
 773      * display names.  <code>ID</code> values are unique in the system
 774      * table but may not be for dynamically created zones.
 775      * @serial
 776      */
 777     private String           ID;
 778 
 779     /**
 780      * Cached {@link ZoneId} for this TimeZone
 781      */
 782     private transient ZoneId zoneId;
 783 
 784     private static volatile TimeZone defaultTimeZone;
 785 
 786     static final String         GMT_ID        = "GMT";
 787     private static final int    GMT_ID_LENGTH = 3;
 788 
 789     // a static TimeZone we can reference if no AppContext is in place
 790     private static volatile TimeZone mainAppContextDefault;
 791 
 792     /**
 793      * Parses a custom time zone identifier and returns a corresponding zone.
 794      * This method doesn't support the RFC 822 time zone format. (e.g., +hhmm)
 795      *
 796      * @param id a string of the <a href="#CustomID">custom ID form</a>.
 797      * @return a newly created TimeZone with the given offset and
 798      * no daylight saving time, or null if the id cannot be parsed.
 799      */
 800     private static final TimeZone parseCustomTimeZone(String id) {
 801         int length;
 802 
 803         // Error if the length of id isn't long enough or id doesn't
 804         // start with "GMT".
 805         if ((length = id.length()) < (GMT_ID_LENGTH + 2) ||
 806             id.indexOf(GMT_ID) != 0) {
 807             return null;
 808         }
 809 
 810         ZoneInfo zi;
 811 
 812         // First, we try to find it in the cache with the given
 813         // id. Even the id is not normalized, the returned ZoneInfo
 814         // should have its normalized id.
 815         zi = ZoneInfoFile.getZoneInfo(id);
 816         if (zi != null) {
 817             return zi;
 818         }
 819 
 820         int index = GMT_ID_LENGTH;
 821         boolean negative = false;
 822         char c = id.charAt(index++);
 823         if (c == '-') {
 824             negative = true;
 825         } else if (c != '+') {
 826             return null;
 827         }
 828 
 829         int hours = 0;
 830         int num = 0;
 831         int countDelim = 0;
 832         int len = 0;
 833         while (index < length) {
 834             c = id.charAt(index++);
 835             if (c == ':') {
 836                 if (countDelim > 0) {
 837                     return null;
 838                 }
 839                 if (len > 2) {
 840                     return null;
 841                 }
 842                 hours = num;
 843                 countDelim++;
 844                 num = 0;
 845                 len = 0;
 846                 continue;
 847             }
 848             if (c < '0' || c > '9') {
 849                 return null;
 850             }
 851             num = num * 10 + (c - '0');
 852             len++;
 853         }
 854         if (index != length) {
 855             return null;
 856         }
 857         if (countDelim == 0) {
 858             if (len <= 2) {
 859                 hours = num;
 860                 num = 0;
 861             } else {
 862                 hours = num / 100;
 863                 num %= 100;
 864             }
 865         } else {
 866             if (len != 2) {
 867                 return null;
 868             }
 869         }
 870         if (hours > 23 || num > 59) {
 871             return null;
 872         }
 873         int gmtOffset =  (hours * 60 + num) * 60 * 1000;
 874 
 875         if (gmtOffset == 0) {
 876             zi = ZoneInfoFile.getZoneInfo(GMT_ID);
 877             if (negative) {
 878                 zi.setID("GMT-00:00");
 879             } else {
 880                 zi.setID("GMT+00:00");
 881             }
 882         } else {
 883             zi = ZoneInfoFile.getCustomTimeZone(id, negative ? -gmtOffset : gmtOffset);
 884         }
 885         return zi;
 886     }
 887 }