Class ZoneRules
- java.lang.Object
-
- javax.time.calendar.zone.ZoneRules
-
- Direct Known Subclasses:
FixedZoneRules
,StandardZoneRules
public abstract class ZoneRules extends java.lang.Object
The rules defining how the zone offset varies for a single time-zone.The rules model all the historic and future transitions for a time-zone. The rules are loaded via
TimeZone
andZoneRulesGroup
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 Modifier Constructor Description protected
ZoneRules()
Constructor for subclasses.
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description (package private) static void
checkNotNull(java.lang.Object object, java.lang.String errorMessage)
Validates that the input value is not null.abstract boolean
equals(java.lang.Object otherRules)
Checks if this set of rules equals another.Period
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.ZoneOffsetInfo
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 java.util.List<ZoneOffsetTransitionRule>
getTransitionRules()
Gets the list of transition rules for years beyond those defined in the transition list.abstract java.util.List<ZoneOffsetTransition>
getTransitions()
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
isFixedOffset()
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.
-
-
-
Method Detail
-
ofFixed
public static ZoneRules ofFixed(ZoneOffset offset)
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
static void checkNotNull(java.lang.Object object, java.lang.String errorMessage)
Validates that the input value is not null.- Parameters:
object
- the object to checkerrorMessage
- the error to throw- Throws:
java.lang.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
public abstract ZoneOffset getOffset(InstantProvider instant)
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
public ZoneOffsetInfo getOffsetInfo(Instant instant)
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
public abstract ZoneOffsetInfo getOffsetInfo(LocalDateTime dateTime)
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
public abstract ZoneOffset getStandardOffset(InstantProvider instantProvider)
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
public Period getDaylightSavings(InstantProvider instantProvider)
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
public boolean isDaylightSavings(InstantProvider instant)
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
public abstract ZoneOffsetTransition nextTransition(InstantProvider instantProvider)
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:
java.lang.UnsupportedOperationException
- if the implementation cannot return this information - the default 'TZDB' can return this information
-
previousTransition
public abstract ZoneOffsetTransition previousTransition(InstantProvider instantProvider)
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:
java.lang.UnsupportedOperationException
- if the implementation cannot return this information - the default 'TZDB' can return this information
-
getTransitions
public abstract java.util.List<ZoneOffsetTransition> 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:
java.lang.UnsupportedOperationException
- if the implementation cannot return this information - the default 'TZDB' can return this information
-
getTransitionRules
public abstract java.util.List<ZoneOffsetTransitionRule> 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:
java.lang.UnsupportedOperationException
- if the implementation cannot return this information - the default 'TZDB' can return this information
-
isValidDateTime
public boolean isValidDateTime(OffsetDateTime dateTime)
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
public abstract boolean equals(java.lang.Object otherRules)
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.
- Overrides:
equals
in classjava.lang.Object
- Parameters:
otherRules
- the other rules, null returns false- Returns:
- true if this rules is the same as that specified
-
hashCode
public abstract int hashCode()
Returns a suitable hash code.- Overrides:
hashCode
in classjava.lang.Object
- Returns:
- the hash code
-
-