TimeZone


1   /*
2    * @(#)TimeZone.java    1.51 00/01/19
3    *
4    * Copyright (C) 1996-2006, International Business Machines
5    * Corporation and others.  All Rights Reserved.
6    */
7   
8   package com.ibm.icu.util;
9   
10  import java.io.Serializable  ;
11  import java.lang.ref.SoftReference  ;
12  import java.util.Date  ;
13  import java.util.Hashtable  ;
14  import java.util.Locale  ;
15  import java.util.MissingResourceException  ;
16  
17  import com.ibm.icu.impl.ICUResourceBundle;
18  import com.ibm.icu.impl.TimeZoneAdapter;
19  import com.ibm.icu.impl.ZoneMeta;
20  import com.ibm.icu.text.SimpleDateFormat;
21  
22  /**
23   * <code>TimeZone</code> represents a time zone offset, and also figures out daylight
24   * savings.
25   *
26   * <p>
27   * Typically, you get a <code>TimeZone</code> using <code>getDefault</code>
28   * which creates a <code>TimeZone</code> based on the time zone where the program
29   * is running. For example, for a program running in Japan, <code>getDefault</code>
30   * creates a <code>TimeZone</code> object based on Japanese Standard Time.
31   *
32   * <p>
33   * You can also get a <code>TimeZone</code> using <code>getTimeZone</code>
34   * along with a time zone ID. For instance, the time zone ID for the
35   * U.S. Pacific Time zone is "America/Los_Angeles". So, you can get a
36   * U.S. Pacific Time <code>TimeZone</code> object with:
37   * <blockquote>
38   * <pre>
39   * TimeZone tz = TimeZone.getTimeZone("America/Los_Angeles");
40   * </pre>
41   * </blockquote>
42   * You can use <code>getAvailableIDs</code> method to iterate through
43   * all the supported time zone IDs. You can then choose a
44   * supported ID to get a <code>TimeZone</code>.
45   * If the time zone you want is not represented by one of the
46   * supported IDs, then you can create a custom time zone ID with
47   * the following syntax:
48   *
49   * <blockquote>
50   * <pre>
51   * GMT[+|-]hh[[:]mm]
52   * </pre>
53   * </blockquote>
54   *
55   * For example, you might specify GMT+14:00 as a custom
56   * time zone ID.  The <code>TimeZone</code> that is returned
57   * when you specify a custom time zone ID does not include
58   * daylight savings time.
59   * <p>
60   * For compatibility with JDK 1.1.x, some other three-letter time zone IDs
61   * (such as "PST", "CTT", "AST") are also supported. However, <strong>their
62   * use is deprecated</strong> because the same abbreviation is often used
63   * for multiple time zones (for example, "CST" could be U.S. "Central Standard
64   * Time" and "China Standard Time"), and the Java platform can then only
65   * recognize one of them.
66   *
67   *
68   * @see          Calendar
69   * @see          GregorianCalendar
70   * @see          SimpleTimeZone
71   * @author       Mark Davis, David Goldsmith, Chen-Lieh Huang, Alan Liu
72   * @stable ICU 2.0
73   */
74  abstract public class TimeZone implements Serializable  , Cloneable   {
75      // using serialver from jdk1.4.2_05
76      private static final long serialVersionUID = -744942128318337471L;
77  
78      /**
79       * Default constructor.  (For invocation by subclass constructors,
80       * typically implicit.)
81       * @stable ICU 2.8
82       */
83      public TimeZone() {
84      }
85  
86      /**
87       * A style specifier for <code>getDisplayName()</code> indicating
88       * a short name, such as "PST."
89       * @see #LONG
90       * @stable ICU 2.0
91       */
92      public static final int SHORT = 0;
93  
94      /**
95       * A style specifier for <code>getDisplayName()</code> indicating
96       * a long name, such as "Pacific Standard Time."
97       * @see #SHORT
98       * @stable ICU 2.0
99       */
100     public static final int LONG  = 1;
101 
102     /**
103      * @internal
104      * @deprecated This API is ICU internal only.
105      */
106     private static final int SHORT_GENERIC = 2;
107 
108     /**
109      * @internal
110      * @deprecated This API is ICU internal only.
111      */
112     private static final int LONG_GENERIC = 3;
113 
114     /**
115      * Cache to hold the SimpleDateFormat objects for a Locale.
116      */
117     private static Hashtable   cachedLocaleData = new Hashtable  (3);
118 
119     /**
120      * Gets the time zone offset, for current date, modified in case of
121      * daylight savings. This is the offset to add *to* UTC to get local time.
122      * @param era the era of the given date.
123      * @param year the year in the given date.
124      * @param month the month in the given date.
125      * Month is 0-based. e.g., 0 for January.
126      * @param day the day-in-month of the given date.
127      * @param dayOfWeek the day-of-week of the given date.
128      * @param milliseconds the millis in day in <em>standard</em> local time.
129      * @return the offset to add *to* GMT to get local time.
130      * @stable ICU 2.0
131      */
132     abstract public int getOffset(int era, int year, int month, int day,
133                                   int dayOfWeek, int milliseconds);
134 
135 
136     /**
137      * Returns the offset of this time zone from UTC at the specified
138      * date. If Daylight Saving Time is in effect at the specified
139      * date, the offset value is adjusted with the amount of daylight
140      * saving.
141      *
142      * @param date the date represented in milliseconds since January 1, 1970 00:00:00 GMT
143      * @return the amount of time in milliseconds to add to UTC to get local time.
144      *
145      * @see Calendar#ZONE_OFFSET
146      * @see Calendar#DST_OFFSET
147      * @see #getOffset(long, boolean, int[])
148      * @stable ICU 2.8
149      */
150     public int getOffset(long date) {
151     int[] result = new int[2];
152     getOffset(date, false, result);
153     return result[0]+result[1];
154     }
155 
156     /**
157      * Returns the time zone raw and GMT offset for the given moment
158      * in time.  Upon return, local-millis = GMT-millis + rawOffset +
159      * dstOffset.  All computations are performed in the proleptic
160      * Gregorian calendar.  The default implementation in the TimeZone
161      * class delegates to the 8-argument getOffset().
162      *
163      * @param date moment in time for which to return offsets, in
164      * units of milliseconds from January 1, 1970 0:00 GMT, either GMT
165      * time or local wall time, depending on `local'.
166      * @param local if true, `date' is local wall time; otherwise it
167      * is in GMT time.
168      * @param offsets output parameter to receive the raw offset, that
169      * is, the offset not including DST adjustments, in offsets[0],
170      * and the DST offset, that is, the offset to be added to
171      * `rawOffset' to obtain the total offset between local and GMT
172      * time, in offsets[1]. If DST is not in effect, the DST offset is
173      * zero; otherwise it is a positive value, typically one hour.
174      *
175      * @stable ICU 2.8
176      */
177     public void getOffset(long date, boolean local, int[] offsets) {
178         offsets[0] = getRawOffset();
179         
180         // Convert to local wall millis if necessary
181         if (!local) {
182             date += offsets[0]; // now in local standard millis
183         }
184 
185         // When local==FALSE, we might have to recompute. This loop is
186         // executed once, unless a recomputation is required; then it is
187         // executed twice.
188         for (int pass=0; ; ++pass) {
189             int fields[] = new int[4];
190             long day = floorDivide(date, MILLIS_PER_DAY, fields);
191             int millis = fields[0];
192             
193             computeGregorianFields(day, fields);
194             
195             offsets[1] = getOffset(GregorianCalendar.AD,
196                                    fields[0], fields[1], fields[2],
197                                    fields[3], millis) - offsets[0];
198             
199             // Recompute if local==FALSE, dstOffset!=0, and addition of
200             // the dstOffset puts us in a different day.
201             if (pass!=0 || local || offsets[1]==0) {
202                 break;
203             }
204             date += offsets[1];
205             if (floorDivide(date, MILLIS_PER_DAY) == day) {
206                 break;
207             }
208         }
209     }
210     
211     /**
212      * Divide two long integers, returning the floor of the quotient.
213      * <p>
214      * Unlike the built-in division, this is mathematically well-behaved.
215      * E.g., <code>-1/4</code> => 0
216      * but <code>floorDivide(-1,4)</code> => -1.
217      * TODO: This duplicates a method in Calendar; clean up and
218      * consolidate in ICU 3.0.
219      * @param numerator the numerator
220      * @param denominator a divisor which must be > 0
221      * @return the floor of the quotient.
222      */
223     static long floorDivide(long numerator, long denominator) {
224         // We do this computation in order to handle
225         // a numerator of Long.MIN_VALUE correctly
226         return (numerator >= 0) ?
227             numerator / denominator :
228             ((numerator + 1) / denominator) - 1;
229     }
230 
231     /**
232      * Divide two integers, returning the floor of the quotient, and
233      * the modulus remainder.
234      * <p>
235      * Unlike the built-in division, this is mathematically well-behaved.
236      * E.g., <code>-1/4</code> => 0 and <code>-1%4</code> => -1,
237      * but <code>floorDivide(-1,4)</code> => -1 with <code>remainder[0]</code> => 3.
238      * TODO: This duplicates a method in Calendar; clean up and
239      * consolidate in ICU 3.0.
240      * @param numerator the numerator
241      * @param denominator a divisor which must be > 0
242      * @param remainder an array of at least one element in which the value
243      * <code>numerator mod denominator</code> is returned. Unlike <code>numerator
244      * % denominator</code>, this will always be non-negative.
245      * @return the floor of the quotient.
246      */
247     static int floorDivide(long numerator, int denominator, int[] remainder) {
248         if (numerator >= 0) {
249             remainder[0] = (int)(numerator % denominator);
250             return (int)(numerator / denominator);
251         }
252         int quotient = (int)(((numerator + 1) / denominator) - 1);
253         remainder[0] = (int)(numerator - (quotient * denominator));
254         return quotient;
255     }
256 
257     /**
258      * Compute the Gregorian calendar year, month, and day of month
259      * from the epoch day, and return them in the given array.
260      * TODO: This duplicates a method in Calendar; clean up and
261      * consolidate in ICU 3.0.
262      */
263     static void computeGregorianFields(long day, int fields[]) {
264         int year, month, dayOfMonth, dayOfYear;
265 
266         // Convert from 1970 CE epoch to 1 CE epoch (Gregorian calendar)
267         // JULIAN_1_CE    = 1721426; // January 1, 1 CE Gregorian
268         // JULIAN_1970_CE = 2440588; // January 1, 1970 CE Gregorian
269         day += (2440588 - 1721426);
270 
271         // Here we convert from the day number to the multiple radix
272         // representation.  We use 400-year, 100-year, and 4-year cycles.
273         // For example, the 4-year cycle has 4 years + 1 leap day; giving
274         // 1461 == 365*4 + 1 days.
275         int[] rem = new int[1];
276         int n400 = floorDivide(day, 146097, rem); // 400-year cycle length
277         int n100 = floorDivide(rem[0], 36524, rem); // 100-year cycle length
278         int n4 = floorDivide(rem[0], 1461, rem); // 4-year cycle length
279         int n1 = floorDivide(rem[0], 365, rem);
280         year = 400*n400 + 100*n100 + 4*n4 + n1;
281         dayOfYear = rem[0]; // zero-based day of year
282         if (n100 == 4 || n1 == 4) {
283             dayOfYear = 365; // Dec 31 at end of 4- or 400-yr cycle
284         } else {
285             ++year;
286         }
287 
288         boolean isLeap = ((year&0x3) == 0) && // equiv. to (year%4 == 0)
289             (year%100 != 0 || year%400 == 0);
290 
291         int correction = 0;
292         int march1 = isLeap ? 60 : 59; // zero-based DOY for March 1
293         if (dayOfYear >= march1) correction = isLeap ? 1 : 2;
294         month = (12 * (dayOfYear + correction) + 6) / 367; // zero-based month
295         dayOfMonth = dayOfYear -
296             GREGORIAN_MONTH_COUNT[month][isLeap?1:0] + 1; // one-based DOM
297 
298         // Jan 1 1 CE is Monday
299         int dayOfWeek = (int) ((day + Calendar.MONDAY) % 7);
300         if (dayOfWeek < Calendar.SUNDAY) {
301             dayOfWeek += 7;
302         }
303 
304         fields[0] = year;
305         fields[1] = month; // 0-based already
306         fields[2] = dayOfMonth; // 1-based already
307         fields[3] = dayOfWeek; // 1-based already
308         //fields[4] = dayOfYear + 1; // Convert from 0-based to 1-based
309     }
310 
311 
312     /**
313      * The number of milliseconds in an hour.
314      * @internal
315      * @deprecated This API is ICU internal only.
316      */
317     protected static final int MILLIS_PER_HOUR = 60*60*1000;
318 
319     /**
320      * The number of milliseconds in one day.
321      * @internal
322      * @deprecated This API is ICU internal only.
323      */
324     protected static final int MILLIS_PER_DAY = 24*MILLIS_PER_HOUR;
325     
326     /**
327      * For each month, the days in a non-leap year before the start
328      * the of month, and the days in a leap year before the start of
329      * the month.
330      * TODO: This duplicates data in Calendar.java; clean up and
331      * consolidate in ICU 3.0.
332      */
333     static final int[][] GREGORIAN_MONTH_COUNT = {
334         {   0,   0 }, // Jan
335         {  31,  31 }, // Feb
336         {  59,  60 }, // Mar
337         {  90,  91 }, // Apr
338         { 120, 121 }, // May
339         { 151, 152 }, // Jun
340         { 181, 182 }, // Jul
341         { 212, 213 }, // Aug
342         { 243, 244 }, // Sep
343         { 273, 274 }, // Oct
344         { 304, 305 }, // Nov
345         { 334, 335 }  // Dec
346     };
347 
348     /**
349      * Sets the base time zone offset to GMT.
350      * This is the offset to add *to* UTC to get local time.
351      * @param offsetMillis the given base time zone offset to GMT.
352      * @stable ICU 2.0
353      */
354     abstract public void setRawOffset(int offsetMillis);
355 
356     /**
357      * Gets unmodified offset, NOT modified in case of daylight savings.
358      * This is the offset to add *to* UTC to get local time.
359      * @return the unmodified offset to add *to* UTC to get local time.
360      * @stable ICU 2.0
361      */
362     abstract public int getRawOffset();
363 
364     /**
365      * Gets the ID of this time zone.
366      * @return the ID of this time zone.
367      * @stable ICU 2.0
368      */
369     public String   getID() {
370         return ID;
371     }
372 
373     /**
374      * Sets the time zone ID. This does not change any other data in
375      * the time zone object.
376      * @param ID the new time zone ID.
377      * @stable ICU 2.0
378      */
379     public void setID(String   ID) {
380         if (ID == null) {
381             throw new NullPointerException  ();
382         }
383         this.ID = ID;
384     }
385 
386     /**
387      * Returns a name of this time zone suitable for presentation to the user
388      * in the default locale.
389      * This method returns the long generic name.
390      * If the display name is not available for the locale,
391      * a fallback based on the country, city, or time zone id will be used.
392      * @return the human-readable name of this time zone in the default locale.
393      * @stable ICU 2.0
394      */
395     public final String   getDisplayName() {
396         return _getDisplayName(false, LONG_GENERIC, ULocale.getDefault());
397     }
398 
399     /**
400      * Returns a name of this time zone suitable for presentation to the user
401      * in the specified locale.
402      * This method returns the long generic name.
403      * If the display name is not available for the locale,
404      * a fallback based on the country, city, or time zone id will be used.
405      * @param locale the locale in which to supply the display name.
406      * @return the human-readable name of this time zone in the given locale
407      * or in the default locale if the given locale is not recognized.
408      * @stable ICU 2.0
409      */
410     public final String   getDisplayName(Locale   locale) {
411         return _getDisplayName(false, LONG_GENERIC, ULocale.forLocale(locale));
412     }
413 
414     /**
415      * Returns a name of this time zone suitable for presentation to the user
416      * in the specified locale.
417      * This method returns the long name, not including daylight savings.
418      * If the display name is not available for the locale,
419      * a fallback based on the country, city, or time zone id will be used.
420      * @param locale the ulocale in which to supply the display name.
421      * @return the human-readable name of this time zone in the given locale
422      * or in the default ulocale if the given ulocale is not recognized.
423      * @draft ICU 3.2
424      * @provisional This API might change or be removed in a future release.
425      */
426     public final String   getDisplayName(ULocale locale) {
427         return _getDisplayName(false, LONG_GENERIC, locale);
428     }
429 
430     /**
431      * Returns a name of this time zone suitable for presentation to the user
432      * in the default locale.
433      * If the display name is not available for the locale,
434      * then this method returns a string in the format
435      * <code>GMT[+-]hh:mm</code>.
436      * @param daylight if true, return the daylight savings name.
437      * @param style either <code>LONG</code> or <code>SHORT</code>
438      * @return the human-readable name of this time zone in the default locale.
439      * @stable ICU 2.0
440      */
441     public final String   getDisplayName(boolean daylight, int style) {
442         return getDisplayName(daylight, style, ULocale.getDefault());
443     }
444 
445     /**
446      * Returns a name of this time zone suitable for presentation to the user
447      * in the specified locale.
448      * If the display name is not available for the locale,
449      * then this method returns a string in the format
450      * <code>GMT[+-]hh:mm</code>.
451      * @param daylight if true, return the daylight savings name.
452      * @param style either <code>LONG</code> or <code>SHORT</code>
453      * @param locale the locale in which to supply the display name.
454      * @return the human-readable name of this time zone in the given locale
455      * or in the default locale if the given locale is not recognized.
456      * @exception IllegalArgumentException style is invalid.
457      * @stable ICU 2.0
458      */
459     public String   getDisplayName(boolean daylight, int style, Locale   locale) {
460         return getDisplayName(daylight, style, ULocale.forLocale(locale));
461     }
462 
463     /**
464      * Returns a name of this time zone suitable for presentation to the user
465      * in the specified locale.
466      * If the display name is not available for the locale,
467      * then this method returns a string in the format
468      * <code>GMT[+-]hh:mm</code>.
469      * @param daylight if true, return the daylight savings name.
470      * @param style either <code>LONG</code> or <code>SHORT</code>
471      * @param locale the locale in which to supply the display name.
472      * @return the human-readable name of this time zone in the given locale
473      * or in the default locale if the given locale is not recognized.
474      * @exception IllegalArgumentException style is invalid.
475      * @draft ICU 3.2
476      * @provisional This API might change or be removed in a future release.
477      */
478     public String   getDisplayName(boolean daylight, int style, ULocale locale) {
479         if (style != SHORT && style != LONG) {
480             throw new IllegalArgumentException  ("Illegal style: " + style);
481         }
482         return _getDisplayName(daylight, style, locale);
483     }
484 
485     /**
486      * The public version of this API only accepts LONG/SHORT, the
487      * internal version (which this calls) also accepts LONG_GENERIC/SHORT_GENERIC.
488      * @internal
489      * @deprecated This API is ICU internal only.
490      */
491     private String   _getDisplayName(boolean daylight, int style, ULocale locale) {
492         /* NOTES:
493          * (1) We use SimpleDateFormat for simplicity; we could do this
494          * more efficiently but it would duplicate the SimpleDateFormat code
495          * here, which is undesirable.
496          * (2) Attempts to move the code from SimpleDateFormat to here also run
497          * aground because this requires SimpleDateFormat to keep a Locale
498          * object around, which it currently doesn't; to synthesize such a
499          * locale upon resurrection; and to somehow handle the special case of
500          * construction from a DateFormatSymbols object.
501          */
502 
503         // We keep a cache, indexed by locale.  The cache contains a
504         // SimpleDateFormat object, which we create on demand.
505         SoftReference   data = (SoftReference  )cachedLocaleData.get(locale);
506         SimpleDateFormat format;
507         if (data == null ||
508             (format = (SimpleDateFormat)data.get()) == null) {
509             format = new SimpleDateFormat(null, locale);
510             cachedLocaleData.put(locale, new SoftReference  (format));
511         }
512         // Create a new SimpleTimeZone as a stand-in for this zone; the stand-in
513         // will have no DST, or DST during January, but the same ID and offset,
514         // and hence the same display name.  We don't cache these because
515         // they're small and cheap to create.
516         SimpleTimeZone tz;
517         if (daylight && useDaylightTime()) {
518             int savings = getDSTSavings();
519             tz = new SimpleTimeZone(getRawOffset(), getID(),
520                                     Calendar.JANUARY, 1, 0, 0,
521                                     Calendar.FEBRUARY, 1, 0, 0,
522                                     savings);
523         } else {
524             tz = new SimpleTimeZone(getRawOffset(), getID());
525         }
526         String  [] patterns = { "z", "zzzz", "v", "vvvv" };
527         format.applyPattern(patterns[style]);      
528         format.setTimeZone(tz);
529         // Format a date in January.  We use the value 10*ONE_DAY == Jan 11 1970
530         // 0:00 GMT.
531         return format.format(new Date  (864000000L));
532     }
533 
534     /**
535      * Returns the amount of time to be added to local standard time
536      * to get local wall clock time.
537      * <p>
538      * The default implementation always returns 3600000 milliseconds
539      * (i.e., one hour) if this time zone observes Daylight Saving
540      * Time. Otherwise, 0 (zero) is returned.
541      * <p>
542      * If an underlying TimeZone implementation subclass supports
543      * historical Daylight Saving Time changes, this method returns
544      * the known latest daylight saving value.
545      *
546      * @return the amount of saving time in milliseconds
547      * @stable ICU 2.8
548      */
549     public int getDSTSavings() {
550         if (useDaylightTime()) {
551             return 3600000;
552         }
553         return 0;
554     }
555 
556     /**
557      * Queries if this time zone uses daylight savings time.
558      * @return true if this time zone uses daylight savings time,
559      * false, otherwise.
560      * @stable ICU 2.0
561      */
562     abstract public boolean useDaylightTime();
563 
564     /**
565      * Queries if the given date is in daylight savings time in
566      * this time zone.
567      * @param date the given Date.
568      * @return true if the given date is in daylight savings time,
569      * false, otherwise.
570      * @stable ICU 2.0
571      */
572     abstract public boolean inDaylightTime(Date   date);
573 
574     /**
575      * Gets the <code>TimeZone</code> for the given ID.
576      *
577      * @param ID the ID for a <code>TimeZone</code>, either an abbreviation
578      * such as "PST", a full name such as "America/Los_Angeles", or a custom
579      * ID such as "GMT-8:00". Note that the support of abbreviations is
580      * for JDK 1.1.x compatibility only and full names should be used.
581      *
582      * @return the specified <code>TimeZone</code>, or the GMT zone if the given ID
583      * cannot be understood.
584      * @stable ICU 2.0
585      */
586     public static synchronized TimeZone getTimeZone(String   ID) {
587         /* We first try to lookup the zone ID in our system list.  If this
588          * fails, we try to parse it as a custom string GMT[+-]hh:mm.  If
589          * all else fails, we return GMT, which is probably not what the
590          * user wants, but at least is a functioning TimeZone object.
591          *
592          * We cannot return NULL, because that would break compatibility
593          * with the JDK.
594          */
595         if(ID==null){
596             throw new NullPointerException  ();
597         }
598         TimeZone result = ZoneMeta.getSystemTimeZone(ID);
599         
600         if (result == null) {
601             result = ZoneMeta.getCustomTimeZone(ID);
602         }
603         if (result == null) {
604             result = ZoneMeta.getGMT();
605         }
606         return result;
607     }
608 
609     /**
610      * Return a new String array containing all system TimeZone IDs
611      * with the given raw offset from GMT.  These IDs may be passed to
612      * <code>get()</code> to construct the corresponding TimeZone
613      * object.
614      * @param rawOffset the offset in milliseconds from GMT
615      * @return an array of IDs for system TimeZones with the given
616      * raw offset.  If there are none, return a zero-length array.
617      * @stable ICU 2.0
618      */
619     public static String  [] getAvailableIDs(int rawOffset) {
620         return ZoneMeta.getAvailableIDs(rawOffset);
621 
622     }
623 
624 
625     /**
626      * Return a new String array containing all system TimeZone IDs
627      * associated with the given country.  These IDs may be passed to
628      * <code>get()</code> to construct the corresponding TimeZone
629      * object.
630      * @param country a two-letter ISO 3166 country code, or <code>null</code>
631      * to return zones not associated with any country
632      * @return an array of IDs for system TimeZones in the given
633      * country.  If there are none, return a zero-length array.
634      * @stable ICU 2.0
635      */
636     public static String  [] getAvailableIDs(String   country) {
637         return ZoneMeta.getAvailableIDs(country);
638     }
639 
640     /**
641      * Return a new String array containing all system TimeZone IDs.
642      * These IDs (and only these IDs) may be passed to
643      * <code>get()</code> to construct the corresponding TimeZone
644      * object.
645      * @return an array of all system TimeZone IDs
646      * @stable ICU 2.0
647      */
648     public static String  [] getAvailableIDs() {
649         return ZoneMeta.getAvailableIDs();
650     }
651     
652     /**
653      * Returns the number of IDs in the equivalency group that
654      * includes the given ID.  An equivalency group contains zones
655      * that have the same GMT offset and rules.
656      *
657      * <p>The returned count includes the given ID; it is always >= 1
658      * for valid IDs.  The given ID must be a system time zone.  If it
659      * is not, returns zero.
660      * @param id a system time zone ID
661      * @return the number of zones in the equivalency group containing
662      * 'id', or zero if 'id' is not a valid system ID
663      * @see #getEquivalentID
664      * @stable ICU 2.0
665      */
666     public static int countEquivalentIDs(String   id) {
667         return ZoneMeta.countEquivalentIDs(id);
668     }
669 
670     /**
671      * Returns an ID in the equivalency group that
672      * includes the given ID.  An equivalency group contains zones
673      * that have the same GMT offset and rules.
674      *
675      * <p>The given index must be in the range 0..n-1, where n is the
676      * value returned by <code>countEquivalentIDs(id)</code>.  For
677      * some value of 'index', the returned value will be equal to the
678      * given id.  If the given id is not a valid system time zone, or
679      * if 'index' is out of range, then returns an empty string.
680      * @param id a system time zone ID
681      * @param index a value from 0 to n-1, where n is the value
682      * returned by <code>countEquivalentIDs(id)</code>
683      * @return the ID of the index-th zone in the equivalency group
684      * containing 'id', or an empty string if 'id' is not a valid
685      * system ID or 'index' is out of range
686      * @see #countEquivalentIDs
687      * @stable ICU 2.0
688      */
689     public static String   getEquivalentID(String   id, int index) {
690         return ZoneMeta.getEquivalentID(id, index);
691     }
692 
693     /**
694      * Gets the default <code>TimeZone</code> for this host.
695      * The source of the default <code>TimeZone</code> 
696      * may vary with implementation.
697      * @return a default <code>TimeZone</code>.
698      * @stable ICU 2.0
699      */
700     public static synchronized TimeZone getDefault() {
701         if (defaultZone == null) {
702             java.util.TimeZone   temp=java.util.TimeZone.getDefault();
703             defaultZone = getTimeZone(temp.getID());
704         }
705         return (TimeZone) defaultZone.clone();
706     }
707 
708     /**
709      * Sets the <code>TimeZone</code> that is
710      * returned by the <code>getDefault</code> method.  If <code>zone</code>
711      * is null, reset the default to the value it had originally when the
712      * VM first started.
713      * @param tz the new default time zone
714      * @stable ICU 2.0
715      */
716     public static synchronized void setDefault(TimeZone tz) {
717         
718         defaultZone = tz;
719         // Keep java.util.TimeZone default in sync so java.util.Date
720         // can interoperate with com.ibm.icu.util classes.
721         java.util.TimeZone   jdkZone = null;
722         if (tz != null) {
723             jdkZone = TimeZoneAdapter.wrap(tz);
724         }
725         java.util.TimeZone.setDefault(jdkZone);
726     }
727 
728     /**
729      * Returns true if this zone has the same rule and offset as another zone.
730      * That is, if this zone differs only in ID, if at all.  Returns false
731      * if the other zone is null.
732      * @param other the <code>TimeZone</code> object to be compared with
733      * @return true if the other zone is not null and is the same as this one,
734      * with the possible exception of the ID
735      * @stable ICU 2.0
736      */
737     public boolean hasSameRules(TimeZone other) {
738         return other != null &&
739             getRawOffset() == other.getRawOffset() &&
740             useDaylightTime() == other.useDaylightTime();
741     }
742 
743     /**
744      * Overrides Cloneable
745      * @stable ICU 2.0
746      */
747     public Object   clone() {
748         try {
749             TimeZone other = (TimeZone) super.clone();
750             other.ID = ID;
751             return other;
752         } catch (CloneNotSupportedException   e) {
753             throw new IllegalStateException  ();
754         }
755     }
756 
757     /**
758      * Return true if obj is a TimeZone with the same class and ID as this.
759      * @return true if obj is a TimeZone with the same class and ID as this
760      * @param obj the object to compare against
761      * @draft ICU 3.4.2
762      * @provisional This API might change or be removed in a future release.
763      */
764     public boolean equals(Object   obj){
765         if (this == obj) return true;
766         if (obj == null || getClass() != obj.getClass()) return false;
767         return (ID.equals(((TimeZone)obj).ID));
768     }
769 
770     /**
771      * Return the hash code.
772      * @return the hash code
773      * @draft ICU 3.4.2
774      * @provisional This API might change or be removed in a future release.
775      */
776     public int hashCode(){
777         return ID.hashCode();
778     }
779 
780     // =======================privates===============================
781 
782     /**
783      * The string identifier of this <code>TimeZone</code>.  This is a
784      * programmatic identifier used internally to look up <code>TimeZone</code>
785      * objects from the system table and also to map them to their localized
786      * display names.  <code>ID</code> values are unique in the system
787      * table but may not be for dynamically created zones.
788      * @serial
789      */
790     private String             ID;
791 
792     /**
793      * The default time zone, or null if not set.
794      */
795     private static TimeZone  defaultZone = null;
796 
797 }
798 
799 //eof
800
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags