Top Description Inners Fields Constructors Methods
com.ibm.icu.util

public abstract Class TimeZone

extends Object
implements Serializable, Cloneable, Freezable<TimeZone>
Class Inheritance
All Implemented Interfaces
com.ibm.icu.util.Freezable, java.lang.Cloneable, java.io.Serializable
Known Direct Subclasses
com.ibm.icu.util.TimeZone.ConstantZone, com.ibm.icu.impl.JavaTimeZone, com.ibm.icu.util.BasicTimeZone
Imports
java.io.Serializable, java.util.Date, .Locale, .MissingResourceException, .Set, java.util.logging.Logger, com.ibm.icu.impl.Grego, .ICUConfig, .ICUData, .ICUResourceBundle, .JavaTimeZone, .TimeZoneAdapter, .ZoneMeta, com.ibm.icu.text.TimeZoneFormat, .TimeZoneFormat.Style, .TimeZoneFormat.TimeType, .TimeZoneNames, .TimeZoneNames.NameType, com.ibm.icu.util.ULocale.Category

ICU Enhancement

This class is ICU's replacement for java.util.TimeZone.

ICU

Methods, fields, and other functionality specific to ICU are labeled 'ICU'.

TimeZone represents a time zone offset, and also computes daylight savings.

Typically, you get a TimeZone using getDefault() which creates a TimeZone based on the time zone where the program is running. For example, for a program running in Japan, getDefault creates a TimeZone object based on Japanese Standard Time.

You can also get a TimeZone using getTimeZone(String) along with a time zone ID. For instance, the time zone ID for the U.S. Pacific Time zone is "America/Los_Angeles". So, you can get a U.S. Pacific Time TimeZone object with:

TimeZone tz = TimeZone.getTimeZone("America/Los_Angeles");
You can use the getAvailableIDs() method to iterate through all the supported time zone IDs, or getCanonicalID method to check if a time zone ID is supported or not. You can then choose a supported ID to get a TimeZone. If the time zone you want is not represented by one of the supported IDs, then you can create a custom time zone ID with the following syntax:
GMT[+|-]hh[[:]mm]
For example, you might specify GMT+14:00 as a custom time zone ID. The TimeZone that is returned when you specify a custom time zone ID uses the specified offset from GMT(=UTC) and does not observe daylight saving time. For example, you might specify GMT+14:00 as a custom time zone ID to create a TimeZone representing 14 hours ahead of GMT (with no daylight saving time). In addition, getCanonicalID can also be used to normalize a custom time zone ID.

For compatibility with JDK 1.1.x, some other three-letter time zone IDs (such as "PST", "CTT", "AST") are also supported. However, their use is deprecated because the same abbreviation is often used for multiple time zones (for example, "CST" could be U.S. "Central Standard Time" and "China Standard Time"), and the Java platform can then only recognize one of them.

Note

Starting from ICU4J 4.0, you can optionally choose JDK TimeZone as the time zone implementation. The TimeZone factory method getTimeZone creates an instance of ICU's own TimeZone subclass by default. If you want to use the JDK implementation always, you can set the default time zone implementation type by the new method setDefaultTimeZoneType. Alternatively, you can change the initial default implementation type by setting a property below.

#
# The default TimeZone implementation type used by the ICU TimeZone
# factory method. [ ICU | JDK ]
#
com.ibm.icu.util.TimeZone.DefaultTimeZoneType = ICU

This property is included in ICUConfig.properties in com.ibm.icu package. When the TimeZone class is loaded, the initialization code checks if the property com.ibm.icu.util.TimeZone.DefaultTimeZoneType=xxx is defined by the system properties. If not available, then it loads ICUConfig.properties to get the default time zone implementation type. The property setting is only used for the initial default value and you can change the default type by calling setDefaultTimeZoneType at runtime.

Author
Mark Davis, Deborah Goldsmith, Chen-Lieh Huang, Alan Liu
ICU Status
Stable since ICU 2.0.
See Also
Calendar, GregorianCalendar, SimpleTimeZone

Nested and Inner Type Summary

Modifier and TypeClass and Description
private static class
public static enum

Field Summary

Modifier and TypeField and Description
private static volatile TimeZone
defaultZone

The default time zone, or null if not set.

public static final int
public static final TimeZone
pack-priv static final String
GMT_ZONE_ID

The canonical ID for GMT(UTC) time zone.

private String
ID

The string identifier of this TimeZone.

private static final Logger
LOGGER

Logger instance for this class

public static final int
LONG

A style specifier for getDisplayName() indicating a long name, such as "Pacific Standard Time."

public static final int
public static final int
private static final long
public static final int
SHORT

A style specifier for getDisplayName() indicating a short name, such as "PST."

