Class ZoneResolver

java.lang.Object
javax.time.calendar.ZoneResolver
Direct Known Subclasses:
ZoneResolvers.Combination, ZoneResolvers.PostGapPreOverlap, ZoneResolvers.PostTransition, ZoneResolvers.PreTransition, ZoneResolvers.PushForward, ZoneResolvers.RetainOffset, ZoneResolvers.Strict

public abstract class ZoneResolver extends Object
Strategy for resolving a LocalDateTime to an OffsetDateTime using the rules of the time-zone.

A time-zone provides rules for when and by how much the offset changes for a given location. These rules can result in 'missing hours', such as at the spring daylight savings cutover, and 'overlapping hours', such as at the autumn cutover.

Implementations of this resolver handles these missing and overlapping cases by either throwing an exception, selecting the appropriate offset or changing the local date-time.

ZoneResolver is an abstract class and must be implemented with care to ensure other classes in the framework operate correctly. All instantiable subclasses must be final, immutable and thread-safe.

  • Constructor Details

    • ZoneResolver

      protected ZoneResolver()
      Restrictive constructor.
  • Method Details

    • resolve

      public final OffsetDateTime resolve(TimeZone zone, LocalDateTime newDateTime, ZonedDateTime oldDateTime)
      Parameters:
      zone - the time-zone, not null
      newDateTime - the new date-time, not null
      oldDateTime - the old date-time before the adjustment, may be null
      Returns:
      the resolved values, returned as a (year,month,day) tuple, never null
      Throws:
      CalendricalException - if the date-time cannot be resolved
    • handleGap

      protected abstract OffsetDateTime handleGap(TimeZone zone, ZoneRules rules, ZoneOffsetTransition gapInfo, LocalDateTime newDateTime, OffsetDateTime oldDateTime)
      Defines the strategy for selecting an offset to use for a local date-time when the local date-time is in a local time-line gap.

      Implementations of method handles missing date-times by either throwing an exception or changing the local date-time.

      Information is provided to assist with the strategy. This includes the zone rules, information about the gap and the old date-time.

      The old date-time is provided if this strategy is called as a result of an adjustment, such as changing a field, addition or subtraction. This parameter will be null if there is no original date-time, such as during construction of a ZonedDateTime.

      After the completion of this method, the result will be validated.

      A typical implementation might be:

        return gapInfo.getDateTimeAfter();
       
      This implementation works by returning the first valid date-time after the gap.
      Parameters:
      zone - the time-zone, not null
      rules - the applicable zone rules, not null
      gapInfo - the information about the gap for the newDateTime, not null
      newDateTime - the new local date-time, not null
      oldDateTime - the old offset date-time before the adjustment, may be null
      Returns:
      the resolved offset date-time, never null
      Throws:
      IllegalCalendarFieldValueException - if the offset cannot be calculated
    • handleOverlap

      protected abstract OffsetDateTime handleOverlap(TimeZone zone, ZoneRules rules, ZoneOffsetTransition overlapInfo, LocalDateTime newDateTime, OffsetDateTime oldDateTime)
      Defines the strategy for selecting an offset to use for a local date-time when the local date-time is in a local time-line overlap.

      Implementations of method handle overlapping date-times by throwing an exception, selecting the appropriate offset or changing the local date-time. Two additional parameters are available to help with the logic.

      Firstly, the discontinuity, which represents the discontinuity in the local time-line that needs to be resolved. This is the result from zone.getOffsetInfo(newDateTime) and is provided to improve performance.

      Secondly, the old date-time, which is the original offset date-time that any adjustment started from. Example adjustments are changing a field, addition or subtraction. This parameter will be null if there is no original date-time, such as during construction.

      After the completion of this method, the result will be validated.

      A typical implementation might be:

        if (oldDateTime != null invalid input: '&'invalid input: '&' discontinuity.containsOffset(oldDateTime.getOffset())) {
          return OffsetDateTime.dateTime(newDateTime, oldDateTime.getOffset());
        }
        return OffsetDateTime.dateTime(newDateTime, discontinuity.getOffsetBefore());
       
      This implementation handles the overlap by attempting to keep the result offset in the same offset as the old date-time. Otherwise, it returns the earlier of the two offsets.
      Parameters:
      zone - the time-zone, not null
      rules - the applicable zone rules, not null
      overlapInfo - the information about the overlap for the newDateTime, not null
      newDateTime - the new local date-time, not null
      oldDateTime - the old offset date-time before the adjustment, may be null
      Returns:
      the resolved offset date-time, never null
      Throws:
      IllegalCalendarFieldValueException - if the offset cannot be calculated