Class BasicTimeZone

java.lang.Object
com.ibm.icu.util.TimeZone
com.ibm.icu.util.BasicTimeZone
All Implemented Interfaces:
Freezable<TimeZone>, Serializable, Cloneable
Direct Known Subclasses:
RuleBasedTimeZone, SimpleTimeZone, VTimeZone
public abstract class BasicTimeZone extends TimeZone
Methods, fields, and other functionality specific to ICU are labeled '[icu]'. BasicTimeZone extends TimeZone with additional methods to access time zone transitions and rules. All ICU TimeZone concrete subclasses extend this class. APIs added to java.util.TimeZone by BasicTimeZone are annotated with '[icu]'.
See Also:
Status:
Stable ICU 3.8.

  • Field Details

    • LOCAL_STD

      @Deprecated protected static final int LOCAL_STD
      Deprecated.
      This API is ICU internal only.
      The time type option for standard time used by internal implementation.
      See Also:
      Status:
      Internal. This API is ICU internal only.

    • LOCAL_DST

      @Deprecated protected static final int LOCAL_DST
      Deprecated.
      This API is ICU internal only.
      The time type option for daylight saving time used internally.
      See Also:
      Status:
      Internal. This API is ICU internal only.

    • LOCAL_FORMER

      @Deprecated protected static final int LOCAL_FORMER
      Deprecated.
      This API is ICU internal only.
      The option designate former time used by internal implementation.
      See Also:
      Status:
      Internal. This API is ICU internal only.

    • LOCAL_LATTER

      @Deprecated protected static final int LOCAL_LATTER
      Deprecated.
      This API is ICU internal only.
      The option designate latter time used by internal implementation.
      See Also:
      Status:
      Internal. This API is ICU internal only.

    • STD_DST_MASK

      @Deprecated protected static final int STD_DST_MASK
      Deprecated.
      This API is ICU internal only.
      The bit mask for the time type option used by internal implementation.
      See Also:
      Status:
      Internal. This API is ICU internal only.

    • FORMER_LATTER_MASK

      @Deprecated protected static final int FORMER_LATTER_MASK
      Deprecated.
      This API is ICU internal only.
      The bit mask for the former/latter option used by internal implementation.
      See Also:
      Status:
      Internal. This API is ICU internal only.

  • Constructor Details

    • BasicTimeZone

      protected BasicTimeZone()
      Protected no arg constructor.
      Status:
      Stable ICU 3.8.

    • BasicTimeZone

      @Deprecated protected BasicTimeZone(String ID)
      Deprecated.
      This API is ICU internal only.
      Constructing a BasicTimeZone with the given time zone ID.
      Parameters:
      ID - the time zone ID.
      Status:
      Internal. This API is ICU internal only.

  • Method Details

    • getNextTransition

      public abstract 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;
}
      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 abstract 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;
}
      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 tz, 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);
}
      Parameters:
      tz - 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.

    • hasEquivalentTransitions

      public boolean hasEquivalentTransitions(TimeZone tz, long start, long end, boolean ignoreDstAmount)
      [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.
      Parameters:
      tz - The instance of TimeZone
      start - The start time of the evaluated time range (inclusive)
      end - The end time of the evaluated time range (inclusive)
      ignoreDstAmount - When true, any transitions with only daylight saving amount changes will be ignored, except either of them is zero. For example, a transition from rawoffset 3:00/dstsavings 1:00 to rawoffset 2:00/dstsavings 2:00 is excluded from the comparison, but a transition from rawoffset 2:00/dstsavings 1:00 to rawoffset 3:00/dstsavings 0:00 is included.
      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 abstract 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.
      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]);
}
      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.

    • getSimpleTimeZoneRulesNear

      public TimeZoneRule[] getSimpleTimeZoneRulesNear(long date)
      [icu] Returns the array of TimeZoneRule which represents the rule of this time zone object near the specified date. Some applications are not capable to handle historic time zone rule changes. Also some applications can only handle certain type of rule definitions. This method returns either a single InitialTimeZoneRule if this time zone does not have any daylight saving time within 1 year from the specified time, or a pair of AnnualTimeZoneRule whose rule type is DateTimeRule.DOW for date and DateTimeRule.WALL_TIME for time with a single InitialTimeZoneRule representing the initial time, when this time zone observes daylight saving time near the specified date. Thus, the result may be only valid for dates around the specified date.
      Parameters:
      date - The date to be used for TimeZoneRule extraction.
      Returns:
      The array of TimeZoneRule, either a single InitialTimeZoneRule object, or a pair of AnnualTimeZoneRule with a single InitialTimeZoneRule. The first element in the array is always a InitialTimeZoneRule.
      Status:
      Stable ICU 3.8.

    • getLocalOptionValue

      @Deprecated protected static int getLocalOptionValue(BasicTimeZone.LocalOption locOpt)
      Deprecated.
      This API is ICU internal only.
      Get BasicTimeZone.LocalOption's internal flag value. This is used by ICU internal implementation only.
      Parameters:
      locOpt - A LocalOption
      Returns:
      LocalOption's internal flag value.
      Status:
      Internal. This API is ICU internal only.

    • getOffsetFromLocal

      public void getOffsetFromLocal(long date, BasicTimeZone.LocalOption nonExistingTimeOpt, BasicTimeZone.LocalOption duplicatedTimeOpt, int[] offsets)
      [icu] Returns time zone offsets from local wall time.
      Status:
      Stable ICU 69.