public static final int
public static final int
public static final int
public static final int
public static final int
private static int
TZ_IMPL

TimeZone implementation type

private static final String
private static final String
private static final String
TZIMPL_CONFIG_KEY

TimeZone implementation type initialization

public static final TimeZone
public static final String

Constructor Summary

AccessConstructor and Description
public
TimeZone()

Default constructor.

protected
TimeZone(String
the time zone ID.
ID
)

Deprecated This API is ICU internal only.
Constructing a TimeZone with the given time zone ID.

Method Summary

Modifier and TypeMethod and Description
private String
_getDisplayName(int style, boolean daylight, ULocale locale)

internal version (which is called by public APIs) accepts SHORT, LONG, SHORT_GENERIC, LONG_GENERIC, SHORT_GMT, LONG_GMT, SHORT_COMMONLY_USED and GENERIC_LOCATION.

public Object
clone()

Overrides java.lang.Object.clone.

Overrides clone.
public TimeZone
cloneAsThawed()

Implements com.ibm.icu.util.Freezable.cloneAsThawed.

Provides for the clone operation.
public static int

Returns:

the number of zones in the equivalency group containing 'id', or zero if 'id' is not a valid system ID
countEquivalentIDs
(String
a system time zone ID
id
)

ICU

public boolean

Returns:

true if this object is the same as the obj argument; false otherwise.
equals
(Object
the reference object with which to compare.
obj
)

Overrides java.lang.Object.equals.

Overrides equals.
public static TimeZone

Returns:

A TimeZone. Clients are responsible for deleting the TimeZone object returned.
forLocaleOrDefault
(Locale
a locale which may contains 'timezone' keyword/value.
locale
)

Deprecated This API is ICU internal only.
If the locale contains the timezone keyword, creates a copy of that TimeZone.
public static TimeZone

Returns:

A TimeZone. Clients are responsible for deleting the TimeZone object returned.
forULocaleOrDefault
(ULocale
a locale which may contains 'timezone' keyword/value.
locale
)

Deprecated This API is ICU internal only.
If the locale contains the timezone keyword, creates a copy of that TimeZone.
public TimeZone
freeze()

Implements com.ibm.icu.util.Freezable.freeze.

Freezes the object.
public static Set<String>

Returns:

an immutable set of system time zone IDs.
getAvailableIDs
(TimeZone.SystemTimeZoneType
The system time zone type.
zoneType
,
String
The ISO 3166 two-letter country code or UN M.49 three-digit area code. When null, no filtering done by region.
region
,
Integer
An offset from GMT in milliseconds, ignoring the effect of daylight savings time, if any. When null, no filtering done by zone offset.
rawOffset
)

ICU

public static String[]

Returns:

an array of IDs for system TimeZones with the given raw offset. If there are none, return a zero-length array.
getAvailableIDs
(int
the offset in milliseconds from GMT
rawOffset
)

Return a new String array containing all system TimeZone IDs with the given raw offset from GMT.

public static String[]

Returns:

an array of IDs for system TimeZones in the given country. If there are none, return a zero-length array.
getAvailableIDs
(String
a two-letter ISO 3166 country code, or null to return zones not associated with any country
country
)

Return a new String array containing all system TimeZone IDs associated with the given country.

public static String[]

Returns:

an array of all system TimeZone IDs
getAvailableIDs
()

Return a new String array containing all system TimeZone IDs.

public static String

Returns:

The canonical system time zone ID or the custom time zone ID in normalized format for the given time zone ID. When the given time zone ID is neither a known system time zone ID nor a valid custom time zone ID, null is returned.
getCanonicalID
(String
The input time zone ID to be canonicalized.
id
)

ICU

public static String

Returns:

The canonical system time zone ID or the custom time zone ID in normalized format for the given time zone ID. When the given time zone ID is neither a known system time zone ID nor a valid custom time zone ID, null is returned.
getCanonicalID
(String
The input time zone ID to be canonicalized.
id
,
boolean[]
When non-null boolean array is specified and the given ID is a known system time zone ID, true is set to isSystemID[0]
isSystemID
)

ICU

public static TimeZone

Returns:

a default TimeZone.
getDefault
()

Gets the default TimeZone for this host.

public static int

Returns:

The default time zone type, either TIMEZONE_ICU or TIMEZONE_JDK.
getDefaultTimeZoneType
()

ICU

public final String

Returns:

the human-readable name of this time zone in the default locale.
getDisplayName
()

Returns a name of this time zone suitable for presentation to the user in the default DISPLAY locale.

public final String

Returns:

the human-readable name of this time zone in the given locale or in the default locale if the given locale is not recognized.
getDisplayName
(Locale
the locale in which to supply the display name.
locale
)

Returns a name of this time zone suitable for presentation to the user in the specified locale.

