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

additional clarifications to reversed() default methods' implementation requirements

    XMLWordPrintable

Details

    • CSR
    • Resolution: Approved
    • P4
    • 22
    • core-libs
    • None
    • behavioral
    • minimal
    • Java API
    • SE

    Description

      Summary

      Some text in the implementation specifications of several interfaces appears to be testable assertions, when it was intended to be informative examples.

      Problem

      The implementation specifications (@implSpec) sections of the specifications for the reversed() methods of Deque, List, SortedMap, and SortedSet contain wording that makes it seem to be a normative requirement that order-sensitive operations delegate to the corresponding opposite-orientation method of the backing collection. This was intended to be general, informative description, not normative requirements.

      Solution

      Adjust the wording to make it clear that the statements are intended to be informative.

      Specification

      java.util.Deque reversed() @implSpec:

            * to this Deque. Other operations on the view are implemented via calls to
            * public methods on this Deque. The exact relationship between calls on the
            * view and calls on this Deque is unspecified. However, order-sensitive
      -     * operations generally delegate to the appropriate method with the opposite
      -     * orientation. For example, calling {@code getFirst} on the view results in
      -     * a call to {@code getLast} on this Deque.
      +     * operations generally behave as if they delegate to the appropriate method
      +     * with the opposite orientation. For example, calling {@code getFirst} on
      +     * the view might result in a call to {@code getLast} on this Deque.
            *
            * @return a reverse-ordered view of this collection, as a {@code Deque}
            * @since 21

      java.util.List reversed() @implSpec:

            * to this List. Other operations on the view are implemented via calls to
            * public methods on this List. The exact relationship between calls on the
            * view and calls on this List is unspecified. However, order-sensitive
      -     * operations generally delegate to the appropriate method with the opposite
      -     * orientation. For example, calling {@code getFirst} on the view results in
      -     * a call to {@code getLast} on this List.
      +     * operations generally behave as if they delegate to the appropriate method
      +     * with the opposite orientation. For example, calling {@code getFirst} on
      +     * the view might result in a call to {@code getLast} on this List.
            *
            * @return a reverse-ordered view of this collection, as a {@code List}
            * @since 21

      java.util.SortedMap reversed() @implSpec:

            * to this SortedMap. Other operations on the view are implemented via calls to
            * public methods on this SortedMap. The exact relationship between calls on the
            * view and calls on this SortedMap is unspecified. However, order-sensitive
      -     * operations generally delegate to the appropriate method with the opposite
      -     * orientation. For example, calling {@code firstEntry} on the view results in
      -     * a call to {@code lastEntry} on this SortedMap.
      +     * operations generally behave as if they delegate to the appropriate method
      +     * with the opposite orientation. For example, calling {@code firstEntry} on
      +     * the view might result in a call to {@code lastEntry} on this SortedMap.
            *
            * @return a reverse-ordered view of this map, as a {@code SortedMap}
            * @since 21

      java.util.SortedSet reversed() @implSpec:

            * to this SortedSet. Other operations on the view are implemented via calls to
            * public methods on this SortedSet. The exact relationship between calls on the
            * view and calls on this SortedSet is unspecified. However, order-sensitive
      -     * operations generally delegate to the appropriate method with the opposite
      -     * orientation. For example, calling {@code getFirst} on the view results in
      -     * a call to {@code getLast} on this SortedSet.
      +     * operations generally behave as if they delegate to the appropriate method
      +     * with the opposite orientation. For example, calling {@code getFirst} on the
      +     * view might result in a call to {@code getLast} on this SortedSet.
            *
            * @return a reverse-ordered view of this collection, as a {@code SortedSet}
            * @since 21

      Attachments

        Issue Links

          Activity

            People

              smarks Stuart Marks
              smarks Stuart Marks
              Brent Christian
              Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved: