Class ZoneRules

java.lang.Object
javax.time.calendar.zone.ZoneRules
Direct Known Subclasses:
FixedZoneRules, StandardZoneRules

public abstract class ZoneRules extends 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 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 Details

    • ZoneRules

      protected ZoneRules()
      Constructor for subclasses.
  • Method Details

    • 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(Object object, String errorMessage)
      Validates that the input value is not null.
      Parameters:
      object - the object to check
      errorMessage - 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 and OffsetTime are used in preference to fixed offset time-zones in ZonedDateTime.

      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.
      The third case, a gap in the local time-line, cannot be returned by this method as an instant will always represent a valid point and cannot be in a gap. The returned object provides information about the offset or overlap and it is vital to check 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.
      The returned object provides this information and it is vital to check 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:
      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:
      UnsupportedOperationException - if the implementation cannot return this information - the default 'TZDB' can return this information
    • getTransitions

      public abstract 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:
      UnsupportedOperationException - if the implementation cannot return this information - the default 'TZDB' can return this information
    • getTransitionRules

      public abstract 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 of ZoneOffsetTransitionRule 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

      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(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 class 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 class Object
      Returns:
      the hash code