46 import sun.util.calendar.ZoneInfo; |
46 import sun.util.calendar.ZoneInfo; |
47 import sun.util.calendar.ZoneInfoFile; |
47 import sun.util.calendar.ZoneInfoFile; |
48 import sun.util.locale.provider.TimeZoneNameUtility; |
48 import sun.util.locale.provider.TimeZoneNameUtility; |
49 |
49 |
50 /** |
50 /** |
51 * <code>TimeZone</code> represents a time zone offset, and also figures out daylight |
51 * {@code TimeZone} represents a time zone offset, and also figures out daylight |
52 * savings. |
52 * savings. |
53 * |
53 * |
54 * <p> |
54 * <p> |
55 * Typically, you get a <code>TimeZone</code> using <code>getDefault</code> |
55 * Typically, you get a {@code TimeZone} using {@code getDefault} |
56 * which creates a <code>TimeZone</code> based on the time zone where the program |
56 * which creates a {@code TimeZone} based on the time zone where the program |
57 * is running. For example, for a program running in Japan, <code>getDefault</code> |
57 * is running. For example, for a program running in Japan, {@code getDefault} |
58 * creates a <code>TimeZone</code> object based on Japanese Standard Time. |
58 * creates a {@code TimeZone} object based on Japanese Standard Time. |
59 * |
59 * |
60 * <p> |
60 * <p> |
61 * You can also get a <code>TimeZone</code> using <code>getTimeZone</code> |
61 * You can also get a {@code TimeZone} using {@code getTimeZone} |
62 * along with a time zone ID. For instance, the time zone ID for the |
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 |
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: |
64 * U.S. Pacific Time {@code TimeZone} object with: |
65 * <blockquote><pre> |
65 * <blockquote><pre> |
66 * TimeZone tz = TimeZone.getTimeZone("America/Los_Angeles"); |
66 * TimeZone tz = TimeZone.getTimeZone("America/Los_Angeles"); |
67 * </pre></blockquote> |
67 * </pre></blockquote> |
68 * You can use the <code>getAvailableIDs</code> method to iterate through |
68 * You can use the {@code getAvailableIDs} method to iterate through |
69 * all the supported time zone IDs. You can then choose a |
69 * all the supported time zone IDs. You can then choose a |
70 * supported ID to get a <code>TimeZone</code>. |
70 * supported ID to get a {@code TimeZone}. |
71 * If the time zone you want is not represented by one of the |
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 |
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: |
73 * produce a TimeZone. The syntax of a custom time zone ID is: |
74 * |
74 * |
75 * <blockquote><pre> |
75 * <blockquote><pre> |
76 * <a id="CustomID"><i>CustomID:</i></a> |
76 * <a id="CustomID"><i>CustomID:</i></a> |
77 * <code>GMT</code> <i>Sign</i> <i>Hours</i> <code>:</code> <i>Minutes</i> |
77 * {@code GMT} <i>Sign</i> <i>Hours</i> {@code :} <i>Minutes</i> |
78 * <code>GMT</code> <i>Sign</i> <i>Hours</i> <i>Minutes</i> |
78 * {@code GMT} <i>Sign</i> <i>Hours</i> <i>Minutes</i> |
79 * <code>GMT</code> <i>Sign</i> <i>Hours</i> |
79 * {@code GMT} <i>Sign</i> <i>Hours</i> |
80 * <i>Sign:</i> one of |
80 * <i>Sign:</i> one of |
81 * <code>+ -</code> |
81 * {@code + -} |
82 * <i>Hours:</i> |
82 * <i>Hours:</i> |
83 * <i>Digit</i> |
83 * <i>Digit</i> |
84 * <i>Digit</i> <i>Digit</i> |
84 * <i>Digit</i> <i>Digit</i> |
85 * <i>Minutes:</i> |
85 * <i>Minutes:</i> |
86 * <i>Digit</i> <i>Digit</i> |
86 * <i>Digit</i> <i>Digit</i> |
87 * <i>Digit:</i> one of |
87 * <i>Digit:</i> one of |
88 * <code>0 1 2 3 4 5 6 7 8 9</code> |
88 * {@code 0 1 2 3 4 5 6 7 8 9} |
89 * </pre></blockquote> |
89 * </pre></blockquote> |
90 * |
90 * |
91 * <i>Hours</i> must be between 0 to 23 and <i>Minutes</i> must be |
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 |
92 * between 00 to 59. For example, "GMT+10" and "GMT+0010" mean ten |
93 * hours and ten minutes ahead of GMT, respectively. |
93 * hours and ten minutes ahead of GMT, respectively. |
94 * <p> |
94 * <p> |
95 * The format is locale independent and digits must be taken from the |
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 |
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 |
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> |
98 * the specified string doesn't match the syntax, {@code "GMT"} |
99 * is used. |
99 * is used. |
100 * <p> |
100 * <p> |
101 * When creating a <code>TimeZone</code>, the specified custom time |
101 * When creating a {@code TimeZone}, the specified custom time |
102 * zone ID is normalized in the following syntax: |
102 * zone ID is normalized in the following syntax: |
103 * <blockquote><pre> |
103 * <blockquote><pre> |
104 * <a id="NormalizedCustomID"><i>NormalizedCustomID:</i></a> |
104 * <a id="NormalizedCustomID"><i>NormalizedCustomID:</i></a> |
105 * <code>GMT</code> <i>Sign</i> <i>TwoDigitHours</i> <code>:</code> <i>Minutes</i> |
105 * {@code GMT} <i>Sign</i> <i>TwoDigitHours</i> {@code :} <i>Minutes</i> |
106 * <i>Sign:</i> one of |
106 * <i>Sign:</i> one of |
107 * <code>+ -</code> |
107 * {@code + -} |
108 * <i>TwoDigitHours:</i> |
108 * <i>TwoDigitHours:</i> |
109 * <i>Digit</i> <i>Digit</i> |
109 * <i>Digit</i> <i>Digit</i> |
110 * <i>Minutes:</i> |
110 * <i>Minutes:</i> |
111 * <i>Digit</i> <i>Digit</i> |
111 * <i>Digit</i> <i>Digit</i> |
112 * <i>Digit:</i> one of |
112 * <i>Digit:</i> one of |
113 * <code>0 1 2 3 4 5 6 7 8 9</code> |
113 * {@code 0 1 2 3 4 5 6 7 8 9} |
114 * </pre></blockquote> |
114 * </pre></blockquote> |
115 * For example, TimeZone.getTimeZone("GMT-8").getID() returns "GMT-08:00". |
115 * For example, TimeZone.getTimeZone("GMT-8").getID() returns "GMT-08:00". |
116 * |
116 * |
117 * <h2>Three-letter time zone IDs</h2> |
117 * <h2>Three-letter time zone IDs</h2> |
118 * |
118 * |
260 * Returns the amount of time in milliseconds to add to UTC to get |
260 * Returns the amount of time in milliseconds to add to UTC to get |
261 * standard time in this time zone. Because this value is not |
261 * standard time in this time zone. Because this value is not |
262 * affected by daylight saving time, it is called <I>raw |
262 * affected by daylight saving time, it is called <I>raw |
263 * offset</I>. |
263 * offset</I>. |
264 * <p> |
264 * <p> |
265 * If an underlying <code>TimeZone</code> implementation subclass |
265 * If an underlying {@code TimeZone} implementation subclass |
266 * supports historical GMT offset changes, the method returns the |
266 * supports historical GMT offset changes, the method returns the |
267 * raw offset value of the current date. In Honolulu, for example, |
267 * raw offset value of the current date. In Honolulu, for example, |
268 * its raw offset changed from GMT-10:30 to GMT-10:00 in 1947, and |
268 * its raw offset changed from GMT-10:30 to GMT-10:00 in 1947, and |
269 * this method always returns -36000000 milliseconds (i.e., -10 |
269 * this method always returns -36000000 milliseconds (i.e., -10 |
270 * hours). |
270 * hours). |
374 * observe Daylight Saving Time). Otherwise, a Standard Time name is |
374 * observe Daylight Saving Time). Otherwise, a Standard Time name is |
375 * returned. |
375 * returned. |
376 * |
376 * |
377 * <p>When looking up a time zone name, the {@linkplain |
377 * <p>When looking up a time zone name, the {@linkplain |
378 * ResourceBundle.Control#getCandidateLocales(String,Locale) default |
378 * ResourceBundle.Control#getCandidateLocales(String,Locale) default |
379 * <code>Locale</code> search path of <code>ResourceBundle</code>} derived |
379 * {@code Locale} search path of {@code ResourceBundle}} derived |
380 * from the specified {@code locale} is used. (No {@linkplain |
380 * from the specified {@code locale} is used. (No {@linkplain |
381 * ResourceBundle.Control#getFallbackLocale(String,Locale) fallback |
381 * ResourceBundle.Control#getFallbackLocale(String,Locale) fallback |
382 * <code>Locale</code>} search is performed.) If a time zone name in any |
382 * {@code Locale}} search is performed.) If a time zone name in any |
383 * {@code Locale} of the search path, including {@link Locale#ROOT}, is |
383 * {@code Locale} of the search path, including {@link Locale#ROOT}, is |
384 * found, the name is returned. Otherwise, a string in the |
384 * found, the name is returned. Otherwise, a string in the |
385 * <a href="#NormalizedCustomID">normalized custom ID format</a> is returned. |
385 * <a href="#NormalizedCustomID">normalized custom ID format</a> is returned. |
386 * |
386 * |
387 * @param daylight {@code true} specifying a Daylight Saving Time name, or |
387 * @param daylight {@code true} specifying a Daylight Saving Time name, or |
502 * {@code false}, otherwise. |
502 * {@code false}, otherwise. |
503 */ |
503 */ |
504 public abstract boolean inDaylightTime(Date date); |
504 public abstract boolean inDaylightTime(Date date); |
505 |
505 |
506 /** |
506 /** |
507 * Gets the <code>TimeZone</code> for the given ID. |
507 * Gets the {@code TimeZone} for the given ID. |
508 * |
508 * |
509 * @param ID the ID for a <code>TimeZone</code>, either an abbreviation |
509 * @param ID the ID for a {@code TimeZone}, either an abbreviation |
510 * such as "PST", a full name such as "America/Los_Angeles", or a custom |
510 * such as "PST", a full name such as "America/Los_Angeles", or a custom |
511 * ID such as "GMT-8:00". Note that the support of abbreviations is |
511 * ID such as "GMT-8:00". Note that the support of abbreviations is |
512 * for JDK 1.1.x compatibility only and full names should be used. |
512 * for JDK 1.1.x compatibility only and full names should be used. |
513 * |
513 * |
514 * @return the specified <code>TimeZone</code>, or the GMT zone if the given ID |
514 * @return the specified {@code TimeZone}, or the GMT zone if the given ID |
515 * cannot be understood. |
515 * cannot be understood. |
516 */ |
516 */ |
517 public static synchronized TimeZone getTimeZone(String ID) { |
517 public static synchronized TimeZone getTimeZone(String ID) { |
518 return getTimeZone(ID, true); |
518 return getTimeZone(ID, true); |
519 } |
519 } |
731 |
731 |
732 /** |
732 /** |
733 * Returns true if this zone has the same rule and offset as another zone. |
733 * Returns true if this zone has the same rule and offset as another zone. |
734 * That is, if this zone differs only in ID, if at all. Returns false |
734 * That is, if this zone differs only in ID, if at all. Returns false |
735 * if the other zone is null. |
735 * if the other zone is null. |
736 * @param other the <code>TimeZone</code> object to be compared with |
736 * @param other the {@code TimeZone} object to be compared with |
737 * @return true if the other zone is not null and is the same as this one, |
737 * @return true if the other zone is not null and is the same as this one, |
738 * with the possible exception of the ID |
738 * with the possible exception of the ID |
739 * @since 1.2 |
739 * @since 1.2 |
740 */ |
740 */ |
741 public boolean hasSameRules(TimeZone other) { |
741 public boolean hasSameRules(TimeZone other) { |
742 return other != null && getRawOffset() == other.getRawOffset() && |
742 return other != null && getRawOffset() == other.getRawOffset() && |
743 useDaylightTime() == other.useDaylightTime(); |
743 useDaylightTime() == other.useDaylightTime(); |
744 } |
744 } |
745 |
745 |
746 /** |
746 /** |
747 * Creates a copy of this <code>TimeZone</code>. |
747 * Creates a copy of this {@code TimeZone}. |
748 * |
748 * |
749 * @return a clone of this <code>TimeZone</code> |
749 * @return a clone of this {@code TimeZone} |
750 */ |
750 */ |
751 public Object clone() |
751 public Object clone() |
752 { |
752 { |
753 try { |
753 try { |
754 return super.clone(); |
754 return super.clone(); |