Class ZoneResolver
- Direct Known Subclasses:
ZoneResolvers.Combination
,ZoneResolvers.PostGapPreOverlap
,ZoneResolvers.PostTransition
,ZoneResolvers.PreTransition
,ZoneResolvers.PushForward
,ZoneResolvers.RetainOffset
,ZoneResolvers.Strict
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 Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionprotected 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.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.final OffsetDateTime
resolve
(TimeZone zone, LocalDateTime newDateTime, ZonedDateTime oldDateTime) Resolves the new local date-time to an offset date-time using the zone.
-
Constructor Details
-
ZoneResolver
protected ZoneResolver()Restrictive constructor.
-
-
Method Details
-
resolve
public final OffsetDateTime resolve(TimeZone zone, LocalDateTime newDateTime, ZonedDateTime oldDateTime) Resolves the new local date-time to an offset date-time using the zone.This method forwards to an internal method that calls
handleGap(javax.time.calendar.TimeZone, javax.time.calendar.zone.ZoneRules, javax.time.calendar.zone.ZoneOffsetTransition, javax.time.calendar.LocalDateTime, javax.time.calendar.OffsetDateTime)
orhandleOverlap(javax.time.calendar.TimeZone, javax.time.calendar.zone.ZoneRules, javax.time.calendar.zone.ZoneOffsetTransition, javax.time.calendar.LocalDateTime, javax.time.calendar.OffsetDateTime)
. The internal method will validate the result to ensure it is valid for the zone.- Parameters:
zone
- the time-zone, not nullnewDateTime
- the new date-time, not nulloldDateTime
- 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 nullrules
- the applicable zone rules, not nullgapInfo
- the information about the gap for the newDateTime, not nullnewDateTime
- the new local date-time, not nulloldDateTime
- 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 nullrules
- the applicable zone rules, not nulloverlapInfo
- the information about the overlap for the newDateTime, not nullnewDateTime
- the new local date-time, not nulloldDateTime
- 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
-