Class VTimeZone
- All Implemented Interfaces:
Freezable<TimeZone>
,Serializable
,Cloneable
VTimeZone
is a class implementing RFC2445 VTIMEZONE. You can create a
VTimeZone
instance from a time zone ID supported by TimeZone
.
With the VTimeZone
instance created from the ID, you can write out the rule
in RFC2445 VTIMEZONE format. Also, you can create a VTimeZone
instance
from RFC2445 VTIMEZONE data stream, which allows you to calculate time
zone offset by the rules defined by the data.Note: The consumer of this class reading or writing VTIMEZONE data is responsible to decode or encode Non-ASCII text. Methods reading/writing VTIMEZONE data in this class do nothing with MIME encoding.
- See Also:
-
Nested Class Summary
Nested classes/interfaces inherited from class com.ibm.icu.util.BasicTimeZone
BasicTimeZone.LocalOption
Nested classes/interfaces inherited from class com.ibm.icu.util.TimeZone
TimeZone.SystemTimeZoneType
-
Field Summary
Fields inherited from class com.ibm.icu.util.BasicTimeZone
FORMER_LATTER_MASK, LOCAL_DST, LOCAL_FORMER, LOCAL_LATTER, LOCAL_STD, STD_DST_MASK
Fields inherited from class com.ibm.icu.util.TimeZone
GENERIC_LOCATION, GMT_ZONE, LONG, LONG_GENERIC, LONG_GMT, SHORT, SHORT_COMMONLY_USED, SHORT_GENERIC, SHORT_GMT, TIMEZONE_ICU, TIMEZONE_JDK, UNKNOWN_ZONE, UNKNOWN_ZONE_ID
-
Method Summary
Modifier and TypeMethodDescriptionclone()
Overrides clone.Provides for the clone operation.static VTimeZone
Create aVTimeZone
instance by RFC2445 VTIMEZONE data.static VTimeZone
Create aVTimeZone
instance by the time zone ID.freeze()
Freezes the object.Gets the RFC2445 LAST-MODIFIED property value.getNextTransition
(long base, boolean inclusive) Returns the first time zone transition after the base time.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.void
getOffset
(long date, boolean local, int[] offsets) Returns the time zone raw and GMT offset for the given moment in time.void
getOffsetFromLocal
(long date, BasicTimeZone.LocalOption nonExistingTimeOpt, BasicTimeZone.LocalOption duplicatedTimeOpt, int[] offsets) Returns time zone offsets from local wall time.getPreviousTransition
(long base, boolean inclusive) Returns the last time zone transition before the base time.int
Gets unmodified offset, NOT modified in case of daylight savings.Returns the array ofTimeZoneRule
which represents the rule of this time zone object.getTimeZoneRules
(long start) Returns the array ofTimeZoneRule
which represents the rule of this time zone object since the specified start time.getTZURL()
Gets the RFC2445 TZURL property value.boolean
hasEquivalentTransitions
(TimeZone other, long start, long end) Checks if the time zone has equivalent transitions in the time range.boolean
hasSameRules
(TimeZone other) Returns true if this zone has the same rule and offset as another zone.boolean
inDaylightTime
(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
Queries if this time zone is in daylight saving time or will observe daylight saving time at any future time.void
setLastModified
(Date date) Sets the date used for RFC2445 LAST-MODIFIED property value.void
setRawOffset
(int offsetMillis) Sets the base time zone offset to GMT.void
Sets the RFC2445 TZURL property value.boolean
Queries if this time zone uses daylight savings time.void
Writes RFC2445 VTIMEZONE data for this time zonevoid
Writes RFC2445 VTIMEZONE data applicable for dates after the specified start time.void
writeSimple
(Writer writer, long time) Writes RFC2445 VTIMEZONE data applicable near the specified date.Methods inherited from class com.ibm.icu.util.BasicTimeZone
getLocalOptionValue, getSimpleTimeZoneRulesNear, hasEquivalentTransitions
Methods inherited from class com.ibm.icu.util.TimeZone
countEquivalentIDs, equals, forLocaleOrDefault, forULocaleOrDefault, getAvailableIDs, getAvailableIDs, getAvailableIDs, getAvailableIDs, getCanonicalID, getCanonicalID, getDefault, getDefaultTimeZoneType, getDisplayName, getDisplayName, getDisplayName, getDisplayName, getDisplayName, getDisplayName, getDSTSavings, getEquivalentID, getFrozenTimeZone, getID, getIDForWindowsID, getOffset, getRegion, getTimeZone, getTimeZone, getTZDataVersion, getWindowsID, hashCode, setDefault, setDefaultTimeZoneType, setICUDefault, setID
-
Method Details
-
create
Create aVTimeZone
instance by the time zone ID.- Parameters:
tzid
- The time zone ID, such as America/New_York- Returns:
- A
VTimeZone
initialized by the time zone ID, or null when the ID is unknown.
-
create
Create aVTimeZone
instance by RFC2445 VTIMEZONE data.- Parameters:
reader
- The Reader for VTIMEZONE data input stream- Returns:
- A
VTimeZone
initialized by the VTIMEZONE data or null if failed to load the rule from the VTIMEZONE data.
-
getOffset
public 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.- Specified by:
getOffset
in classTimeZone
- 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 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().- Overrides:
getOffset
in classTimeZone
- 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.
-
getOffsetFromLocal
public void getOffsetFromLocal(long date, BasicTimeZone.LocalOption nonExistingTimeOpt, BasicTimeZone.LocalOption duplicatedTimeOpt, int[] offsets) Returns time zone offsets from local wall time.- Overrides:
getOffsetFromLocal
in classBasicTimeZone
-
getRawOffset
public int getRawOffset()Gets unmodified offset, NOT modified in case of daylight savings. This is the offset to add to UTC to get local time.- Specified by:
getRawOffset
in classTimeZone
- Returns:
- the unmodified offset to add to UTC to get local time.
-
inDaylightTime
Queries if the given date is in daylight savings time in this time zone.- Specified by:
inDaylightTime
in classTimeZone
- Parameters:
date
- the given Date.- Returns:
- true if the given date is in daylight savings time, false, otherwise.
-
setRawOffset
public void setRawOffset(int offsetMillis) Sets the base time zone offset to GMT. This is the offset to add to UTC to get local time.- Specified by:
setRawOffset
in classTimeZone
- Parameters:
offsetMillis
- the given base time zone offset to GMT.
-
useDaylightTime
public boolean useDaylightTime()Queries if this time zone uses daylight savings time.- Specified by:
useDaylightTime
in classTimeZone
- 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
ifTimeZone.useDaylightTime()
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,TimeZone.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()
. UnlikeTimeZone.useDaylightTime()
, the implementation does not take past daylight saving time into account, so that this method may returnfalse
even whenTimeZone.useDaylightTime()
returnstrue
.- Overrides:
observesDaylightTime
in classTimeZone
- Returns:
true
if this time zone is in daylight saving time or will observe daylight saving time at any future time.- See Also:
-
hasSameRules
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.- Overrides:
hasSameRules
in classTimeZone
- 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
-
getTZURL
Gets the RFC2445 TZURL property value. When aVTimeZone
instance was created from VTIMEZONE data, the value is set by the TZURL property value in the data. Otherwise, the initial value is null.- Returns:
- The RFC2445 TZURL property value
-
setTZURL
Sets the RFC2445 TZURL property value.- Parameters:
url
- The TZURL property value.
-
getLastModified
Gets the RFC2445 LAST-MODIFIED property value. When aVTimeZone
instance was created from VTIMEZONE data, the value is set by the LAST-MODIFIED property value in the data. Otherwise, the initial value is null.- Returns:
- The Date represents the RFC2445 LAST-MODIFIED date.
-
setLastModified
Sets the date used for RFC2445 LAST-MODIFIED property value.- Parameters:
date
- TheDate
object represents the date for RFC2445 LAST-MODIFIED property value.
-
write
Writes RFC2445 VTIMEZONE data for this time zone- Parameters:
writer
- AWriter
used for the output- Throws:
IOException
- If there were problems creating a buffered writer or writing to it.
-
write
Writes RFC2445 VTIMEZONE data applicable for dates after the specified start time.- Parameters:
writer
- TheWriter
used for the outputstart
- The start time- Throws:
IOException
- If there were problems reading and writing to the writer.
-
writeSimple
Writes RFC2445 VTIMEZONE data applicable near the specified date. Some common iCalendar implementations can only handle a single time zone property or a pair of standard and daylight time properties using BYDAY rule with day of week (such as BYDAY=1SUN). This method produce the VTIMEZONE data which can be handled these implementations. The rules produced by this method can be used only for calculating time zone offset around the specified date.- Parameters:
writer
- TheWriter
used for the outputtime
- The date- Throws:
IOException
- If there were problems reading or writing to the writer.
-
getNextTransition
Returns the first time zone transition after the base time.Example code:invalid input: '{@'.jcite com.ibm.icu.samples.util.timezone.BasicTimeZoneExample:---getNextTransitionExample}
- Specified by:
getNextTransition
in classBasicTimeZone
- Parameters:
base
- The base time.inclusive
- Whether the base time is inclusive or not.- Returns:
- A
Date
holding the first time zone transition time after the given base time, or null if no time zone transitions are available after the base time.
-
getPreviousTransition
Returns the last time zone transition before the base time.Example code:invalid input: '{@'.jcite com.ibm.icu.samples.util.timezone.BasicTimeZoneExample:---getPreviousTransitionExample}
- Specified by:
getPreviousTransition
in classBasicTimeZone
- Parameters:
base
- The base time.inclusive
- Whether the base time is inclusive or not.- Returns:
- A
Date
holding the last time zone transition time before the given base time, or null if no time zone transitions are available before the base time.
-
hasEquivalentTransitions
Checks if the time zone has equivalent transitions in the time range. This method returns true when all of transition times, from/to standard offsets and DST savings used by this time zone match the other in the time range.Example code:invalid input: '{@'.jcite com.ibm.icu.samples.util.timezone.BasicTimeZoneExample:---hasEquivalentTransitionsExample}
- Overrides:
hasEquivalentTransitions
in classBasicTimeZone
- Parameters:
other
- The instance ofTimeZone
start
- The start time of the evaluated time range (inclusive)end
- The end time of the evaluated time range (inclusive)- Returns:
- true if the other time zone has the equivalent transitions in the
time range. When tz is not a
BasicTimeZone
, this method returns false.
-
getTimeZoneRules
Returns the array ofTimeZoneRule
which represents the rule of this time zone object. The first element in the result array will be theInitialTimeZoneRule
instance for the initial rule. The rest will be eitherAnnualTimeZoneRule
orTimeArrayTimeZoneRule
instances representing transitions.- Specified by:
getTimeZoneRules
in classBasicTimeZone
- Returns:
- The array of
TimeZoneRule
which represents this time zone.
-
getTimeZoneRules
Returns the array ofTimeZoneRule
which represents the rule of this time zone object since the specified start time. The first element in the result array will be theInitialTimeZoneRule
instance for the initial rule. The rest will be eitherAnnualTimeZoneRule
orTimeArrayTimeZoneRule
instances representing transitions.Example code:invalid input: '{@'.jcite com.ibm.icu.samples.util.timezone.BasicTimeZoneExample:---getTimeZoneRulesExample}
- Overrides:
getTimeZoneRules
in classBasicTimeZone
- Parameters:
start
- The start time (inclusive).- Returns:
- The array of
TimeZoneRule
which represents this time zone since the start time.
-
clone
Overrides clone. -
isFrozen
public boolean isFrozen()Determines whether the object has been frozen or not. -
freeze
Freezes the object. -
cloneAsThawed
Provides for the clone operation. Any clone is initially unfrozen.- Specified by:
cloneAsThawed
in interfaceFreezable<TimeZone>
- Overrides:
cloneAsThawed
in classTimeZone
-