public abstract class ZoneResolver extends Object
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.
Modifier | Constructor and Description |
---|---|
protected |
ZoneResolver()
Restrictive constructor.
|
Modifier and Type | Method and Description |
---|---|
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.
|
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.
|
OffsetDateTime |
resolve(TimeZone zone,
LocalDateTime newDateTime,
ZonedDateTime oldDateTime)
Resolves the new local date-time to an offset date-time using the zone.
|
public final OffsetDateTime resolve(TimeZone zone, LocalDateTime newDateTime, ZonedDateTime oldDateTime)
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)
or handleOverlap(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.
zone
- the time-zone, not nullnewDateTime
- the new date-time, not nulloldDateTime
- the old date-time before the adjustment, may be nullCalendricalException
- if the date-time cannot be resolvedprotected abstract OffsetDateTime handleGap(TimeZone zone, ZoneRules rules, ZoneOffsetTransition gapInfo, LocalDateTime newDateTime, OffsetDateTime oldDateTime)
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.
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 nullIllegalCalendarFieldValueException
- if the offset cannot be calculatedprotected abstract OffsetDateTime handleOverlap(TimeZone zone, ZoneRules rules, ZoneOffsetTransition overlapInfo, LocalDateTime newDateTime, OffsetDateTime oldDateTime)
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 && 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.
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 nullIllegalCalendarFieldValueException
- if the offset cannot be calculatedCopyright © 2014. All rights reserved.