Class TimeZone
- java.lang.Object
-
- com.ibm.icu.util.TimeZone
-
- Direct Known Subclasses:
BasicTimeZone
,JavaTimeZone
,TimeZone.ConstantZone
,TimeZoneJDK
public abstract class TimeZone extends java.lang.Object implements java.io.Serializable, java.lang.Cloneable, Freezable<TimeZone>
.TimeZone
represents a time zone offset, and also computes daylight savings.Typically, you get a
TimeZone
usinggetDefault()
which creates aTimeZone
based on the time zone where the program is running. For example, for a program running in Japan,getDefault
creates aTimeZone
object based on Japanese Standard Time.You can also get a
TimeZone
usinggetTimeZone(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 TimeTimeZone
object with:TimeZone tz = TimeZone.getTimeZone("America/Los_Angeles");
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 aTimeZone
. 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]
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 methodgetTimeZone
creates an instance of ICU's ownTimeZone
subclass by default. If you want to use the JDK implementation always, you can set the default time zone implementation type by the new methodsetDefaultTimeZoneType
. 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 propertycom.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 callingsetDefaultTimeZoneType
at runtime.- See Also:
Calendar
,GregorianCalendar
,SimpleTimeZone
, Serialized Form
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description private static class
TimeZone.ConstantZone
static class
TimeZone.SystemTimeZoneType
System time zone type constants used by filtering zones ingetAvailableIDs(SystemTimeZoneType, String, Integer)
-
Field Summary
Fields Modifier and Type Field Description private static TimeZone
defaultZone
The default time zone, or null if not set.static int
GENERIC_LOCATION
A style specifier forgetDisplayName()
indicating a long name derived from the timezone's fallback name, such as "United States (Los Angeles)."static TimeZone
GMT_ZONE
The immutable GMT (=UTC) time zone.(package private) static java.lang.String
GMT_ZONE_ID
The canonical ID for GMT(UTC) time zone.private java.lang.String
ID
The string identifier of thisTimeZone
.private static java.util.logging.Logger
LOGGER
Logger instance for this classstatic int
LONG
A style specifier forgetDisplayName()
indicating a long name, such as "Pacific Standard Time."static int
LONG_GENERIC
A style specifier forgetDisplayName()
indicating a long generic name, such as "Pacific Time."static int
LONG_GMT
A style specifier forgetDisplayName()
indicating a long name derived from the timezone's offset, such as "GMT-08:00."private static long
serialVersionUID
static int
SHORT
A style specifier forgetDisplayName()
indicating a short name, such as "PST."static int
SHORT_COMMONLY_USED
A style specifier forgetDisplayName()
indicating a short name derived from the timezone's short standard or daylight timezone name ignoring commonlyUsed, such as "PDT."static int
SHORT_GENERIC
A style specifier forgetDisplayName()
indicating a short generic name, such as "PT."static int
SHORT_GMT
A style specifier forgetDisplayName()
indicating a short name derived from the timezone's offset, such as "-0800."static int
TIMEZONE_ICU
A time zone implementation type indicating ICU's own TimeZone used bygetTimeZone
,setDefaultTimeZoneType
andgetDefaultTimeZoneType
.static int
TIMEZONE_JDK
A time zone implementation type indicating theTimeZone
used bygetTimeZone
,setDefaultTimeZoneType
andgetDefaultTimeZoneType
.private static int
TZ_IMPL
TimeZone implementation typeprivate static java.lang.String
TZIMPL_CONFIG_ICU
private static java.lang.String
TZIMPL_CONFIG_JDK
private static java.lang.String
TZIMPL_CONFIG_KEY
TimeZone implementation type initializationstatic TimeZone
UNKNOWN_ZONE
The immutable (frozen) "unknown" time zone.static java.lang.String
UNKNOWN_ZONE_ID
The time zone ID reserved for unknown time zone.
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods Modifier and Type Method Description private java.lang.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.java.lang.Object
clone()
Overrides clone.TimeZone
cloneAsThawed()
Provides for the clone operation.static int
countEquivalentIDs(java.lang.String id)
Returns the number of IDs in the equivalency group that includes the given ID.boolean
equals(java.lang.Object obj)
Overrides equals.static TimeZone
forLocaleOrDefault(java.util.Locale locale)
Deprecated.This API is ICU internal only.static TimeZone
forULocaleOrDefault(ULocale locale)
Deprecated.This API is ICU internal only.TimeZone
freeze()
Freezes the object.static java.lang.String[]
getAvailableIDs()
Return a new String array containing all system TimeZone IDs.static java.lang.String[]
getAvailableIDs(int rawOffset)
Return a new String array containing all system TimeZone IDs with the given raw offset from GMT.static java.util.Set<java.lang.String>
getAvailableIDs(TimeZone.SystemTimeZoneType zoneType, java.lang.String region, java.lang.Integer rawOffset)
Returns a set of time zone ID strings with the given filter conditions.static java.lang.String[]
getAvailableIDs(java.lang.String country)
Return a new String array containing all system TimeZone IDs associated with the given country.static java.lang.String
getCanonicalID(java.lang.String id)
Returns the canonical system time zone ID or the normalized custom time zone ID for the given time zone ID.static java.lang.String
getCanonicalID(java.lang.String id, boolean[] isSystemID)
Returns the canonical system time zone ID or the normalized custom time zone ID for the given time zone ID.static TimeZone
getDefault()
Gets the defaultTimeZone
for this host.static int
getDefaultTimeZoneType()
Returns the default time zone type currently used.java.lang.String
getDisplayName()
Returns a name of this time zone suitable for presentation to the user in the defaultDISPLAY
locale.java.lang.String
getDisplayName(boolean daylight, int style)
Returns a name of this time zone suitable for presentation to the user in the defaultDISPLAY
locale.java.lang.String
getDisplayName(boolean daylight, int style, ULocale locale)
Returns a name of this time zone suitable for presentation to the user in the specified locale.java.lang.String
getDisplayName(boolean daylight, int style, java.util.Locale locale)
Returns a name of this time zone suitable for presentation to the user in the specified locale.java.lang.String
getDisplayName(ULocale locale)
Returns a name of this time zone suitable for presentation to the user in the specified locale.java.lang.String
getDisplayName(java.util.Locale locale)
Returns a name of this time zone suitable for presentation to the user in the specified locale.int
getDSTSavings()
Returns the amount of time to be added to local standard time to get local wall clock time.static java.lang.String
getEquivalentID(java.lang.String id, int index)
Returns an ID in the equivalency group that includes the given ID.(package private) static BasicTimeZone
getFrozenICUTimeZone(java.lang.String id, boolean trySystem)
Returns a frozen ICU type TimeZone object given a time zone ID.static TimeZone
getFrozenTimeZone(java.lang.String ID)
Gets theTimeZone
for the given ID.static java.lang.String
getIanaID(java.lang.String id)
Returns the preferred time zone ID in the IANA database for the given time zone ID.java.lang.String
getID()
Gets the ID of this time zone.static java.lang.String
getIDForWindowsID(java.lang.String winid, java.lang.String region)
Converts a Windows time zone ID to an equivalent system time zone ID for a region.abstract int
getOffset(int era, int year, int month, int day, int dayOfWeek, int milliseconds)
Gets the time zone offset, for current date, modified in case of daylight savings.int
getOffset(long date)
Returns the offset of this time zone from UTC at the specified date.void
getOffset(long date, boolean local, int[] offsets)
Returns the time zone raw and GMT offset for the given moment in time.abstract int
getRawOffset()
Gets unmodified offset, NOT modified in case of daylight savings.static java.lang.String
getRegion(java.lang.String id)
Returns the region code associated with the given system time zone ID.static TimeZone
getTimeZone(java.lang.String ID)
Gets theTimeZone
for the given ID.static TimeZone
getTimeZone(java.lang.String ID, int type)
Gets theTimeZone
for the given ID and the timezone type.private static TimeZone
getTimeZone(java.lang.String id, int type, boolean frozen)
Gets theTimeZone
for the given ID and the timezone type.static java.lang.String
getTZDataVersion()
Returns the time zone data version currently used by ICU.static java.lang.String
getWindowsID(java.lang.String id)
Converts a system time zone ID to an equivalent Windows time zone ID.int
hashCode()
Overrides hashCode.boolean
hasSameRules(TimeZone other)
Returns true if this zone has the same rule and offset as another zone.abstract boolean
inDaylightTime(java.util.Date date)
Queries if the given date is in daylight savings time in this time zone.boolean
isFrozen()
Determines whether the object has been frozen or not.boolean
observesDaylightTime()
Queries if this time zone is in daylight saving time or will observe daylight saving time at any future time.static void
setDefault(TimeZone tz)
Sets theTimeZone
that is returned by thegetDefault
method.static void
setDefaultTimeZoneType(int type)
Sets the default time zone type used bygetTimeZone
.static void
setICUDefault(TimeZone tz)
Deprecated.This API is ICU internal only.void
setID(java.lang.String ID)
Sets the time zone ID.abstract void
setRawOffset(int offsetMillis)
Sets the base time zone offset to GMT.abstract boolean
useDaylightTime()
Queries if this time zone uses daylight savings time.
-
-
-
Field Detail
-
LOGGER
private static final java.util.logging.Logger LOGGER
Logger instance for this class
-
serialVersionUID
private static final long serialVersionUID
- See Also:
- Constant Field Values
-
TIMEZONE_ICU
public static final int TIMEZONE_ICU
A time zone implementation type indicating ICU's own TimeZone used bygetTimeZone
,setDefaultTimeZoneType
andgetDefaultTimeZoneType
.- See Also:
- Constant Field Values
-
TIMEZONE_JDK
public static final int TIMEZONE_JDK
A time zone implementation type indicating theTimeZone
used bygetTimeZone
,setDefaultTimeZoneType
andgetDefaultTimeZoneType
.- See Also:
- Constant Field Values
-
SHORT
public static final int SHORT
A style specifier forgetDisplayName()
indicating a short name, such as "PST."- See Also:
LONG
, Constant Field Values
-
LONG
public static final int LONG
A style specifier forgetDisplayName()
indicating a long name, such as "Pacific Standard Time."- See Also:
SHORT
, Constant Field Values
-
SHORT_GENERIC
public static final int SHORT_GENERIC
A style specifier forgetDisplayName()
indicating a short generic name, such as "PT."- See Also:
LONG_GENERIC
, Constant Field Values
-
LONG_GENERIC
public static final int LONG_GENERIC
A style specifier forgetDisplayName()
indicating a long generic name, such as "Pacific Time."- See Also:
SHORT_GENERIC
, Constant Field Values
-
SHORT_GMT
public static final int SHORT_GMT
A style specifier forgetDisplayName()
indicating a short name derived from the timezone's offset, such as "-0800."- See Also:
LONG_GMT
, Constant Field Values
-
LONG_GMT
public static final int LONG_GMT
A style specifier forgetDisplayName()
indicating a long name derived from the timezone's offset, such as "GMT-08:00."- See Also:
SHORT_GMT
, Constant Field Values
-
SHORT_COMMONLY_USED
public static final int SHORT_COMMONLY_USED
A style specifier forgetDisplayName()
indicating a short name derived from the timezone's short standard or daylight timezone name ignoring commonlyUsed, such as "PDT."- See Also:
- Constant Field Values
-
GENERIC_LOCATION
public static final int GENERIC_LOCATION
A style specifier forgetDisplayName()
indicating a long name derived from the timezone's fallback name, such as "United States (Los Angeles)."- See Also:
- Constant Field Values
-
UNKNOWN_ZONE_ID
public static final java.lang.String UNKNOWN_ZONE_ID
The time zone ID reserved for unknown time zone.- See Also:
getTimeZone(String)
, Constant Field Values
-
GMT_ZONE_ID
static final java.lang.String GMT_ZONE_ID
The canonical ID for GMT(UTC) time zone.- See Also:
- Constant Field Values
-
UNKNOWN_ZONE
public static final TimeZone UNKNOWN_ZONE
The immutable (frozen) "unknown" time zone. It behaves like the GMT/UTC time zone but has the UNKNOWN_ZONE_ID = "Etc/Unknown".getTimeZone(String)
returns a mutable clone of this time zone if the input ID is not recognized.- See Also:
UNKNOWN_ZONE_ID
,getTimeZone(String)
-
GMT_ZONE
public static final TimeZone GMT_ZONE
The immutable GMT (=UTC) time zone. Its ID is "Etc/GMT".
-
ID
private java.lang.String ID
The string identifier of thisTimeZone
. This is a programmatic identifier used internally to look upTimeZone
objects from the system table and also to map them to their localized display names.ID
values are unique in the system table but may not be for dynamically created zones.
-
defaultZone
private static volatile TimeZone defaultZone
The default time zone, or null if not set.
-
TZ_IMPL
private static int TZ_IMPL
TimeZone implementation type
-
TZIMPL_CONFIG_KEY
private static final java.lang.String TZIMPL_CONFIG_KEY
TimeZone implementation type initialization- See Also:
- Constant Field Values
-
TZIMPL_CONFIG_ICU
private static final java.lang.String TZIMPL_CONFIG_ICU
- See Also:
- Constant Field Values
-
TZIMPL_CONFIG_JDK
private static final java.lang.String TZIMPL_CONFIG_JDK
- See Also:
- Constant Field Values
-
-
Constructor Detail
-
TimeZone
public TimeZone()
Default constructor. (For invocation by subclass constructors, typically implicit.)
-
TimeZone
@Deprecated protected TimeZone(java.lang.String ID)
Deprecated.This API is ICU internal only.Constructing a TimeZone with the given time zone ID.- Parameters:
ID
- the time zone ID.
-
-
Method Detail
-
getOffset
public abstract int getOffset(int era, int year, int month, int day, int dayOfWeek, int milliseconds)
Gets the time zone offset, for current date, modified in case of daylight savings. This is the offset to add to UTC to get local time.- Parameters:
era
- the era of the given date.year
- the year in the given date.month
- the month in the given date. Month is 0-based. e.g., 0 for January.day
- the day-in-month of the given date.dayOfWeek
- the day-of-week of the given date.milliseconds
- the millis in day in standard local time.- Returns:
- the offset to add to GMT to get local time.
-
getOffset
public int getOffset(long date)
Returns the offset of this time zone from UTC at the specified date. If Daylight Saving Time is in effect at the specified date, the offset value is adjusted with the amount of daylight saving.- Parameters:
date
- the date represented in milliseconds since January 1, 1970 00:00:00 GMT- Returns:
- the amount of time in milliseconds to add to UTC to get local time.
- See Also:
Calendar.ZONE_OFFSET
,Calendar.DST_OFFSET
,getOffset(long, boolean, int[])
-
getOffset
public void getOffset(long date, boolean local, int[] offsets)
Returns the time zone raw and GMT offset for the given moment in time. Upon return, local-millis = GMT-millis + rawOffset + dstOffset. All computations are performed in the proleptic Gregorian calendar. The default implementation in the TimeZone class delegates to the 8-argument getOffset().- Parameters:
date
- 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 onlocal
.local
- if true,date
is local wall time; otherwise it is in GMT time.offsets
- 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 torawOffset
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.
-
setRawOffset
public abstract void setRawOffset(int offsetMillis)
Sets the base time zone offset to GMT. This is the offset to add to UTC to get local time.- Parameters:
offsetMillis
- the given base time zone offset to GMT.
-
getRawOffset
public abstract int getRawOffset()
Gets unmodified offset, NOT modified in case of daylight savings. This is the offset to add to UTC to get local time.- Returns:
- the unmodified offset to add to UTC to get local time.
-
getID
public java.lang.String getID()
Gets the ID of this time zone.- Returns:
- the ID of this time zone.
-
setID
public void setID(java.lang.String ID)
Sets the time zone ID. This does not change any other data in the time zone object.- Parameters:
ID
- the new time zone ID.
-
getDisplayName
public final java.lang.String getDisplayName()
Returns a name of this time zone suitable for presentation to the user in the defaultDISPLAY
locale. This method returns the long generic name. If the display name is not available for the locale, a fallback based on the country, city, or time zone id will be used.- Returns:
- the human-readable name of this time zone in the default locale.
- See Also:
ULocale.Category.DISPLAY
-
getDisplayName
public final java.lang.String getDisplayName(java.util.Locale locale)
Returns a name of this time zone suitable for presentation to the user in the specified locale. This method returns the long generic name. If the display name is not available for the locale, a fallback based on the country, city, or time zone id will be used.- Parameters:
locale
- the locale in which to supply the display name.- 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
public final java.lang.String getDisplayName(ULocale locale)
Returns a name of this time zone suitable for presentation to the user in the specified locale. This method returns the long name, not including daylight savings. If the display name is not available for the locale, a fallback based on the country, city, or time zone id will be used.- Parameters:
locale
- the ulocale in which to supply the display name.- 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
public final java.lang.String getDisplayName(boolean daylight, int style)
Returns a name of this time zone suitable for presentation to the user in the defaultDISPLAY
locale. If the display name is not available for the locale, then this method returns a string in the localized GMT offset format such asGMT[+-]HH:mm
.- Parameters:
daylight
- if true, return the daylight savings name.style
- the output style of the display name. Valid styles areSHORT
,LONG
,SHORT_GENERIC
,LONG_GENERIC
,SHORT_GMT
,LONG_GMT
,SHORT_COMMONLY_USED
orGENERIC_LOCATION
.- Returns:
- the human-readable name of this time zone in the default locale.
- See Also:
ULocale.Category.DISPLAY
-
getDisplayName
public java.lang.String getDisplayName(boolean daylight, int style, java.util.Locale locale)
Returns a name of this time zone suitable for presentation to the user in the specified locale. If the display name is not available for the locale, then this method returns a string in the localized GMT offset format such asGMT[+-]HH:mm
.- Parameters:
daylight
- if true, return the daylight savings name.style
- the output style of the display name. Valid styles areSHORT
,LONG
,SHORT_GENERIC
,LONG_GENERIC
,SHORT_GMT
,LONG_GMT
,SHORT_COMMONLY_USED
orGENERIC_LOCATION
.locale
- the locale in which to supply the display name.- 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.
- Throws:
java.lang.IllegalArgumentException
- style is invalid.
-
getDisplayName
public java.lang.String getDisplayName(boolean daylight, int style, ULocale locale)
Returns a name of this time zone suitable for presentation to the user in the specified locale. If the display name is not available for the locale, then this method returns a string in the localized GMT offset format such asGMT[+-]HH:mm
.- Parameters:
daylight
- if true, return the daylight savings name.style
- the output style of the display name. Valid styles areSHORT
,LONG
,SHORT_GENERIC
,LONG_GENERIC
,SHORT_GMT
,LONG_GMT
,SHORT_COMMONLY_USED
orGENERIC_LOCATION
.locale
- the locale in which to supply the display name.- 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.
- Throws:
java.lang.IllegalArgumentException
- style is invalid.
-
_getDisplayName
private java.lang.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.
-
getDSTSavings
public int getDSTSavings()
Returns the amount of time to be added to local standard time to get local wall clock time.The default implementation always returns 3600000 milliseconds (i.e., one hour) if this time zone observes Daylight Saving Time. Otherwise, 0 (zero) is returned.
If an underlying TimeZone implementation subclass supports historical Daylight Saving Time changes, this method returns the known latest daylight saving value.
- Returns:
- the amount of saving time in milliseconds
-
useDaylightTime
public abstract boolean useDaylightTime()
Queries if this time zone uses daylight savings time.- 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 returnstrue
when the time zone uses daylight savings time in the current (Gregorian) calendar year.
-
observesDaylightTime
public boolean observesDaylightTime()
Queries if this time zone is in daylight saving time or will observe daylight saving time at any future time.The default implementation in this class returns
true
ifuseDaylightTime()
orinDaylightTime(new Date())
returnstrue
.Note: This method was added for
TimeZone
compatibility support. TheTimeZone.useDaylightTime()
method only checks the last known rule(s), therefore it may return false even the zone observes daylight saving time currently.TimeZone
addedobservesDaylightTime()
to resolve the issue. In ICU,useDaylightTime()
works differently. The ICU implementation checks if the zone uses daylight saving time in the current calendar year. Therefore, it will never returnfalse
if daylight saving time is currently used.ICU's TimeZone subclass implementations override this method to support the same behavior with
TimeZone.observesDaylightTime()
. UnlikeuseDaylightTime()
, the implementation does not take past daylight saving time into account, so that this method may returnfalse
even whenuseDaylightTime()
returnstrue
.- Returns:
true
if this time zone is in daylight saving time or will observe daylight saving time at any future time.- See Also:
useDaylightTime()
-
inDaylightTime
public abstract boolean inDaylightTime(java.util.Date date)
Queries if the given date is in daylight savings time in this time zone.- Parameters:
date
- the given Date.- Returns:
- true if the given date is in daylight savings time, false, otherwise.
-
getTimeZone
public static TimeZone getTimeZone(java.lang.String ID)
Gets theTimeZone
for the given ID.- Parameters:
ID
- the ID for aTimeZone
, 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.- 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". - See Also:
UNKNOWN_ZONE
-
getFrozenTimeZone
public static TimeZone getFrozenTimeZone(java.lang.String ID)
Gets theTimeZone
for the given ID. The instance ofTimeZone
returned by this method is immutable. Any methods mutate the instance(setID(String)
,setRawOffset(int)
) will throwUnsupportedOperationException
upon its invocation.- Parameters:
ID
- the ID for aTimeZone
, 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.- Returns:
- the specified
TimeZone
, or the UNKNOWN_ZONE if the given ID cannot be understood. - See Also:
UNKNOWN_ZONE
-
getTimeZone
public static TimeZone getTimeZone(java.lang.String ID, int type)
Gets theTimeZone
for the given ID and the timezone type.- Parameters:
ID
- the ID for aTimeZone
, 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.type
- Time zone type, eitherTIMEZONE_ICU
orTIMEZONE_JDK
.- 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". - See Also:
UNKNOWN_ZONE
-
getTimeZone
private static TimeZone getTimeZone(java.lang.String id, int type, boolean frozen)
Gets theTimeZone
for the given ID and the timezone type.- Parameters:
id
- time zone IDtype
- time zone implementation type, TIMEZONE_JDK or TIMEZONE_ICUfrozen
- specify if the returned object can be frozen- Returns:
- the specified
TimeZone
or UNKNOWN_ZONE if the given ID cannot be understood.
-
getFrozenICUTimeZone
static BasicTimeZone getFrozenICUTimeZone(java.lang.String id, boolean trySystem)
Returns a frozen ICU type TimeZone object given a time zone ID.- Parameters:
id
- the time zone IDtrySystem
- if true tries the system time zones first otherwise skip to the custom time zones.- Returns:
- the frozen ICU TimeZone or null if one could not be created.
-
setDefaultTimeZoneType
public static void setDefaultTimeZoneType(int type)
Sets the default time zone type used bygetTimeZone
.- Parameters:
type
- time zone type, eitherTIMEZONE_ICU
orTIMEZONE_JDK
.
-
getDefaultTimeZoneType
public static int getDefaultTimeZoneType()
Returns the default time zone type currently used.- Returns:
- The default time zone type, either
TIMEZONE_ICU
orTIMEZONE_JDK
.
-
getAvailableIDs
public static java.util.Set<java.lang.String> getAvailableIDs(TimeZone.SystemTimeZoneType zoneType, java.lang.String region, java.lang.Integer rawOffset)
Returns a set of time zone ID strings with the given filter conditions.Note:A
Set
returned by this method is immutable.- Parameters:
zoneType
- The system time zone type.region
- The ISO 3166 two-letter country code or UN M.49 three-digit area code. When null, no filtering done by region.rawOffset
- An offset from GMT in milliseconds, ignoring the effect of daylight savings time, if any. When null, no filtering done by zone offset.- Returns:
- an immutable set of system time zone IDs.
- See Also:
TimeZone.SystemTimeZoneType
-
getAvailableIDs
public static java.lang.String[] getAvailableIDs(int rawOffset)
Return a new String array containing all system TimeZone IDs with the given raw offset from GMT. These IDs may be passed toget()
to construct the corresponding TimeZone object.- Parameters:
rawOffset
- the offset in milliseconds from GMT- Returns:
- an array of IDs for system TimeZones with the given raw offset. If there are none, return a zero-length array.
- See Also:
getAvailableIDs(SystemTimeZoneType, String, Integer)
-
getAvailableIDs
public static java.lang.String[] getAvailableIDs(java.lang.String country)
Return a new String array containing all system TimeZone IDs associated with the given country. These IDs may be passed toget()
to construct the corresponding TimeZone object.- Parameters:
country
- a two-letter ISO 3166 country code, ornull
to return zones not associated with any country- Returns:
- an array of IDs for system TimeZones in the given country. If there are none, return a zero-length array.
- See Also:
getAvailableIDs(SystemTimeZoneType, String, Integer)
-
getAvailableIDs
public static java.lang.String[] getAvailableIDs()
Return a new String array containing all system TimeZone IDs. These IDs (and only these IDs) may be passed toget()
to construct the corresponding TimeZone object.- Returns:
- an array of all system TimeZone IDs
- See Also:
getAvailableIDs(SystemTimeZoneType, String, Integer)
-
countEquivalentIDs
public static int countEquivalentIDs(java.lang.String id)
Returns the number of IDs in the equivalency group that includes the given ID. An equivalency group contains zones that have the same GMT offset and rules.The returned count includes the given ID; it is always >= 1 for valid IDs. The given ID must be a system time zone. If it is not, returns zero.
- Parameters:
id
- a system time zone ID- Returns:
- the number of zones in the equivalency group containing 'id', or zero if 'id' is not a valid system ID
- See Also:
getEquivalentID(java.lang.String, int)
-
getEquivalentID
public static java.lang.String getEquivalentID(java.lang.String id, int 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.The given index must be in the range 0..n-1, where n is the value returned by
countEquivalentIDs(id)
. For some value of 'index', the returned value will be equal to the given id. If the given id is not a valid system time zone, or if 'index' is out of range, then returns an empty string.- Parameters:
id
- a system time zone IDindex
- a value from 0 to n-1, where n is the value returned bycountEquivalentIDs(id)
- 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
- See Also:
countEquivalentIDs(java.lang.String)
-
forULocaleOrDefault
@Deprecated public static TimeZone forULocaleOrDefault(ULocale locale)
Deprecated.This API is ICU internal only.If the locale contains the timezone keyword, creates a copy of thatTimeZone
. Otherwise, create the defaultTimeZone
.- Parameters:
locale
- a locale which may contains 'timezone' keyword/value.- Returns:
- A
TimeZone
. Clients are responsible for deleting theTimeZone
object returned.
-
forLocaleOrDefault
@Deprecated public static TimeZone forLocaleOrDefault(java.util.Locale locale)
Deprecated.This API is ICU internal only.If the locale contains the timezone keyword, creates a copy of thatTimeZone
. Otherwise, create the defaultTimeZone
.- Parameters:
locale
- a locale which may contains 'timezone' keyword/value.- Returns:
- A
TimeZone
. Clients are responsible for deleting theTimeZone
object returned.
-
getDefault
public static TimeZone getDefault()
Gets the defaultTimeZone
for this host. The source of the defaultTimeZone
may vary with implementation.- Returns:
- a default
TimeZone
.
-
setDefault
public static void setDefault(TimeZone tz)
Sets theTimeZone
that is returned by thegetDefault
method. This method also sets a Java TimeZone equivalent to the inputtz
as the JVM's default time zone if not null. Iftz
is null, nextgetDefault()
method invocation will reset the default time zone synchronized with the JVM's default at that time.- Parameters:
tz
- the new default time zone
-
setICUDefault
@Deprecated public static void setICUDefault(TimeZone tz)
Deprecated.This API is ICU internal only.Sets theTimeZone
that is returned by thegetDefault
method. Iftz
is null, nextgetDefault()
method invocation will reset the default time zone synchronized with the JVM's default at that time. UnlikesetDefault(TimeZone)
, this method does not change the JVM's default time zone.- Parameters:
tz
- the new default time zone
-
hasSameRules
public boolean hasSameRules(TimeZone other)
Returns true if this zone has the same rule and offset as another zone. That is, if this zone differs only in ID, if at all. Returns false if the other zone is null.- Parameters:
other
- theTimeZone
object to be compared with- Returns:
- true if the other zone is not null and is the same as this one, with the possible exception of the ID
-
clone
public java.lang.Object clone()
Overrides clone.- Overrides:
clone
in classjava.lang.Object
-
equals
public boolean equals(java.lang.Object obj)
Overrides equals.- Overrides:
equals
in classjava.lang.Object
- Returns:
true
if this object is the same as the obj argument;false
otherwise.
-
hashCode
public int hashCode()
Overrides hashCode.- Overrides:
hashCode
in classjava.lang.Object
- Returns:
- a hash code value for this object.
-
getTZDataVersion
public static java.lang.String getTZDataVersion()
Returns the time zone data version currently used by ICU.- Returns:
- the version string, such as "2007f"
- Throws:
java.util.MissingResourceException
- if ICU time zone resource bundle is missing or the version information is not available.
-
getCanonicalID
public static java.lang.String getCanonicalID(java.lang.String id)
Returns the canonical system time zone ID or the normalized custom time zone ID for the given time zone ID.- Parameters:
id
- The input time zone ID to be canonicalized.- 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
public static java.lang.String getCanonicalID(java.lang.String id, boolean[] isSystemID)
Returns the canonical system time zone ID or the normalized custom time zone ID for the given time zone ID.- Parameters:
id
- The input time zone ID to be canonicalized.isSystemID
- When non-null boolean array is specified and the given ID is a known system time zone ID, true is set toisSystemID[0]
- 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.
-
getIanaID
public static java.lang.String getIanaID(java.lang.String id)
Returns the preferred time zone ID in the IANA database for the given time zone ID. There are two types of preferred IDs. The first type is the one defined in zone.tab file, such as "America/Los_Angeles". The second types is the one defined for zones not associated with a specific region, but not defined with "Link" syntax, such as "Etc/GMT+10".Note: For most of system time zone IDs, this method returns an ID same as
getCanonicalID(String)
.getCanonicalID(String)
is based on canonical time zone IDs defined in Unicode CLDR. These canonical time zone IDs in CLDR were based on very old version of the time zone database. In the IANA time zone database, some IDs were updated since then. This API returns a newer time zone ID. For example, CLDR defines "Asia/Calcutta" as the canonical time zone ID. This method returns "Asia/Kolkata" instead."Etc/Unknown" is a special time zone ID defined by CLDR. There are no corresponding zones in the IANA time zone database. when the input is "Etc/Unknown", this method returns "Etc/Unknown", but it really means no mappings available. Caller of this method should interpret "Etc/Unknown" as an error.
- Parameters:
id
- The input time zone ID.- Returns:
- The preferred time zone ID in the IANA time zone database, or
UNKNOWN_ZONE_ID
if the input ID is not a system ID. - See Also:
getCanonicalID(String)
-
getRegion
public static java.lang.String getRegion(java.lang.String id)
Returns the region code associated with the given system time zone ID. The region code is either ISO 3166 2-letter country code or UN M.49 3-digit area code. When the time zone is not associated with a specific location, for example - "Etc/UTC", "EST5EDT", then this method returns "001" (UN M.49 area code for World).- Parameters:
id
- the system time zone ID.- Returns:
- the region code associated with the given system time zone ID.
- Throws:
java.lang.IllegalArgumentException
- ifid
is not a known system ID.- See Also:
getAvailableIDs(String)
-
getWindowsID
public static java.lang.String getWindowsID(java.lang.String id)
Converts a system time zone ID to an equivalent Windows time zone ID. For example, Windows time zone ID "Pacific Standard Time" is returned for input "America/Los_Angeles".There are system time zones that cannot be mapped to Windows zones. When the input system time zone ID is unknown or unmappable to a Windows time zone, then this method returns
null
.This implementation utilizes Zone-Tzid mapping data. The mapping data is updated time to time. To get the latest changes, please read the ICU user guide section Updating the Time Zone Data.
- Parameters:
id
- A system time zone ID- Returns:
- A Windows time zone ID mapped from the input system time zone ID,
or
null
when the input ID is unknown or unmappable. - See Also:
getIDForWindowsID(String, String)
-
getIDForWindowsID
public static java.lang.String getIDForWindowsID(java.lang.String winid, java.lang.String region)
Converts a Windows time zone ID to an equivalent system time zone ID for a region. For example, system time zone ID "America/Los_Angeles" is returned for input Windows ID "Pacific Standard Time" and region "US" (ornull
), "America/Vancouver" is returned for the same Windows ID "Pacific Standard Time" and region "CA".Not all Windows time zones can be mapped to system time zones. When the input Windows time zone ID is unknown or unmappable to a system time zone, then this method returns
null
.This implementation utilizes Zone-Tzid mapping data. The mapping data is updated time to time. To get the latest changes, please read the ICU user guide section Updating the Time Zone Data.
- Parameters:
winid
- A Windows time zone IDregion
- A region code, ornull
if no regional preference.- Returns:
- A system time zone ID mapped from the input Windows time zone ID,
or
null
when the input ID is unknown or unmappable. - See Also:
getWindowsID(String)
-
isFrozen
public boolean isFrozen()
Determines whether the object has been frozen or not.
-
freeze
public TimeZone freeze()
Freezes the object.
-
cloneAsThawed
public TimeZone cloneAsThawed()
Provides for the clone operation. Any clone is initially unfrozen.- Specified by:
cloneAsThawed
in interfaceFreezable<TimeZone>
-
-