public final String

Returns:

the human-readable name of this time zone in the given locale or in the default ulocale if the given ulocale is not recognized.
getDisplayName
(ULocale
the ulocale in which to supply the display name.
locale
)

Returns a name of this time zone suitable for presentation to the user in the specified locale.

public final String

Returns:

the human-readable name of this time zone in the default locale.
getDisplayName
(boolean
if true, return the daylight savings name.
daylight
,
int
the output style of the display name. Valid styles are SHORT, LONG, SHORT_GENERIC, LONG_GENERIC, SHORT_GMT, LONG_GMT, SHORT_COMMONLY_USED or GENERIC_LOCATION.
style
)

Returns a name of this time zone suitable for presentation to the user in the default DISPLAY locale.

public String

Returns:

the human-readable name of this time zone in the given locale or in the default locale if the given locale is not recognized.
getDisplayName
(boolean
if true, return the daylight savings name.
daylight
,
int
the output style of the display name. Valid styles are SHORT, LONG, SHORT_GENERIC, LONG_GENERIC, SHORT_GMT, LONG_GMT, SHORT_COMMONLY_USED or GENERIC_LOCATION.
style
,
Locale
the locale in which to supply the display name.
locale
)

Returns a name of this time zone suitable for presentation to the user in the specified locale.

public String

Returns:

the human-readable name of this time zone in the given locale or in the default locale if the given locale is not recognized.
getDisplayName
(boolean
if true, return the daylight savings name.
daylight
,
int
the output style of the display name. Valid styles are SHORT, LONG, SHORT_GENERIC, LONG_GENERIC, SHORT_GMT, LONG_GMT, SHORT_COMMONLY_USED or GENERIC_LOCATION.
style
,
ULocale
the locale in which to supply the display name.
locale
)

Returns a name of this time zone suitable for presentation to the user in the specified locale.

public int

Returns:

the amount of saving time in milliseconds
getDSTSavings
()

Returns the amount of time to be added to local standard time to get local wall clock time.

public static String

Returns:

the ID of the index-th zone in the equivalency group containing 'id', or an empty string if 'id' is not a valid system ID or 'index' is out of range
getEquivalentID
(String
a system time zone ID
id
,
int
a value from 0 to n-1, where n is the value returned by countEquivalentIDs(id)
index
)

Returns an ID in the equivalency group that includes the given ID. An equivalency group contains zones that have the same GMT offset and rules.

pack-priv static BasicTimeZone

Returns:

the frozen ICU TimeZone or null if one could not be created.
getFrozenICUTimeZone
(String
the time zone ID
id
,
boolean
if true tries the system time zones first otherwise skip to the custom time zones.
trySystem
)

Returns a frozen ICU type TimeZone object given a time zone ID.

public static TimeZone

Returns:

the specified TimeZone, or the UNKNOWN_ZONE if the given ID cannot be understood.
getFrozenTimeZone
(String
the ID for a TimeZone, such as "America/Los_Angeles", or a custom ID such as "GMT-8:00". Note that the support of abbreviations, such as "PST", is for JDK 1.1.x compatibility only and full names should be used.
ID
)

Gets the TimeZone for the given ID. The instance of TimeZone returned by this method is immutable.

public static String

Returns:

The preferred time zone ID in the IANA time zone database, or TimeZone#UNKNOWN_ZONE_ID if the input ID is not a system ID.
getIanaID
(String
The input time zone ID.
id
)

Returns the preferred time zone ID in the IANA database for the given time zone ID. There are two types of preferred IDs.

public String

Returns:

the ID of this time zone.
getID
()

Gets the ID of this time zone.

public static String

Returns:

A system time zone ID mapped from the input Windows time zone ID, or null when the input ID is unknown or unmappable.
getIDForWindowsID
(String
A Windows time zone ID
winid
,
String
A region code, or null if no regional preference.
region
)

ICU

public abstract int

Returns:

the offset to add to GMT to get local time.
getOffset
(int
the era of the given date.
era
,
int
the year in the given date.
year
,
int
the month in the given date. Month is 0-based. e.g., 0 for January.
month
,
int
the day-in-month of the given date.
day
,
int
the day-of-week of the given date.
dayOfWeek
,
int
the millis in day in standard local time.
milliseconds
)

Gets the time zone offset, for current date, modified in case of daylight savings.

public int

Returns:

the amount of time in milliseconds to add to UTC to get local time.
getOffset
(long
the date represented in milliseconds since January 1, 1970 00:00:00 GMT
date
)

Returns the offset of this time zone from UTC at the specified date.

