Class OlsonTimeZone

java.lang.Object
com.ibm.icu.util.TimeZone
com.ibm.icu.util.BasicTimeZone
com.ibm.icu.impl.OlsonTimeZone
All Implemented Interfaces:
Freezable<TimeZone>, Serializable, Cloneable
public class OlsonTimeZone extends BasicTimeZone implements Cloneable
A time zone based on the Olson tz database. Olson time zones change behavior over time. The raw offset, rules, presence or absence of daylight savings time, and even the daylight savings amount can all vary. This class uses a resource bundle named "zoneinfo". Zoneinfo is a table containing different kinds of resources. In several places, zones are referred to using integers. A zone's integer is a number from 0..n-1, where n is the number of zones, with the zones sorted in lexicographic order. 1. Zones. These have keys corresponding to the Olson IDs, e.g., "Asia/Shanghai". Each resource describes the behavior of the given zone. Zones come in two different formats. a. Zone (table). A zone is a table resource contains several type of resources below: - typeOffsets:intvector (Required) Sets of UTC raw/dst offset pairs in seconds. Entries at 2n represents raw offset and 2n+1 represents dst offset paired with the raw offset at 2n. The very first pair represents the initial zone offset (before the first transition) always. - trans:intvector (Optional) List of transition times represented by 32bit seconds from the epoch (1970-01-01T00:00Z) in ascending order. - transPre32/transPost32:intvector (Optional) List of transition times before/after 32bit minimum seconds. Each time is represented by a pair of 32bit integer. - typeMap:bin (Optional) Array of bytes representing the mapping between each transition time (transPre32/trans/transPost32) and its corresponding offset data (typeOffsets). - finalRule:string (Optional) If a recurrent transition rule is applicable to a zone forever after the final transition time, finalRule represents the rule in Rules data. - finalRaw:int (Optional) When finalRule is available, finalRaw is required and specifies the raw (base) offset of the rule. - finalYear:int (Optional) When finalRule is available, finalYear is required and specifies the start year of the rule. - links:intvector (Optional) When this zone data is shared with other zones, links specifies all zones including the zone itself. Each zone is referenced by integer index. b. Link (int, length 1). A link zone is an int resource. The integer is the zone number of the target zone. The key of this resource is an alternate name for the target zone. This data is corresponding to Link data in the tz database. 2. Rules. These have keys corresponding to the Olson rule IDs, with an underscore prepended, e.g., "_EU". Each resource describes the behavior of the given rule using an intvector, containing the onset list, the cessation list, and the DST savings. The onset and cessation lists consist of the month, dowim, dow, time, and time mode. The end result is that the 11 integers describing the rule can be passed directly into the SimpleTimeZone 13-argument constructor (the other two arguments will be the raw offset, taken from the complex zone element 5, and the ID string, which is not used), with the times and the DST savings multiplied by 1000 to scale from seconds to milliseconds. 3. Regions. An array specifies mapping between zones and regions. Each item is either a 2-letter ISO country code or "001" (UN M.49 - World). This data is generated from "zone.tab" in the tz database.
See Also:

  • Field Details

    • serialVersionUID

      static final long serialVersionUID
      See Also:

    • MAX_OFFSET_SECONDS

      private static final int MAX_OFFSET_SECONDS
      See Also:

    • transitionCount

      private int transitionCount
      Number of transitions, 0..~370

    • typeCount

      private int typeCount
      Number of types, 1..255

    • transitionTimes64

      private long[] transitionTimes64
      Time of each transition in seconds from 1970 epoch.

    • typeOffsets

      private int[] typeOffsets
      Offset from GMT in seconds for each type. Length is equal to typeCount

    • typeMapData

      private byte[] typeMapData
      Type description data, consisting of transitionCount uint8_t type indices (from 0..typeCount-1). Length is equal to transitionCount

    • finalStartYear

      private int finalStartYear
      For year >= finalStartYear, the finalZone will be used.

    • finalStartMillis

      private double finalStartMillis
      For date >= finalStartMillis, the finalZone will be used.

    • finalZone

      private SimpleTimeZone finalZone
      A SimpleTimeZone that governs the behavior for years >= finalYear. If and only if finalYear == INT32_MAX then finalZone == 0.

    • canonicalID

      private volatile String canonicalID
      The canonical ID of this zone. Initialized when getCanonicalID() is invoked first time, or setID(String) is called.

    • ZONEINFORES

      private static final String ZONEINFORES
      See Also:

    • DEBUG

      private static final boolean DEBUG

    • SECONDS_PER_DAY

      private static final int SECONDS_PER_DAY
      See Also:

    • initialRule

      private transient InitialTimeZoneRule initialRule

    • firstTZTransition

      private transient TimeZoneTransition firstTZTransition

    • firstTZTransitionIdx

      private transient int firstTZTransitionIdx

    • firstFinalTZTransition

      private transient TimeZoneTransition firstFinalTZTransition

    • historicRules

      private transient TimeArrayTimeZoneRule[] historicRules

    • finalZoneWithStartYear

      private transient SimpleTimeZone finalZoneWithStartYear

    • transitionRulesInitialized

      private transient boolean transitionRulesInitialized

    • currentSerialVersion

      private static final int currentSerialVersion
      See Also:

    • serialVersionOnStream

      private int serialVersionOnStream

    • isFrozen

      private transient volatile boolean isFrozen

  • Constructor Details

    • OlsonTimeZone

      public OlsonTimeZone(UResourceBundle top, UResourceBundle res, String id)
      Construct from a resource bundle
      Parameters:
      top - the top-level zoneinfo resource bundle. This is used to lookup the rule that res may refer to, if there is one.
      res - the resource bundle of the zone to be constructed
      id - time zone ID

    • OlsonTimeZone

      public OlsonTimeZone(String id)

  • Method Details

    • getOffset

      public int getOffset(int era, int year, int month, int day, int dayOfWeek, int milliseconds)
      Description copied from class: TimeZone
      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.

    • getOffset

      public int getOffset(int era, int year, int month, int dom, int dow, int millis, int monthLength)
      TimeZone API.

    • setRawOffset

      public void setRawOffset(int offsetMillis)
      Description copied from class: TimeZone
      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.

    • clone

      public OlsonTimeZone clone()
      Description copied from class: TimeZone
      Overrides clone.
      Overrides:
      clone in class TimeZone

    • getOffset

      public void getOffset(long date, boolean local, int[] offsets)
      TimeZone API.
      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.

    • 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 class BasicTimeZone

    • getRawOffset

      public int getRawOffset()
      Description copied from class: TimeZone
      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.

    • useDaylightTime

      public boolean useDaylightTime()
      Description copied from class: TimeZone
      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.

    • observesDaylightTime

      public boolean observesDaylightTime()
      Description copied from class: TimeZone
      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:

    • getDSTSavings

      public int getDSTSavings()
      TimeZone API Returns the amount of time to be added to local standard time to get local wall clock time.
      Overrides:
      getDSTSavings in class TimeZone
      Returns:
      the amount of saving time in milliseconds

    • inDaylightTime

      public boolean inDaylightTime(Date date)
      Description copied from class: TimeZone
      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.

    • hasSameRules

      public boolean hasSameRules(TimeZone other)
      Description copied from class: TimeZone
      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

    • getCanonicalID

      public String getCanonicalID()
      Returns the canonical ID of this system time zone

    • constructEmpty

      private void constructEmpty()
      Construct a GMT+0 zone with no transitions. This is done when a constructor fails so the resultant object is well-behaved.

    • construct

      private void construct(UResourceBundle top, UResourceBundle res, String id)

    • setID

      public void setID(String id)
      Description copied from class: TimeZone
      Sets the time zone ID. This does not change any other data in the time zone object.
      Overrides:
      setID in class TimeZone
      Parameters:
      id - the new time zone ID.

    • getHistoricalOffset

      private void getHistoricalOffset(long date, boolean local, int NonExistingTimeOpt, int DuplicatedTimeOpt, int[] offsets)

    • getInt

      private int getInt(byte val)

    • zoneOffsetAt

      private int zoneOffsetAt(int transIdx)

    • rawOffsetAt

      private int rawOffsetAt(int transIdx)

    • dstOffsetAt

      private int dstOffsetAt(int transIdx)

    • initialRawOffset

      private int initialRawOffset()

    • initialDstOffset

      private int initialDstOffset()

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • loadRule

      private static UResourceBundle loadRule(UResourceBundle top, String ruleid)

    • equals

      public boolean equals(Object obj)
      Description copied from class: TimeZone
      Overrides equals.
      Overrides:
      equals in class TimeZone
      Returns:
      true if this object is the same as the obj argument; false otherwise.

    • hashCode

      public int hashCode()
      Description copied from class: TimeZone
      Overrides hashCode.
      Overrides:
      hashCode in class TimeZone
      Returns:
      a hash code value for this object.

    • getNextTransition

      public TimeZoneTransition getNextTransition(long base, boolean inclusive)
      Description copied from class: BasicTimeZone
      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.

    • getPreviousTransition

      public TimeZoneTransition getPreviousTransition(long base, boolean inclusive)
      Description copied from class: BasicTimeZone
      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.

    • getTimeZoneRules

      public TimeZoneRule[] getTimeZoneRules()
      Description copied from class: BasicTimeZone
      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.

    • initTransitionRules

      private void initTransitionRules()

    • readObject

      private void readObject(ObjectInputStream stream) throws IOException, ClassNotFoundException
      Throws:
      IOException
      ClassNotFoundException

    • isFrozen

      public boolean isFrozen()
      Description copied from class: TimeZone
      Determines whether the object has been frozen or not.
      Specified by:
      isFrozen in interface Freezable<TimeZone>
      Overrides:
      isFrozen in class TimeZone

    • freeze

      public TimeZone freeze()
      Description copied from class: TimeZone
      Freezes the object.
      Specified by:
      freeze in interface Freezable<TimeZone>
      Overrides:
      freeze in class TimeZone
      Returns:
      the object itself.

    • cloneAsThawed

      public OlsonTimeZone cloneAsThawed()
      Description copied from class: TimeZone
      Provides for the clone operation. Any clone is initially unfrozen.
      Specified by:
      cloneAsThawed in interface Freezable<TimeZone>
      Overrides:
      cloneAsThawed in class TimeZone