jars/icu4j-4_2_1-src/src/com/ibm/icu/dev/eclipse/plugins/com.ibm.icu.base/src/com/ibm/icu/util/TimeZone.java

   1 /*\r
   2  *******************************************************************************\r
   3  * Copyright (C) 1996-2008, International Business Machines Corporation and    *\r
   4  * others. All Rights Reserved.                                                *\r
   5  *******************************************************************************\r
   6  */\r
   7 \r
   8 package com.ibm.icu.util;\r
   9 \r
  10 import java.io.Serializable;\r
  11 import java.util.Date;\r
  12 import java.util.Locale;\r
  13 \r
  14 /**\r
  15  * <code>TimeZone</code> represents a time zone offset, and also figures out daylight\r
  16  * savings.\r
  17  *\r
  18  * <p>\r
  19  * Typically, you get a <code>TimeZone</code> using <code>getDefault</code>\r
  20  * which creates a <code>TimeZone</code> based on the time zone where the program\r
  21  * is running. For example, for a program running in Japan, <code>getDefault</code>\r
  22  * creates a <code>TimeZone</code> object based on Japanese Standard Time.\r
  23  *\r
  24  * <p>\r
  25  * You can also get a <code>TimeZone</code> using <code>getTimeZone</code>\r
  26  * along with a time zone ID. For instance, the time zone ID for the\r
  27  * U.S. Pacific Time zone is "America/Los_Angeles". So, you can get a\r
  28  * U.S. Pacific Time <code>TimeZone</code> object with:\r
  29  * <blockquote>\r
  30  * <pre>\r
  31  * TimeZone tz = TimeZone.getTimeZone("America/Los_Angeles");\r
  32  * </pre>\r
  33  * </blockquote>\r
  34  * You can use <code>getAvailableIDs</code> method to iterate through\r
  35  * all the supported time zone IDs. You can then choose a\r
  36  * supported ID to get a <code>TimeZone</code>.\r
  37  * If the time zone you want is not represented by one of the\r
  38  * supported IDs, then you can create a custom time zone ID with\r
  39  * the following syntax:\r
  40  *\r
  41  * <blockquote>\r
  42  * <pre>\r
  43  * GMT[+|-]hh[[:]mm]\r
  44  * </pre>\r
  45  * </blockquote>\r
  46  *\r
  47  * For example, you might specify GMT+14:00 as a custom\r
  48  * time zone ID.  The <code>TimeZone</code> that is returned\r
  49  * when you specify a custom time zone ID does not include\r
  50  * daylight savings time.\r
  51  * <p>\r
  52  * For compatibility with JDK 1.1.x, some other three-letter time zone IDs\r
  53  * (such as "PST", "CTT", "AST") are also supported. However, <strong>their\r
  54  * use is deprecated</strong> because the same abbreviation is often used\r
  55  * for multiple time zones (for example, "CST" could be U.S. "Central Standard\r
  56  * Time" and "China Standard Time"), and the Java platform can then only\r
  57  * recognize one of them.\r
  58  *\r
  59  * @see          Calendar\r
  60  * @see          GregorianCalendar\r
  61  * @see          SimpleTimeZone\r
  62  * @author       Mark Davis, David Goldsmith, Chen-Lieh Huang, Alan Liu\r
  63  * @stable ICU 2.0\r
  64  */\r
  65 public class TimeZone implements Serializable, Cloneable {\r
  66     private static final long serialVersionUID = 1;\r
  67         \r
  68     /**\r
  69      * @internal\r
  70      */\r
  71     public final java.util.TimeZone timeZone;\r
  72         \r
  73     /**\r
  74      * @internal\r
  75      * @param delegate the TimeZone to which to delegate\r
  76      */\r
  77     public TimeZone(java.util.TimeZone delegate) {\r
  78         this.timeZone = delegate;\r
  79     }\r
  80 \r
  81     /**\r
  82      * Default constructor to mirror Java's public\r
  83      * constructor.  Java's is not callable as a public API, since\r
  84      * their TimeZone is abstract, so this is only useful to\r
  85      * subclasses.  In general, subclasses will not work unless\r
  86      * they manipulate the delegate.\r
  87      */\r
  88     public TimeZone() {\r
  89         this.timeZone = java.util.TimeZone.getDefault();\r
  90     }\r
  91     \r
  92     /**\r
  93      * A style specifier for <code>getDisplayName()</code> indicating\r
  94      * a short name, such as "PST."\r
  95      * @see #LONG\r
  96      * @stable ICU 2.0\r
  97      */\r
  98     public static final int SHORT = 0;\r
  99 \r
 100     /**\r
 101      * A style specifier for <code>getDisplayName()</code> indicating\r
 102      * a long name, such as "Pacific Standard Time."\r
 103      * @see #SHORT\r
 104      * @stable ICU 2.0\r
 105      */\r
 106     public static final int LONG  = 1;\r
 107 \r
 108     /**\r
 109      * Gets the time zone offset, for current date, modified in case of\r
 110      * daylight savings. This is the offset to add *to* UTC to get local time.\r
 111      * @param era the era of the given date.\r
 112      * @param year the year in the given date.\r
 113      * @param month the month in the given date.\r
 114      * Month is 0-based. e.g., 0 for January.\r
 115      * @param day the day-in-month of the given date.\r
 116      * @param dayOfWeek the day-of-week of the given date.\r
 117      * @param milliseconds the millis in day in <em>standard</em> local time.\r
 118      * @return the offset to add *to* GMT to get local time.\r
 119      * @stable ICU 2.0\r
 120      */\r
 121     public int getOffset(int era, int year, int month, int day,\r
 122                          int dayOfWeek, int milliseconds) {\r
 123         return timeZone.getOffset(era, year, month, day, dayOfWeek, milliseconds);\r
 124     }\r
 125 \r
 126     /**\r
 127      * Returns the offset of this time zone from UTC at the specified\r
 128      * date. If Daylight Saving Time is in effect at the specified\r
 129      * date, the offset value is adjusted with the amount of daylight\r
 130      * saving.\r
 131      *\r
 132      * @param date the date represented in milliseconds since January 1, 1970 00:00:00 GMT\r
 133      * @return the amount of time in milliseconds to add to UTC to get local time.\r
 134      *\r
 135      * @see Calendar#ZONE_OFFSET\r
 136      * @see Calendar#DST_OFFSET\r
 137      * @see #getOffset(long, boolean, int[])\r
 138      * @stable ICU 2.8\r
 139      */\r
 140     public int getOffset(long date) {\r
 141         if (inDaylightTime(new Date(date))) {\r
 142             return getRawOffset() + getDSTSavings();\r
 143         }\r
 144         return getRawOffset();\r
 145     }\r
 146 \r
 147    /**\r
 148      * Sets the base time zone offset to GMT.\r
 149      * This is the offset to add *to* UTC to get local time.\r
 150      * @param offsetMillis the given base time zone offset to GMT.\r
 151      * @stable ICU 2.0\r
 152      */\r
 153     public void setRawOffset(int offsetMillis) {\r
 154         timeZone.setRawOffset(offsetMillis);\r
 155     }\r
 156 \r
 157     /**\r
 158      * Gets unmodified offset, NOT modified in case of daylight savings.\r
 159      * This is the offset to add *to* UTC to get local time.\r
 160      * @return the unmodified offset to add *to* UTC to get local time.\r
 161      * @stable ICU 2.0\r
 162      */\r
 163     public int getRawOffset() {\r
 164         return timeZone.getRawOffset();\r
 165     }\r
 166 \r
 167     /**\r
 168      * Gets the ID of this time zone.\r
 169      * @return the ID of this time zone.\r
 170      * @stable ICU 2.0\r
 171      */\r
 172     public String getID() {\r
 173         return timeZone.getID();\r
 174     }\r
 175 \r
 176     /**\r
 177      * Sets the time zone ID. This does not change any other data in\r
 178      * the time zone object.\r
 179      * @param ID the new time zone ID.\r
 180      * @stable ICU 2.0\r
 181      */\r
 182     public void setID(String ID) {\r
 183         timeZone.setID(ID);\r
 184     }\r
 185 \r
 186     /**\r
 187      * Returns a name of this time zone suitable for presentation to the user\r
 188      * in the default locale.\r
 189      * This method returns the long generic name.\r
 190      * If the display name is not available for the locale,\r
 191      * a fallback based on the country, city, or time zone id will be used.\r
 192      * @return the human-readable name of this time zone in the default locale.\r
 193      * @stable ICU 2.0\r
 194      */\r
 195     public final String getDisplayName() {\r
 196         return timeZone.getDisplayName();\r
 197     }\r
 198 \r
 199     /**\r
 200      * Returns a name of this time zone suitable for presentation to the user\r
 201      * in the specified locale.\r
 202      * This method returns the long generic name.\r
 203      * If the display name is not available for the locale,\r
 204      * a fallback based on the country, city, or time zone id will be used.\r
 205      * @param locale the locale in which to supply the display name.\r
 206      * @return the human-readable name of this time zone in the given locale\r
 207      * or in the default locale if the given locale is not recognized.\r
 208      * @stable ICU 2.0\r
 209      */\r
 210     public final String getDisplayName(Locale locale) {\r
 211         return timeZone.getDisplayName(locale);\r
 212     }\r
 213 \r
 214     /**\r
 215      * Returns a name of this time zone suitable for presentation to the user\r
 216      * in the specified locale.\r
 217      * This method returns the long name, not including daylight savings.\r
 218      * If the display name is not available for the locale,\r
 219      * a fallback based on the country, city, or time zone id will be used.\r
 220      * @param locale the ulocale in which to supply the display name.\r
 221      * @return the human-readable name of this time zone in the given locale\r
 222      * or in the default ulocale if the given ulocale is not recognized.\r
 223      * @stable ICU 3.2\r
 224      */\r
 225     public final String getDisplayName(ULocale locale) {\r
 226         return timeZone.getDisplayName(locale.toLocale());\r
 227     }\r
 228 \r
 229     /**\r
 230      * Returns a name of this time zone suitable for presentation to the user\r
 231      * in the default locale.\r
 232      * If the display name is not available for the locale,\r
 233      * then this method returns a string in the format\r
 234      * <code>GMT[+-]hh:mm</code>.\r
 235      * @param daylight if true, return the daylight savings name.\r
 236      * @param style either <code>LONG</code> or <code>SHORT</code>\r
 237      * @return the human-readable name of this time zone in the default locale.\r
 238      * @stable ICU 2.0\r
 239      */\r
 240     public final String getDisplayName(boolean daylight, int style) {\r
 241         return timeZone.getDisplayName(daylight, style);\r
 242     }\r
 243 \r
 244     /**\r
 245      * Returns a name of this time zone suitable for presentation to the user\r
 246      * in the specified locale.\r
 247      * If the display name is not available for the locale,\r
 248      * then this method returns a string in the format\r
 249      * <code>GMT[+-]hh:mm</code>.\r
 250      * @param daylight if true, return the daylight savings name.\r
 251      * @param style either <code>LONG</code> or <code>SHORT</code>\r
 252      * @param locale the locale in which to supply the display name.\r
 253      * @return the human-readable name of this time zone in the given locale\r
 254      * or in the default locale if the given locale is not recognized.\r
 255      * @exception IllegalArgumentException style is invalid.\r
 256      * @stable ICU 2.0\r
 257      */\r
 258     public String getDisplayName(boolean daylight, int style, Locale locale) {\r
 259         return timeZone.getDisplayName(daylight, style, locale);\r
 260     }\r
 261 \r
 262     /**\r
 263      * Returns a name of this time zone suitable for presentation to the user\r
 264      * in the specified locale.\r
 265      * If the display name is not available for the locale,\r
 266      * then this method returns a string in the format\r
 267      * <code>GMT[+-]hh:mm</code>.\r
 268      * @param daylight if true, return the daylight savings name.\r
 269      * @param style either <code>LONG</code> or <code>SHORT</code>\r
 270      * @param locale the locale in which to supply the display name.\r
 271      * @return the human-readable name of this time zone in the given locale\r
 272      * or in the default locale if the given locale is not recognized.\r
 273      * @exception IllegalArgumentException style is invalid.\r
 274      * @stable ICU 3.2\r
 275      */\r
 276     public String getDisplayName(boolean daylight, int style, ULocale locale) {\r
 277         return timeZone.getDisplayName(daylight, style, locale.toLocale());\r
 278     }\r
 279 \r
 280     /**\r
 281      * Returns the amount of time to be added to local standard time\r
 282      * to get local wall clock time.\r
 283      * <p>\r
 284      * The default implementation always returns 3600000 milliseconds\r
 285      * (i.e., one hour) if this time zone observes Daylight Saving\r
 286      * Time. Otherwise, 0 (zero) is returned.\r
 287      * <p>\r
 288      * If an underlying TimeZone implementation subclass supports\r
 289      * historical Daylight Saving Time changes, this method returns\r
 290      * the known latest daylight saving value.\r
 291      *\r
 292      * @return the amount of saving time in milliseconds\r
 293      * @stable ICU 2.8\r
 294      */\r
 295     public int getDSTSavings() {\r
 296         if (useDaylightTime()) {\r
 297             return 3600000;\r
 298         }\r
 299         return 0;\r
 300     }\r
 301 \r
 302     /**\r
 303      * Queries if this time zone uses daylight savings time.\r
 304      * @return true if this time zone uses daylight savings time,\r
 305      * false, otherwise.\r
 306      * @stable ICU 2.0\r
 307      */\r
 308     public boolean useDaylightTime() {\r
 309         return timeZone.useDaylightTime();\r
 310     }\r
 311 \r
 312     /**\r
 313      * Queries if the given date is in daylight savings time in\r
 314      * this time zone.\r
 315      * @param date the given Date.\r
 316      * @return true if the given date is in daylight savings time,\r
 317      * false, otherwise.\r
 318      * @stable ICU 2.0\r
 319      */\r
 320     public boolean inDaylightTime(Date date) {\r
 321         return timeZone.inDaylightTime(date);\r
 322     }\r
 323 \r
 324     /**\r
 325      * Gets the <code>TimeZone</code> for the given ID.\r
 326      *\r
 327      * @param ID the ID for a <code>TimeZone</code>, either an abbreviation\r
 328      * such as "PST", a full name such as "America/Los_Angeles", or a custom\r
 329      * ID such as "GMT-8:00". Note that the support of abbreviations is\r
 330      * for JDK 1.1.x compatibility only and full names should be used.\r
 331      *\r
 332      * @return the specified <code>TimeZone</code>, or the GMT zone if the given ID\r
 333      * cannot be understood.\r
 334      * @stable ICU 2.0\r
 335      */\r
 336     public static TimeZone getTimeZone(String ID) {\r
 337         return new TimeZone(java.util.TimeZone.getTimeZone(ID));\r
 338     }\r
 339 \r
 340     /**\r
 341      * Return a new String array containing all system TimeZone IDs\r
 342      * with the given raw offset from GMT.  These IDs may be passed to\r
 343      * <code>get()</code> to construct the corresponding TimeZone\r
 344      * object.\r
 345      * @param rawOffset the offset in milliseconds from GMT\r
 346      * @return an array of IDs for system TimeZones with the given\r
 347      * raw offset.  If there are none, return a zero-length array.\r
 348      * @stable ICU 2.0\r
 349      */\r
 350     public static String[] getAvailableIDs(int rawOffset) {\r
 351         return java.util.TimeZone.getAvailableIDs(rawOffset);\r
 352     }\r
 353 \r
 354     /**\r
 355      * Return a new String array containing all system TimeZone IDs.\r
 356      * These IDs (and only these IDs) may be passed to\r
 357      * <code>get()</code> to construct the corresponding TimeZone\r
 358      * object.\r
 359      * @return an array of all system TimeZone IDs\r
 360      * @stable ICU 2.0\r
 361      */\r
 362     public static String[] getAvailableIDs() {\r
 363         return java.util.TimeZone.getAvailableIDs();\r
 364     }\r
 365   \r
 366     /**\r
 367      * Gets the default <code>TimeZone</code> for this host.\r
 368      * The source of the default <code>TimeZone</code> \r
 369      * may vary with implementation.\r
 370      * @return a default <code>TimeZone</code>.\r
 371      * @stable ICU 2.0\r
 372      */\r
 373     public static TimeZone getDefault() {\r
 374         return new TimeZone(java.util.TimeZone.getDefault());\r
 375     }\r
 376 \r
 377     /**\r
 378      * Sets the <code>TimeZone</code> that is\r
 379      * returned by the <code>getDefault</code> method.  If <code>zone</code>\r
 380      * is null, reset the default to the value it had originally when the\r
 381      * VM first started.\r
 382      * @param tz the new default time zone\r
 383      * @stable ICU 2.0\r
 384      */\r
 385     public static void setDefault(TimeZone tz) {\r
 386         java.util.TimeZone.setDefault(tz.timeZone);\r
 387     }\r
 388         \r
 389     /**\r
 390      * Returns true if this zone has the same rule and offset as another zone.\r
 391      * That is, if this zone differs only in ID, if at all.  Returns false\r
 392      * if the other zone is null.\r
 393      * @param other the <code>TimeZone</code> object to be compared with\r
 394      * @return true if the other zone is not null and is the same as this one,\r
 395      * with the possible exception of the ID\r
 396      * @stable ICU 2.0\r
 397      */\r
 398     public boolean hasSameRules(TimeZone other) {\r
 399         return timeZone.hasSameRules(other.timeZone);\r
 400     }\r
 401 \r
 402     /**\r
 403      * Overrides Cloneable\r
 404      * @stable ICU 2.0\r
 405      */\r
 406     public Object clone() {\r
 407         return new TimeZone((java.util.TimeZone)timeZone.clone());\r
 408     }\r
 409     \r
 410     /**\r
 411      * Return true if rhs is a TimeZone and has the same time rules as this.\r
 412      * @return true if rhs equals this\r
 413      * @stable ICU 3.4.2\r
 414      */\r
 415     public boolean equals(Object rhs){\r
 416         try {\r
 417             return timeZone.equals(((TimeZone)rhs).timeZone);\r
 418         }\r
 419         catch (Exception e) {\r
 420             return false;\r
 421         }\r
 422     }\r
 423 \r
 424     /**\r
 425      * Return a hashCode.\r
 426      * @return a hashCode\r
 427      * @stable ICU 3.4.2\r
 428      */\r
 429     public int hashCode(){\r
 430         return timeZone.hashCode();\r
 431     }\r
 432 }\r