Summary

Clarify the implementation requirements (@implSpec sections) of the specifications of the reversed methods of Deque, List, SortedMap, and SortedSet. This request is for JDK 21 and 22.

Problem

The current implementation requirements merely say that the returned reverse-ordered view delegates its operations to the backing collection. This seems to imply that calling foo on the view results in a call to foo on the underlying collection. This isn't correct, of course (since the view is reversed, after all) but it needs to be clarified.

Solution

The obvious revision is to specify that a call to a method on the view results in a call to the appropriate method of the backing collection, but with the opposite orientation. This is true, but only for some methods. For example, a call to getFirst on the view results in a call to getLast on the backing collection. However, this isn't true for all methods. For example, calling reversed on the view simply returns the backing collection. This ought to be specified.

Other methods, however, cannot be specified so simply. For example, consider addAll. This takes all the elements from its argument collection, in encounter order, and adds them at the end of the encounter order of the receiver. If called on a reversed view, it needs to take the elements from the argument collection in reverse encounter order and add them at the front of the backing collection. There are many different ways to do this, and we don't want to specify any particular way. This is true of many of the complex collection operations, such as spliterator. For these operations, we require only that the default implementation result in calls to public methods on the backing collection, but we also state that the exact behaviors in calling those public methods is unspecified.

Specification

Deque.reversed() --

      * @implSpec
-     * The implementation in this interface returns an instance of a reverse-ordered
-     * Deque that delegates its operations to this Deque.
+     * The implementation in this interface returns a reverse-ordered Deque
+     * view. The {@code reversed()} method of the view returns a reference
+     * 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.
      *
      * @return a reverse-ordered view of this collection, as a {@code Deque}
      * @since 21

List.reversed() --

      * @implSpec
-     * The implementation in this interface returns an instance of a reverse-ordered
-     * List that delegates its operations to this List.
+     * The implementation in this interface returns a reverse-ordered List
+     * view. The {@code reversed()} method of the view returns a reference
+     * 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.
      *
      * @return a reverse-ordered view of this collection, as a {@code List}
      * @since 21

SortedMap.reversed() --

      * @implSpec
-     * The implementation in this interface returns an instance of a reverse-ordered
-     * SortedMap that delegates its operations to this SortedMap.
+     * The implementation in this interface returns a reverse-ordered SortedMap
+     * view. The {@code reversed()} method of the view returns a reference
+     * 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.
      *
      * @return a reverse-ordered view of this map, as a {@code SortedMap}
      * @since 21

SortedSet.reversed() --

      * @implSpec
-     * The implementation in this interface returns an instance of a reverse-ordered
-     * SortedSet that delegates its operations to this SortedSet.
+     * The implementation in this interface returns a reverse-ordered SortedSet
+     * view. The {@code reversed()} method of the view returns a reference
+     * 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.
      *
      * @return a reverse-ordered view of this collection, as a {@code SortedSet}
      * @since 21