Package net.time4j.tz

Interface TransitionHistory

All Known Implementing Classes:
TransitionModel
public interface TransitionHistory

Keeps all offset transitions and rules of a timezone.

Note: This interface can be considered as stable since version v2.2. Preliminary experimental versions of this interface existed since v1.0 but there was originally not any useable implementation.

Note: All implementations must be immutable and serializable.

Author:
Meno Hochschild

  • Method Details

    • getInitialOffset

      ZonalOffset getInitialOffset()

      Return the initial offset no matter if there are any transitions defined or not.

      If any transition is defined then the initial offset is identical to the shift getPreviousOffset() of the first defined transition in history.

      Returns:
      fixed initial shift in full seconds

    • getStartTransition

      ZonalTransition getStartTransition​(UnixTime ut)

      Queries the last transition which defines the offset for given global timestamp.

      For standard use cases, users can use the alternative method findStartTransition() unless performance considerations prohibit the usage of class Optional.

      Parameters:
      ut - unix reference time
      Returns:
      ZonalTransition or null if given reference time is before first defined transition
      See Also:
      findStartTransition(UnixTime)

    • getConflictTransition

      ZonalTransition getConflictTransition​(GregorianDate localDate, WallTime localTime)

      Returns the conflict transition where given local timestamp falls either in a gap or in an overlap on the local timeline.

      Note that only the expression localDate.getYear() is used to determine the daylight saving rules to be applied in calculation. This is particularly important if there is a wall time of 24:00. Here only the date before merging to next day matters, not the date of the whole timestamp.

      For standard use cases, users can use the alternative method findConflictTransition() unless performance considerations prohibit the usage of class Optional.

      Parameters:
      localDate - local date in timezone
      localTime - local wall time in timezone
      Returns:
      conflict transition on the local time axis for gaps or overlaps else null
      See Also:
      getValidOffsets(GregorianDate,WallTime), findConflictTransition(GregorianDate, WallTime)

    • getValidOffsets

      List<ZonalOffset> getValidOffsets​(GregorianDate localDate, WallTime localTime)

      Determines the suitable offsets at given local timestamp..

      The offset list is empty if the local timestamp falls in a gap on the local timeline. The list has exactly two offsets sorted by size if the local timestamp belongs to two different timepoints on the POSIX timescale due to an overlap. Otherwise the offset list will contain exactly one suitable offset.

      Note that only the expression localDate.getYear() is used to determine the daylight saving rules to be applied in calculation. This is particularly important if there is a wall time of 24:00. Here only the date before merging to next day matters, not the date of the whole timestamp.

      Parameters:
      localDate - local date in timezone
      localTime - local wall time in timezone
      Returns:
      unmodifiable list of shifts in full seconds which fits the given local time
      See Also:
      findConflictTransition(GregorianDate,WallTime)

    • getStdTransitions

      List<ZonalTransition> getStdTransitions()

      Return the offset transitions from UNIX epoch [1970-01-01T00:00Z] until about one year after the current timestamp.

      Indeed, a potentially bigger interval is obtainable by getTransitions(UnixTime,UnixTime), but earlier or later timepoints are usually not reliable. For example the wide-spread IANA/Olson-repository is only designed for times since UNIX epoch and offers some selected older data to the best of our knowledge. Users must be aware that even older data can be changed as side effect of data corrections. Generally the timezone concept was invented in 19th century. And future transitions are even less reliable due to political arbitrariness.

      Returns:
      unmodifiable list of standard transitions (after 1970-01-01) maybe empty

    • getTransitions

      List<ZonalTransition> getTransitions​(UnixTime startInclusive, UnixTime endExclusive)

      Returns the defined transitions in given POSIX-interval.

      Parameters:
      startInclusive - start time on POSIX time scale
      endExclusive - end time on POSIX time scale
      Returns:
      unmodifiable list of transitions maybe empty
      Throws:
      IllegalArgumentException - if start is after end
      See Also:
      getStdTransitions()

    • isEmpty

      boolean isEmpty()

      Determines if this history does not have any transitions.

      Returns:
      true if there are no transitions else false

    • dump

      void dump​(Appendable buffer) throws IOException

      Creates a dump of this history and writes it to the given buffer.

      Parameters:
      buffer - buffer to write the dump to
      Throws:
      IOException - in any case of I/O-errors

    • findStartTransition

      default Optional<ZonalTransition> findStartTransition​(UnixTime ut)

      Queries the last transition which defines the offset for given global timestamp.

      Parameters:
      ut - unix reference time
      Returns:
      ZonalTransition, not present if given reference time is before first defined transition
      Since:
      4.18

    • findConflictTransition

      default Optional<ZonalTransition> findConflictTransition​(GregorianDate localDate, WallTime localTime)

      Returns the conflict transition where given local timestamp falls either in a gap or in an overlap on the local timeline.

      Note that only the expression localDate.getYear() is used to determine the daylight saving rules to be applied in calculation. This is particularly important if there is a wall time of 24:00. Here only the date before merging to next day matters, not the date of the whole timestamp.

      Parameters:
      localDate - local date in timezone
      localTime - local wall time in timezone
      Returns:
      optional conflict transition on the local time axis for gaps or overlaps if present
      Since:
      4.18
      See Also:
      getValidOffsets(GregorianDate,WallTime)

    • findNextTransition

      Optional<ZonalTransition> findNextTransition​(UnixTime ut)

      Queries the next transition after given global timestamp.

      Parameters:
      ut - unix reference time
      Returns:
      ZonalTransition, not present if given reference time is after any defined transition
      Since:
      4.18

    • findPreviousTransition

      default Optional<ZonalTransition> findPreviousTransition​(UnixTime ut)

      Queries the previous transition which defines the offset for a global timestamp immediately before given reference timestamp.

      Parameters:
      ut - unix reference time
      Returns:
      ZonalTransition, not present if given reference time is not after any defined transition
      Since:
      4.18