public void
getOffset(long
moment in time for which to return offsets, in units of milliseconds from January 1, 1970 0:00 GMT, either GMT time or local wall time, depending on local.
date
,
boolean
if true, date is local wall time; otherwise it is in GMT time.
local
,
int[]
output parameter to receive the raw offset, that is, the offset not including DST adjustments, in offsets[0], and the DST offset, that is, the offset to be added to rawOffset to obtain the total offset between local and GMT time, in offsets[1]. If DST is not in effect, the DST offset is zero; otherwise it is a positive value, typically one hour.
offsets
)

Returns the time zone raw and GMT offset for the given moment in time.

public abstract int

Returns:

the unmodified offset to add to UTC to get local time.
getRawOffset
()

Gets unmodified offset, NOT modified in case of daylight savings.

public static String

Returns:

the region code associated with the given system time zone ID.
getRegion
(String
the system time zone ID.
id
)

ICU

public static TimeZone

Returns:

the specified TimeZone, or a mutable clone of the UNKNOWN_ZONE if the given ID cannot be understood or if the given ID is "Etc/Unknown".
getTimeZone
(String
the ID for a TimeZone, such as "America/Los_Angeles", or a custom ID such as "GMT-8:00". Note that the support of abbreviations, such as "PST", is for JDK 1.1.x compatibility only and full names should be used.
ID
)

Gets the TimeZone for the given ID.

public static TimeZone

Returns:

the specified TimeZone, or a mutable clone of the UNKNOWN_ZONE if the given ID cannot be understood or if the given ID is "Etc/Unknown".
getTimeZone
(String
the ID for a TimeZone, such as "America/Los_Angeles", or a custom ID such as "GMT-8:00". Note that the support of abbreviations, such as "PST", is for JDK 1.1.x compatibility only and full names should be used.
ID
,
int
Time zone type, either TIMEZONE_ICU or TIMEZONE_JDK.
type
)

Gets the TimeZone for the given ID and the timezone type.

private static TimeZone

Returns:

the specified TimeZone or UNKNOWN_ZONE if the given ID cannot be understood.
getTimeZone
(String
time zone ID
id
,
int
time zone implementation type, TIMEZONE_JDK or TIMEZONE_ICU
type
,
boolean
specify if the returned object can be frozen
frozen
)

Gets the TimeZone for the given ID and the timezone type.

public static String

Returns:

the version string, such as "2007f"
getTZDataVersion
()

ICU

public static String

Returns:

A Windows time zone ID mapped from the input system time zone ID, or null when the input ID is unknown or unmappable.
getWindowsID
(String
A system time zone ID
id
)

ICU

public int

Returns:

a hash code value for this object.
hashCode
()

Overrides java.lang.Object.hashCode.

Overrides hashCode.
public boolean

Returns:

true if the other zone is not null and is the same as this one, with the possible exception of the ID
hasSameRules
(TimeZone
the TimeZone object to be compared with
other
)

Returns true if this zone has the same rule and offset as another zone.

public abstract boolean

Returns:

true if the given date is in daylight savings time, false, otherwise.
inDaylightTime
(Date
the given Date.
date
)

Queries if the given date is in daylight savings time in this time zone.

public boolean
isFrozen()

Implements com.ibm.icu.util.Freezable.isFrozen.

Determines whether the object has been frozen or not.
public boolean

Returns:

true if this time zone is in daylight saving time or will observe daylight saving time at any future time.
observesDaylightTime
()

Queries if this time zone is in daylight saving time or will observe daylight saving time at any future time.

public static synchronized void
setDefault(TimeZone
the new default time zone
tz
)

Sets the TimeZone that is returned by the getDefault method.

public static synchronized void
setDefaultTimeZoneType(int
time zone type, either TIMEZONE_ICU or TIMEZONE_JDK.
type
)

Sets the default time zone type used by getTimeZone.

public static synchronized void
setICUDefault(TimeZone
the new default time zone
tz
)

Deprecated This API is ICU internal only.
Sets the TimeZone that is returned by the getDefault method.
public void
setID(String
the new time zone ID.
ID
)

Sets the time zone ID. This does not change any other data in the time zone object.

public abstract void
setRawOffset(int
the given base time zone offset to GMT.
offsetMillis
)

Sets the base time zone offset to GMT.

public abstract boolean

Returns:

true if this time zone uses daylight savings time, false, otherwise.

Note

The default implementation of ICU TimeZone uses the tz database, which supports historic rule changes, for system time zones. With the implementation, there are time zones that used daylight savings time in the past, but no longer used currently. For example, Asia/Tokyo has never used daylight savings time since 1951. Most clients would expect that this method to return false for such case. The default implementation of this method returns true when the time zone uses daylight savings time in the current (Gregorian) calendar year.

useDaylightTime
()

Queries if this time zone uses daylight savings time.

Inherited from java.lang.Object:
finalizegetClassnotifynotifyAlltoStringwaitwaitwait