Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8172165

java.time.zone javadoc error in ZoneRules::getTransition

    Details

      Description

      A DESCRIPTION OF THE PROBLEM :
      The documentation contradicts itself. The code example is wrong, content of if/else statement needs to be switched.

      EXPECTED VERSUS ACTUAL BEHAVIOR :
      EXPECTED -


          /**
           * Gets the offset transition applicable at the specified local date-time in these rules.
           * <p>
           * The mapping from a local date-time to an offset is not straightforward.
           * There are three cases:
           * <ul>
           * <li>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.</li>
           * <li>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.</li>
           * <li>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.</li>
           * </ul>
           * A transition is used to model the cases of a Gap or Overlap.
           * The Normal case will return null.
           * <p>
           * There are various ways to handle the conversion from a {@code LocalDateTime}.
           * One technique, using this method, would be:
           * <pre>
           * ZoneOffsetTransition trans = rules.getTransition(localDT);
           * if (trans == null) {
           * // Normal case: only one valid offset
           * zoneOffset = rule.getOffset(localDT);
           * } else {
           * // Gap or Overlap: determine what to do from transition
           * }
           * </pre>
           *
           * @param 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
           * @return the offset transition, null if the local date-time is not in transition
           */
      ACTUAL -


          /**
           * Gets the offset transition applicable at the specified local date-time in these rules.
           * <p>
           * The mapping from a local date-time to an offset is not straightforward.
           * There are three cases:
           * <ul>
           * <li>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.</li>
           * <li>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.</li>
           * <li>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.</li>
           * </ul>
           * A transition is used to model the cases of a Gap or Overlap.
           * The Normal case will return null.
           * <p>
           * There are various ways to handle the conversion from a {@code LocalDateTime}.
           * One technique, using this method, would be:
           * <pre>
           * 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);
           * }
           * </pre>
           *
           * @param 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
           * @return the offset transition, null if the local date-time is not in transition
           */

      URL OF FAULTY DOCUMENTATION :
      https://docs.oracle.com/javase/8/docs/api/java/time/zone/ZoneRules.html#getTransition-java.time.LocalDateTime-

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                aroy Abhijit Roy (Inactive)
                Reporter:
                webbuggrp Webbug Group
              • Votes:
                0 Vote for this issue
                Watchers:
                5 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: