com.ibm.icu.util

Class VTimeZone

java.lang.Object

com.ibm.icu.util.TimeZone

com.ibm.icu.util.BasicTimeZone

com.ibm.icu.util.VTimeZone

All Implemented Interfaces:

Freezable<TimeZone>, Serializable, Cloneable

public class VTimeZone
extends BasicTimeZone

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:

Serialized Form

Status:

Stable ICU 3.8.

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 Type	Method and Description
Object	clone() Overrides clone.
TimeZone	cloneAsThawed() Provides for the clone operation.
static VTimeZone	create(Reader reader) Create a VTimeZone instance by RFC2445 VTIMEZONE data.
static VTimeZone	create(String tzid) Create a VTimeZone instance by the time zone ID.
TimeZone	freeze() Freezes the object.
Date	getLastModified() Gets the RFC2445 LAST-MODIFIED property value.
TimeZoneTransition	getNextTransition(long base, boolean inclusive) [icu] 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) [icu] Returns time zone offsets from local wall time.
TimeZoneTransition	getPreviousTransition(long base, boolean inclusive) [icu] Returns the last time zone transition before the base time.
int	getRawOffset() Gets unmodified offset, NOT modified in case of daylight savings.
TimeZoneRule[]	getTimeZoneRules() [icu] Returns the array of TimeZoneRule which represents the rule of this time zone object.
TimeZoneRule[]	getTimeZoneRules(long start) [icu] Returns the array of TimeZoneRule which represents the rule of this time zone object since the specified start time.
String	getTZURL() Gets the RFC2445 TZURL property value.
boolean	hasEquivalentTransitions(TimeZone other, long start, long end) [icu] 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	observesDaylightTime() 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	setTZURL(String url) Sets the RFC2445 TZURL property value.
boolean	useDaylightTime() Queries if this time zone uses daylight savings time.
void	write(Writer writer) Writes RFC2445 VTIMEZONE data for this time zone
void	write(Writer writer, long start) 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, getIanaID, getID, getIDForWindowsID, getOffset, getRegion, getTimeZone, getTimeZone, getTZDataVersion, getWindowsID, hashCode, setDefault, setDefaultTimeZoneType, setICUDefault, setID

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Method Detail

create

public static VTimeZone create(String tzid)

Create a VTimeZone 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.

Status:

Stable ICU 3.8.

create

public static VTimeZone create(Reader reader)

Create a VTimeZone 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.

Status:

Stable ICU 3.8.

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 class TimeZone

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.

Status:

Stable ICU 3.8.

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 class TimeZone

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 on local.

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 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.

Status:

Stable ICU 3.8.

getOffsetFromLocal

public void getOffsetFromLocal(long date,
                               BasicTimeZone.LocalOption nonExistingTimeOpt,
                               BasicTimeZone.LocalOption duplicatedTimeOpt,
                               int[] offsets)

[icu] Returns time zone offsets from local wall time.

Overrides:

getOffsetFromLocal in class BasicTimeZone

Status:

Stable ICU 69.

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 class TimeZone

Returns:

the unmodified offset to add to UTC to get local time.

Status:

Stable ICU 3.8.

inDaylightTime

public boolean inDaylightTime(Date date)

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

Specified by:

inDaylightTime in class TimeZone

Parameters:

date - the given Date.

Returns:

true if the given date is in daylight savings time, false, otherwise.

Status:

Stable ICU 3.8.

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 class TimeZone

Parameters:

offsetMillis - the given base time zone offset to GMT.

Status:

Stable ICU 3.8.

useDaylightTime

public boolean useDaylightTime()

Queries if this time zone uses daylight savings time.

Specified by:

useDaylightTime in class TimeZone

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.

Status:

Stable ICU 3.8.

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 if TimeZone.useDaylightTime() or inDaylightTime(new Date()) returns true.

Note: This method was added for TimeZone compatibility support. The TimeZone.useDaylightTime() method only checks the last known rule(s), therefore it may return false even the zone observes daylight saving time currently. TimeZone added observesDaylightTime() 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 return false if daylight saving time is currently used.

ICU's TimeZone subclass implementations override this method to support the same behavior with TimeZone.observesDaylightTime(). Unlike TimeZone.useDaylightTime(), the implementation does not take past daylight saving time into account, so that this method may return false even when TimeZone.useDaylightTime() returns true.

Overrides:

observesDaylightTime in class TimeZone

Returns:

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

See Also:

TimeZone.useDaylightTime()

Status:

Stable ICU 49.

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.

Overrides:

hasSameRules in class TimeZone

Parameters:

other - the TimeZone 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

Status:

Stable ICU 3.8.

getTZURL

public String getTZURL()

Gets the RFC2445 TZURL property value. When a VTimeZone 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

Status:

Stable ICU 3.8.

setTZURL

public void setTZURL(String url)

Sets the RFC2445 TZURL property value.

Parameters:

url - The TZURL property value.

Status:

Stable ICU 3.8.

getLastModified

public Date getLastModified()

Gets the RFC2445 LAST-MODIFIED property value. When a VTimeZone 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.

Status:

Stable ICU 3.8.

setLastModified

public void setLastModified(Date date)

Sets the date used for RFC2445 LAST-MODIFIED property value.

Parameters:

date - The Date object represents the date for RFC2445 LAST-MODIFIED property value.

Status:

Stable ICU 3.8.

write

public void write(Writer writer)
           throws IOException

Writes RFC2445 VTIMEZONE data for this time zone

Parameters:

writer - A Writer used for the output

Throws:

IOException - If there were problems creating a buffered writer or writing to it.

Status:

Stable ICU 3.8.

write

public void write(Writer writer,
                  long start)
           throws IOException

Writes RFC2445 VTIMEZONE data applicable for dates after the specified start time.

Parameters:

writer - The Writer used for the output

start - The start time

Throws:

IOException - If there were problems reading and writing to the writer.

Status:

Stable ICU 3.8.

writeSimple

public void writeSimple(Writer writer,
                        long time)
                 throws IOException

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 - The Writer used for the output

time - The date

Throws:

IOException - If there were problems reading or writing to the writer.

Status:

Stable ICU 3.8.

getNextTransition

public TimeZoneTransition getNextTransition(long base,
                                            boolean inclusive)

[icu] Returns the first time zone transition after the base time.

Example code:

System.out.println("### Iterates time zone transitions in America/Los_Angeles starting 2005-01-01 and forward");

// A TimeZone instance created by getTimeZone with TIMEZONE_ICU is always a BasicTimeZone
BasicTimeZone btz = (BasicTimeZone)TimeZone.getTimeZone("America/Los_Angeles", TimeZone.TIMEZONE_ICU);

// Date format for the wall time
SimpleDateFormat wallTimeFmt = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss z", ULocale.US);
wallTimeFmt.setTimeZone(btz);

long start = 1104537600000L;    // 2005-01-01 0:00 UTC
for (int i = 0; i < 5; i++) {   // Up to 5 transitions
    TimeZoneTransition trans = btz.getNextTransition(start, false /* not including start time */);

    // Display the transition time and offset information
    long transTime = trans.getTime();
    System.out.println(wallTimeFmt.format(new Date(transTime - 1)) + " -> " + wallTimeFmt.format(new Date(transTime)));
    System.out.println(" - Before (Offset/Save): " + trans.getFrom().getRawOffset() + "/" + trans.getFrom().getDSTSavings());
    System.out.println(" - After  (Offset/Save): " + trans.getTo().getRawOffset() + "/" + trans.getTo().getDSTSavings());

    // Update start time for next transition
    start = transTime;
}

Specified by:

getNextTransition in class BasicTimeZone

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.

Status:

Stable ICU 3.8.

getPreviousTransition

public TimeZoneTransition getPreviousTransition(long base,
                                                boolean inclusive)

[icu] Returns the last time zone transition before the base time.

Example code:

System.out.println("### Iterates time zone transitions in America/Los_Angeles starting 2010-01-01 and backward");

// A TimeZone instance created by getTimeZone with TIMEZONE_ICU is always a BasicTimeZone
BasicTimeZone btz = (BasicTimeZone)TimeZone.getTimeZone("America/Los_Angeles", TimeZone.TIMEZONE_ICU);

// Date format for the wall time
SimpleDateFormat wallTimeFmt = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss z", ULocale.US);
wallTimeFmt.setTimeZone(btz);

long start = 1262304000000L;    // 2010-01-01 0:00 UTC
for (int i = 0; i < 5; i++) {   // Up to 5 transitions
    TimeZoneTransition trans = btz.getPreviousTransition(start, false /* not including start time */);

    // Display the transition time and offset information
    long transTime = trans.getTime();
    System.out.println(wallTimeFmt.format(new Date(transTime - 1)) + " -> " + wallTimeFmt.format(new Date(transTime)));
    System.out.println(" - Before (Offset/Save): " + trans.getFrom().getRawOffset() + "/" + trans.getFrom().getDSTSavings());
    System.out.println(" - After  (Offset/Save): " + trans.getTo().getRawOffset() + "/" + trans.getTo().getDSTSavings());

    // Update start time for next transition
    start = transTime;
}

