RuleBasedTimeZone (ICU4J 56.2)

java.lang.Object
- com.ibm.icu.util.TimeZone
- - com.ibm.icu.util.BasicTimeZone
  - - com.ibm.icu.util.RuleBasedTimeZone

All Implemented Interfaces:

Freezable<TimeZone>, Serializable, Cloneable
```
public class RuleBasedTimeZone
extends BasicTimeZone
```
RuleBasedTimeZone is a concrete subclass of TimeZone that allows users to define custom historic time transition rules.

See Also:
TimeZoneRule, Serialized Form
Status:
Stable ICU 3.8.

Nested Class Summary
- 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

Constructor Summary

Constructors
Constructor and Description
`RuleBasedTimeZone(String id, InitialTimeZoneRule initialRule)` Constructs a `RuleBasedTimeZone` object with the ID and the `InitialTimeZoneRule`

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`addTransitionRule(TimeZoneRule rule)` Adds the `TimeZoneRule` which represents time transitions.
`Object`	`clone()` Overrides clone.
`TimeZone`	`cloneAsThawed()` Provides for the clone operation.
`TimeZone`	`freeze()` Freezes the object.
`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 time, boolean local, int[] offsets)` Returns the time zone raw and GMT offset for the given moment in time.
`void`	`getOffsetFromLocal(long date, int nonExistingTimeOpt, int duplicatedTimeOpt, int[] offsets)` Deprecated. This API is ICU internal only.
`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.
`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`	`setRawOffset(int offsetMillis)` Sets the base time zone offset to GMT.
`boolean`	`useDaylightTime()` Queries if this time zone uses daylight savings time.

Methods inherited from class com.ibm.icu.util.BasicTimeZone
getSimpleTimeZoneRulesNear, getTimeZoneRules, hasEquivalentTransitions, hasEquivalentTransitions

Methods inherited from class com.ibm.icu.util.TimeZone
countEquivalentIDs, equals, 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, setID

Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - RuleBasedTimeZone
```
public RuleBasedTimeZone(String id,
                 InitialTimeZoneRule initialRule)
```
    Constructs a RuleBasedTimeZone object with the ID and the InitialTimeZoneRule
    
    Parameters:
    id - The time zone ID.
    initialRule - The initial time zone rule.
    Status:
    Stable ICU 3.8.
- Method Detail
  - addTransitionRule
```
public void addTransitionRule(TimeZoneRule rule)
```
    Adds the TimeZoneRule which represents time transitions. The TimeZoneRule must have start times, that is, the result of TimeZoneRule.isTransitionRule() must be true. Otherwise, IllegalArgumentException is thrown.
    
    Parameters:
    rule - The TimeZoneRule.
    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 time,
             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:
    time - 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
```
@Deprecated
public void getOffsetFromLocal(long date,
                                 int nonExistingTimeOpt,
                                 int duplicatedTimeOpt,
                                 int[] offsets)
```
    Deprecated. This API is ICU internal only.
    
    [icu] Returns time zone offsets from local wall time.
    
    Overrides:
    
    getOffsetFromLocal in class BasicTimeZone
    
    Status:
    Internal. This API is ICU internal only.
  - 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 JDK compatibility support. The JDK's useDaylightTime() only checks the last known rule(s), therefore it may return false even the zone observes daylight saving time currently. JDK 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 JDK's observesDaylightSavingTime(). 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.
  - 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.
  - 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.
  - 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.

Class RuleBasedTimeZone

Nested Class Summary

Nested classes/interfaces inherited from class com.ibm.icu.util.TimeZone

Field Summary

Fields inherited from class com.ibm.icu.util.BasicTimeZone

Fields inherited from class com.ibm.icu.util.TimeZone

Constructor Summary

Method Summary

Methods inherited from class com.ibm.icu.util.BasicTimeZone

Methods inherited from class com.ibm.icu.util.TimeZone

Methods inherited from class java.lang.Object

Constructor Detail

RuleBasedTimeZone

Method Detail

addTransitionRule

getOffset

getOffset

getOffsetFromLocal

getRawOffset

inDaylightTime

setRawOffset

useDaylightTime

observesDaylightTime

hasSameRules

getTimeZoneRules

getNextTransition

getPreviousTransition

clone

isFrozen

freeze

cloneAsThawed