Package org.threeten.bp.zone

Class StandardZoneRules

  • All Implemented Interfaces:
    java.io.Serializable
    final class StandardZoneRules
extends ZoneRules
implements java.io.Serializable
    The rules describing how the zone offset varies through the year and historically.

    This class is used by the TZDB time-zone rules.

    Specification for implementors

    This class is immutable and thread-safe.

    • Field Detail

      • serialVersionUID

        private static final long serialVersionUID
        Serialization version.
        See Also:
        Constant Field Values

      • LAST_CACHED_YEAR

        private static final int LAST_CACHED_YEAR
        The last year to have its transitions cached.
        See Also:
        Constant Field Values

      • standardTransitions

        private final long[] standardTransitions
        The transitions between standard offsets (epoch seconds), sorted.

      • standardOffsets

        private final ZoneOffset[] standardOffsets
        The standard offsets.

      • savingsInstantTransitions

        private final long[] savingsInstantTransitions
        The transitions between instants (epoch seconds), sorted.

      • savingsLocalTransitions

        private final LocalDateTime[] savingsLocalTransitions
        The transitions between local date-times, sorted. This is a paired array, where the first entry is the start of the transition and the second entry is the end of the transition.

      • wallOffsets

        private final ZoneOffset[] wallOffsets
        The wall offsets.

      • lastRulesCache

        private final java.util.concurrent.ConcurrentMap<java.lang.Integer,​ZoneOffsetTransition[]> lastRulesCache
        The map of recent transitions.

    • Constructor Detail

      • StandardZoneRules

        StandardZoneRules​(ZoneOffset baseStandardOffset,
                  ZoneOffset baseWallOffset,
                  java.util.List<ZoneOffsetTransition> standardOffsetTransitionList,
                  java.util.List<ZoneOffsetTransition> transitionList,
                  java.util.List<ZoneOffsetTransitionRule> lastRules)
        Creates an instance.
        Parameters:
        baseStandardOffset - the standard offset to use before legal rules were set, not null
        baseWallOffset - the wall offset to use before legal rules were set, not null
        standardOffsetTransitionList - the list of changes to the standard offset, not null
        transitionList - the list of transitions, not null
        lastRules - the recurring last rules, size 15 or less, not null

      • StandardZoneRules

        private StandardZoneRules​(long[] standardTransitions,
                          ZoneOffset[] standardOffsets,
                          long[] savingsInstantTransitions,
                          ZoneOffset[] wallOffsets,
                          ZoneOffsetTransitionRule[] lastRules)
        Constructor.
        Parameters:
        standardTransitions - the standard transitions, not null
        standardOffsets - the standard offsets, not null
        savingsInstantTransitions - the standard transitions, not null
        wallOffsets - the wall offsets, not null
        lastRules - the recurring last rules, size 15 or less, not null

    • Method Detail

      • writeReplace

        private java.lang.Object writeReplace()
        Uses a serialization delegate.
        Returns:
        the replacing object, not null

      • writeExternal

        void writeExternal​(java.io.DataOutput out)
            throws java.io.IOException
        Writes the state to the stream.
        Parameters:
        out - the output stream, not null
        Throws:
        java.io.IOException - if an error occurs

      • readExternal

        static StandardZoneRules readExternal​(java.io.DataInput in)
                               throws java.io.IOException,
                                      java.lang.ClassNotFoundException
        Reads the state from the stream.
        Parameters:
        in - the input stream, not null
        Returns:
        the created object, not null
        Throws:
        java.io.IOException - if an error occurs
        java.lang.ClassNotFoundException

      • isFixedOffset

        public boolean isFixedOffset()
        Description copied from class: ZoneRules
        Checks of the zone rules are fixed, such that the offset never varies.
        Specified by:
        isFixedOffset in class ZoneRules
        Returns:
        true if the time-zone is fixed and the offset never changes

      • getOffset

        public ZoneOffset getOffset​(Instant instant)
        Description copied from class: ZoneRules
        Gets the offset applicable at the specified instant in these rules.

        The mapping from an instant to an offset is simple, there is only one valid offset for each instant. This method returns that offset.

        Specified by:
        getOffset in class ZoneRules
        Parameters:
        instant - the instant to find the offset for, not null, but null may be ignored if the rules have a single offset for all instants
        Returns:
        the offset, not null

      • getOffset

        public ZoneOffset getOffset​(LocalDateTime localDateTime)
        Description copied from class: ZoneRules
        Gets a suitable offset for the specified local date-time in these rules.

        The mapping from a local date-time to an offset is not straightforward. There are three cases:

        • Normal, with one valid offset. For the vast majority of the year, the normal case applies, where there is a single valid offset for the local date-time.
        • Gap, with zero valid offsets. This is when clocks jump forward typically due to the spring daylight savings change from "winter" to "summer". In a gap there are local date-time values with no valid offset.
        • Overlap, with two valid offsets. This is when clocks are set back typically due to the autumn daylight savings change from "summer" to "winter". In an overlap there are local date-time values with two valid offsets.

        Thus, for any given local date-time there can be zero, one or two valid offsets. This method returns the single offset in the Normal case, and in the Gap or Overlap case it returns the offset before the transition.

        Since, in the case of Gap and Overlap, the offset returned is a "best" value, rather than the "correct" value, it should be treated with care. Applications that care about the correct offset should use a combination of this method, ZoneRules.getValidOffsets(LocalDateTime) and ZoneRules.getTransition(LocalDateTime).

        Specified by:
        getOffset in class ZoneRules
        Parameters:
        localDateTime - the local date-time to query, not null, but null may be ignored if the rules have a single offset for all instants
        Returns:
        the best available offset for the local date-time, not null

      • getValidOffsets

        public java.util.List<ZoneOffset> getValidOffsets​(LocalDateTime localDateTime)
        Description copied from class: ZoneRules
        Gets the offset applicable at the specified local date-time in these rules.

        The mapping from a local date-time to an offset is not straightforward. There are three cases:

        • Normal, with one valid offset. For the vast majority of the year, the normal case applies, where there is a single valid offset for the local date-time.
        • Gap, with zero valid offsets. This is when clocks jump forward typically due to the spring daylight savings change from "winter" to "summer". In a gap there are local date-time values with no valid offset.
        • Overlap, with two valid offsets. This is when clocks are set back typically due to the autumn daylight savings change from "summer" to "winter". In an overlap there are local date-time values with two valid offsets.

        Thus, for any given local date-time there can be zero, one or two valid offsets. This method returns that list of valid offsets, which is a list of size 0, 1 or 2. In the case where there are two offsets, the earlier offset is returned at index 0 and the later offset at index 1.

        There are various ways to handle the conversion from a LocalDateTime. One technique, using this method, would be: 

          List validOffsets = rules.getOffset(localDT);
  if (validOffsets.size() == 1) {
    // Normal case: only one valid offset
    zoneOffset = validOffsets.get(0);
  } else {
    // Gap or Overlap: determine what to do from transition (which will be non-null)
    ZoneOffsetTransition trans = rules.getTransition(localDT);
  }

        In theory, it is possible for there to be more than two valid offsets. This would happen if clocks to be put back more than once in quick succession. This has never happened in the history of time-zones and thus has no special handling. However, if it were to happen, then the list would return more than 2 entries.

        Specified by:
        getValidOffsets in class ZoneRules
        Parameters:
        localDateTime - the local date-time to query for valid offsets, not null, but null may be ignored if the rules have a single offset for all instants
        Returns:
        the list of valid offsets, may be immutable, not null

      • getTransition

        public ZoneOffsetTransition getTransition​(LocalDateTime localDateTime)
        Description copied from class: ZoneRules
        Gets the offset transition applicable at the specified local date-time in these rules.

        The mapping from a local date-time to an offset is not straightforward. There are three cases:

        • Normal, with one valid offset. For the vast majority of the year, the normal case applies, where there is a single valid offset for the local date-time.
        • Gap, with zero valid offsets. This is when clocks jump forward typically due to the spring daylight savings change from "winter" to "summer". In a gap there are local date-time values with no valid offset.
        • Overlap, with two valid offsets. This is when clocks are set back typically due to the autumn daylight savings change from "summer" to "winter". In an overlap there are local date-time values with two valid offsets.

        A transition is used to model the cases of a Gap or Overlap. The Normal case will return null.

        There are various ways to handle the conversion from a LocalDateTime. One technique, using this method, would be: 

          ZoneOffsetTransition trans = rules.getTransition(localDT);
  if (trans == null) {
    // Gap or Overlap: determine what to do from transition
  } else {
    // Normal case: only one valid offset
    zoneOffset = rule.getOffset(localDT);
  }
        Specified by:
        getTransition in class ZoneRules
        Parameters:
        localDateTime - the local date-time to query for offset transition, not null, but null may be ignored if the rules have a single offset for all instants
        Returns:
        the offset transition, null if the local date-time is not in transition

      • getOffsetInfo

        private java.lang.Object getOffsetInfo​(LocalDateTime dt)

      • findOffsetInfo

        private java.lang.Object findOffsetInfo​(LocalDateTime dt,
                                        ZoneOffsetTransition trans)
        Finds the offset info for a local date-time and transition.
        Parameters:
        dt - the date-time, not null
        trans - the transition, not null
        Returns:
        the offset info, not null

      • isValidOffset

        public boolean isValidOffset​(LocalDateTime localDateTime,
                             ZoneOffset offset)
        Description copied from class: ZoneRules
        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.

        Specified by:
        isValidOffset in class ZoneRules
        Parameters:
        localDateTime - the date-time to check, not null, but null may be ignored if the rules have a single offset for all instants
        offset - the offset to check, null returns false
        Returns:
        true if the offset date-time is valid for these rules

      • findTransitionArray

        private ZoneOffsetTransition[] findTransitionArray​(int year)
        Finds the appropriate transition array for the given year.
        Parameters:
        year - the year, not null
        Returns:
        the transition array, not null

      • getStandardOffset

        public ZoneOffset getStandardOffset​(Instant instant)
        Description copied from class: ZoneRules
        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 saving time is applied. This is typically the offset applicable during winter.

        Specified by:
        getStandardOffset in class ZoneRules
        Parameters:
        instant - the instant to find the offset information for, not null, but null may be ignored if the rules have a single offset for all instants
        Returns:
        the standard offset, not null

      • getDaylightSavings

        public Duration getDaylightSavings​(Instant instant)
        Description copied from class: ZoneRules
        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. Typically the amount is zero during winter and one hour during summer. Time-zones are second-based, so the nanosecond part of the duration will be zero.

        Specified by:
        getDaylightSavings in class ZoneRules
        Parameters:
        instant - the instant to find the daylight savings for, not null, but null may be ignored if the rules have a single offset for all instants
        Returns:
        the difference between the standard and actual offset, not null

      • isDaylightSavings

        public boolean isDaylightSavings​(Instant instant)
        Description copied from class: ZoneRules
        Checks if the specified instant is in daylight savings.

        This checks if the standard and actual offsets are the same at the specified instant.

        Specified by:
        isDaylightSavings in class ZoneRules
        Parameters:
        instant - the instant to find the offset information for, not null, but null may be ignored if the rules have a single offset for all instants
        Returns:
        the standard offset, not null

      • nextTransition

        public ZoneOffsetTransition nextTransition​(Instant instant)
        Description copied from class: ZoneRules
        Gets the next transition after the specified instant.

        This returns details of the next transition after the specified instant. For example, if the instant represents a point where "Summer" daylight savings time applies, then the method will return the transition to the next "Winter" time.

        Specified by:
        nextTransition in class ZoneRules
        Parameters:
        instant - the instant to get the next transition after, not null, but null may be ignored if the rules have a single offset for all instants
        Returns:
        the next transition after the specified instant, null if this is after the last transition

      • previousTransition

        public ZoneOffsetTransition previousTransition​(Instant instant)
        Description copied from class: ZoneRules
        Gets the previous transition before the specified instant.

        This returns details of the previous transition after the specified instant. For example, if the instant represents a point where "summer" daylight saving time applies, then the method will return the transition from the previous "winter" time.

        Specified by:
        previousTransition in class ZoneRules
        Parameters:
        instant - the instant to get the previous transition after, not null, but null may be ignored if the rules have a single offset for all instants
        Returns:
        the previous transition after the specified instant, null if this is before the first transition

      • findYear

        private int findYear​(long epochSecond,
                     ZoneOffset offset)

      • getTransitions

        public java.util.List<ZoneOffsetTransition> getTransitions()
        Description copied from class: ZoneRules
        Gets the complete list of fully defined transitions.

        The complete set of transitions for this rules instance is defined by this method and ZoneRules.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 and for any time-zone where there has only ever been a single offset. The list will also be empty if the transition rules are unknown.

        Specified by:
        getTransitions in class ZoneRules
        Returns:
        an immutable list of fully defined transitions, not null

      • getTransitionRules

        public java.util.List<ZoneOffsetTransitionRule> getTransitionRules()
        Description copied from class: ZoneRules
        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 ZoneRules.getTransitions(). This method returns instances of ZoneOffsetTransitionRule that define an algorithm for when transitions will occur.

        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 saving 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.

        The list will be empty for fixed offset rules and for any time-zone where there is no daylight saving time. The list will also be empty if the transition rules are unknown.

        Specified by:
        getTransitionRules in class ZoneRules
        Returns:
        an immutable list of transition rules, not null

      • equals

        public boolean equals​(java.lang.Object obj)
        Description copied from class: ZoneRules
        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 local 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.

        Specified by:
        equals in class ZoneRules
        Parameters:
        obj - the other rules, null returns false
        Returns:
        true if this rules is the same as that specified

      • hashCode

        public int hashCode()
        Description copied from class: ZoneRules
        Returns a suitable hash code given the definition of #equals.
        Specified by:
        hashCode in class ZoneRules
        Returns:
        the hash code

      • toString

        public java.lang.String toString()
        Returns a string describing this object.
        Overrides:
        toString in class java.lang.Object
        Returns:
        a string for debugging, not null