Specified by:

getPreviousTransition in class BasicTimeZone

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.

Status:

Stable ICU 3.8.

hasEquivalentTransitions

public boolean hasEquivalentTransitions(TimeZone other,
                                        long start,
                                        long end)

[icu] 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:

System.out.println("### Compare America/New_York and America/Detroit since year 1970");

// A TimeZone instance created by getTimeZone with TIMEZONE_ICU is always a BasicTimeZone
BasicTimeZone tzNewYork = (BasicTimeZone)TimeZone.getTimeZone("America/New_York", TimeZone.TIMEZONE_ICU);
BasicTimeZone tzDetroit = (BasicTimeZone)TimeZone.getTimeZone("America/Detroit", TimeZone.TIMEZONE_ICU);

GregorianCalendar cal = new GregorianCalendar(TimeZone.getTimeZone("Etc/GMT"));

// Compare these time zones every 10 years since year 1970 up to year 2009
for (int startYear = 1970; startYear <= 2000; startYear += 10) {
    long start, end;

    cal.set(startYear, Calendar.JANUARY, 1, 0, 0, 0);
    cal.set(Calendar.MILLISECOND, 0);
    start = cal.getTimeInMillis();

    // Set the end time to the end of startYear + 9
    int endYear = startYear + 9;
    cal.set(endYear + 1, Calendar.JANUARY, 1, 0, 0, 0);
    end = cal.getTimeInMillis() - 1;

    // Check if these two zones have equivalent time zone transitions for the given time range
    boolean isEquivalent = tzNewYork.hasEquivalentTransitions(tzDetroit, start, end);
    System.out.println(startYear + "-" + endYear + ": " + isEquivalent);
}

Overrides:

hasEquivalentTransitions in class BasicTimeZone

Parameters:

other - The instance of TimeZone

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.

Status:

Stable ICU 3.8.

getTimeZoneRules

public TimeZoneRule[] getTimeZoneRules()

[icu] Returns the array of TimeZoneRule which represents the rule of this time zone object. The first element in the result array will be the InitialTimeZoneRule instance for the initial rule. The rest will be either AnnualTimeZoneRule or TimeArrayTimeZoneRule instances representing transitions.

Specified by:

getTimeZoneRules in class BasicTimeZone

Returns:

The array of TimeZoneRule which represents this time zone.

Status:

Stable ICU 3.8.

getTimeZoneRules

public TimeZoneRule[] getTimeZoneRules(long start)

[icu] Returns the array of TimeZoneRule which represents the rule of this time zone object since the specified start time. The first element in the result array will be the InitialTimeZoneRule instance for the initial rule. The rest will be either AnnualTimeZoneRule or TimeArrayTimeZoneRule instances representing transitions.

Example code:

System.out.println("### Extracts time zone rules used by America/Los_Angeles since year 2005");

// A TimeZone instance created by getTimeZone with TIMEZONE_ICU is always a BasicTimeZone
BasicTimeZone btz = (BasicTimeZone)TimeZone.getTimeZone("America/Los_Angeles", TimeZone.TIMEZONE_ICU);
long since = 1104537600000L;    // 2005-01-01 0:00 UTC
TimeZoneRule[] rules = btz.getTimeZoneRules(since);
System.out.println("Rule(initial): " + rules[0]);
for (int i = 1; i < rules.length; i++) {
    System.out.println("Rule: " + rules[i]);
}

Overrides:

getTimeZoneRules in class BasicTimeZone

Parameters:

start - The start time (inclusive).

Returns:

The array of TimeZoneRule which represents this time zone since the start time.

Status:

Stable ICU 3.8.

clone

public Object clone()

Overrides clone.

Overrides:

clone in class TimeZone

Status:

Stable ICU 3.8.

isFrozen

public boolean isFrozen()

Determines whether the object has been frozen or not.

Specified by:

isFrozen in interface Freezable<TimeZone>

Overrides:

isFrozen in class TimeZone

Status:

Stable ICU 49.

freeze

public TimeZone freeze()

Freezes the object.

Specified by:

freeze in interface Freezable<TimeZone>

Overrides:

freeze in class TimeZone

Returns:

the object itself.

Status:

Stable ICU 49.

cloneAsThawed

public TimeZone cloneAsThawed()

Provides for the clone operation. Any clone is initially unfrozen.

Specified by:

cloneAsThawed in interface Freezable<TimeZone>

Overrides:

cloneAsThawed in class TimeZone

Status:

Stable ICU 49.