Class ZoneRules
- Direct Known Subclasses:
FixedZoneRules
,StandardZoneRules
The rules model all the historic and future transitions for a time-zone.
The rules are loaded via TimeZone
and ZoneRulesGroup
and
are specific to a group, region and version. The same rules may be shared
between multiple versions, regions or even groups.
Serializing an instance of ZoneRules
will store the entire set
of rules. It does not store the group, region or version as they are not
part of the state of this object.
ZoneRules is an abstract class and must be implemented with care to ensure other classes in the framework operate correctly. All instantiable implementations must be final, immutable and thread-safe. It is only intended that the abstract methods are overridden. Subclasses should be Serializable wherever possible.
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescription(package private) static void
checkNotNull
(Object object, String errorMessage) Validates that the input value is not null.abstract boolean
Checks if this set of rules equals another.getDaylightSavings
(InstantProvider instantProvider) Gets the amount of daylight savings in use for the specified instant in this zone.abstract ZoneOffset
getOffset
(InstantProvider instant) Gets the offset applicable at the specified instant in this zone.abstract ZoneOffsetInfo
getOffsetInfo
(LocalDateTime dateTime) Gets the offset information for a local date-time in this zone.getOffsetInfo
(Instant instant) Gets the offset information for the specified instant in this zone.abstract ZoneOffset
getStandardOffset
(InstantProvider instantProvider) Gets the standard offset for the specified instant in this zone.abstract List
<ZoneOffsetTransitionRule> Gets the list of transition rules for years beyond those defined in the transition list.abstract List
<ZoneOffsetTransition> Gets the complete list of fully defined transitions.abstract int
hashCode()
Returns a suitable hash code.boolean
isDaylightSavings
(InstantProvider instant) Gets the standard offset for the specified instant in this zone.boolean
Checks of the zone rules are fixed, such that the offset never varies.boolean
isValidDateTime
(OffsetDateTime dateTime) Checks if the offset date-time is valid for these rules.abstract ZoneOffsetTransition
nextTransition
(InstantProvider instantProvider) Gets the next transition after the specified transition.static ZoneRules
ofFixed
(ZoneOffset offset) Obtains a rules instance for a specific offset.abstract ZoneOffsetTransition
previousTransition
(InstantProvider instantProvider) Gets the previous transition after the specified transition.
-
Constructor Details
-
ZoneRules
protected ZoneRules()Constructor for subclasses.
-
-
Method Details
-
ofFixed
Obtains a rules instance for a specific offset.The returned rules object will have no transitions and will use the specified offset for all points on the time-line.
- Parameters:
offset
- the offset to get the fixed rules for, not null- Returns:
- the rules, never null
-
checkNotNull
Validates that the input value is not null.- Parameters:
object
- the object to checkerrorMessage
- the error to throw- Throws:
NullPointerException
- if the object is null
-
isFixedOffset
public boolean isFixedOffset()Checks of the zone rules are fixed, such that the offset never varies.It is intended that
OffsetDateTime
,OffsetDate
andOffsetTime
are used in preference to fixed offset time-zones inZonedDateTime
.The default implementation returns false.
- Returns:
- true if the time-zone is fixed and the offset never changes
-
getOffset
Gets the offset applicable at the specified instant in this zone.For any given instant there can only ever be one valid offset, which is returned by this method. To access more detailed information about the offset at and around the instant use
getOffsetInfo(Instant)
.- Parameters:
instant
- the instant to find the offset for, ignored for fixed offset rules, otherwise not null- Returns:
- the offset, never null
-
getOffsetInfo
Gets the offset information for the specified instant in this zone.This provides access to full details as to the offset or offsets applicable for the local date-time. The mapping from an instant to an offset is not straightforward. There are two cases:
- Normal. Where there is a single offset for the local date-time.
- Overlap. Where there is a gap in the local time-line normally caused by the autumn cutover from daylight savings. There are two valid offsets during the overlap.
ZoneOffsetInfo.isTransition()
to handle the overlap.- Parameters:
instant
- the instant to find the offset information for, not null- Returns:
- the offset information, never null
-
getOffsetInfo
Gets the offset information for a local date-time in this zone.This provides access to full details as to the offset or offsets applicable for the local date-time. The mapping from a local date-time to an offset is not straightforward. There are three cases:
- Normal. Where there is a single offset for the local date-time.
- Gap. Where there is a gap in the local time-line normally caused by the spring cutover to daylight savings. There are no valid offsets within the gap
- Overlap. Where there is a gap in the local time-line normally caused by the autumn cutover from daylight savings. There are two valid offsets during the overlap.
ZoneOffsetInfo.isTransition()
to handle the gap or overlap.- Parameters:
dateTime
- the date-time to find the offset information for, not null- Returns:
- the offset information, never null
-
getStandardOffset
Gets the standard offset for the specified instant in this zone.This provides access to historic information on how the standard offset has changed over time. The standard offset is the offset before any daylight savings time is applied. This is typically the offset applicable during winter.
- Parameters:
instantProvider
- the instant to find the offset information for, not null- Returns:
- the standard offset, never null
-
getDaylightSavings
Gets the amount of daylight savings in use for the specified instant in this zone.This provides access to historic information on how the amount of daylight savings has changed over time. This is the difference between the standard offset and the actual offset. It is expressed in hours, minutes and seconds. Typically the amount is zero during winter and one hour during summer.
- Parameters:
instantProvider
- the instant to find the offset information for, not null- Returns:
- the difference between the standard and actual offset, never null
-
isDaylightSavings
Gets the standard offset for the specified instant in this zone.This provides access to historic information on how the standard offset has changed over time. The standard offset is the offset before any daylight savings time is applied. This is typically the offset applicable during winter.
- Parameters:
instant
- the instant to find the offset information for, not null- Returns:
- the standard offset, never null
-
nextTransition
Gets the next transition after the specified transition.This returns details of the next transition after the specified instant.
Some providers of rules may not be able to return this information, thus the method is defined to throw UnsupportedOperationException. The supplied rules implementations do supply this information and don't throw the exception
- Parameters:
instantProvider
- the instant to get the next transition after, not null- Returns:
- the next transition after the specified instant, null if this is after the last transition
- Throws:
UnsupportedOperationException
- if the implementation cannot return this information - the default 'TZDB' can return this information
-
previousTransition
Gets the previous transition after the specified transition.This returns details of the previous transition after the specified instant.
Some providers of rules may not be able to return this information, thus the method is defined to throw UnsupportedOperationException. The supplied rules implementations do supply this information and don't throw the exception
- Parameters:
instantProvider
- the instant to get the previous transition after, not null- Returns:
- the previous transition after the specified instant, null if this is before the first transition
- Throws:
UnsupportedOperationException
- if the implementation cannot return this information - the default 'TZDB' can return this information
-
getTransitions
Gets the complete list of fully defined transitions.The complete set of transitions for this rules instance is defined by this method and
getTransitionRules()
. This method returns those transitions that have been fully defined. These are typically historical, but may be in the future. The list will be empty for fixed offset rules.Some providers of rules cannot return this information, thus this method is defined to throw UnsupportedOperationException. The supplied 'TZDB' implementation can supply this information thus does not throw the exception.
- Returns:
- independent, modifiable copy of the list of fully defined transitions, never null
- Throws:
UnsupportedOperationException
- if the implementation cannot return this information - the default 'TZDB' can return this information
-
getTransitionRules
Gets the list of transition rules for years beyond those defined in the transition list.The complete set of transitions for this rules instance is defined by this method and
getTransitions()
. This method returns instances ofZoneOffsetTransitionRule
that define an algorithm for when transitions will occur. The list will be empty for fixed offset rules.For any given
ZoneRules
, this list contains the transition rules for years beyond those years that have been fully defined. These rules typically refer to future daylight savings time rule changes.If the zone defines daylight savings into the future, then the list will normally be of size two and hold information about entering and exiting daylight savings. If the zone does not have daylight savings, or information about future changes is uncertain, then the list will be empty.
Some providers of rules cannot return this information, thus this method is defined to throw UnsupportedOperationException. The supplied 'TZDB' implementation can supply this information thus does not throw the exception.
- Returns:
- independent, modifiable copy of the list of transition rules, never null
- Throws:
UnsupportedOperationException
- if the implementation cannot return this information - the default 'TZDB' can return this information
-
isValidDateTime
Checks if the offset date-time is valid for these rules.To be valid, the local date-time must not be in a gap and the offset must match the valid offsets.
- Parameters:
dateTime
- the date-time to check, not null- Returns:
- true if the offset date-time is valid for these rules
-
equals
Checks if this set of rules equals another.Two rule sets are equal if they will always result in the same output for any given input instant or date-time. Rules from two different groups may return false even if they are in fact the same.
This definition should result in implementations comparing their entire state.
-
hashCode
public abstract int hashCode()Returns a suitable hash code.
-