diff --git a/src/java.base/share/classes/java/util/ArrayList.java b/src/java.base/share/classes/java/util/ArrayList.java index 760c331aa3f..1f27572ef16 100644 --- a/src/java.base/share/classes/java/util/ArrayList.java +++ b/src/java.base/share/classes/java/util/ArrayList.java @@ -430,6 +430,9 @@ public class ArrayList extends AbstractList /** * {@inheritDoc} + * + * @throws NoSuchElementException {@inheritDoc} + * @since 21 */ public E getFirst() { if (size == 0) { @@ -441,6 +444,9 @@ public class ArrayList extends AbstractList /** * {@inheritDoc} + * + * @throws NoSuchElementException {@inheritDoc} + * @since 21 */ public E getLast() { int last = size - 1; @@ -516,6 +522,8 @@ public class ArrayList extends AbstractList /** * {@inheritDoc} + * + * @since 21 */ public void addFirst(E element) { add(0, element); @@ -523,6 +531,8 @@ public class ArrayList extends AbstractList /** * {@inheritDoc} + * + * @since 21 */ public void addLast(E element) { add(element); @@ -549,6 +559,9 @@ public class ArrayList extends AbstractList /** * {@inheritDoc} + * + * @throws NoSuchElementException {@inheritDoc} + * @since 21 */ public E removeFirst() { if (size == 0) { @@ -563,6 +576,9 @@ public class ArrayList extends AbstractList /** * {@inheritDoc} + * + * @throws NoSuchElementException {@inheritDoc} + * @since 21 */ public E removeLast() { int last = size - 1; diff --git a/src/java.base/share/classes/java/util/Collections.java b/src/java.base/share/classes/java/util/Collections.java index d0805d83828..f45d297f300 100644 --- a/src/java.base/share/classes/java/util/Collections.java +++ b/src/java.base/share/classes/java/util/Collections.java @@ -371,7 +371,7 @@ public class Collections { * * @apiNote * This method mutates the specified list in-place. To obtain a - * reversed-ordered view of a list without mutating it, use the + * reverse-ordered view of a list without mutating it, use the * {@link List#reversed List.reversed} method. * * @param list the list whose elements are to be reversed. @@ -5994,14 +5994,14 @@ public class Collections { * in that the map's {@code removeEldestEntry} is overridden to provide * an eviction policy, which is not possible with a {@code LinkedHashSet}. * - * 
{@code
+     * {@snippet :
      *     SequencedSet set = Collections.newSequencedSetFromMap(
      *         new LinkedHashMap() {
      *             protected boolean removeEldestEntry(Map.Entry e) {
      *                 return this.size() > 5;
      *             }
      *        });
-     * }
+ * } * * @param the class of the map keys and of the objects in the * returned set @@ -6067,8 +6067,8 @@ public class Collections { * * @apiNote * This method provides a view that inverts the sense of certain operations, - * but it doesn't reverse the encounter order. To obtain a reversed-ordered - * view, use the {@link Deque#reversed Deque::reversed} method. + * but it doesn't reverse the encounter order. To obtain a reverse-ordered + * view, use the {@link Deque#reversed Deque.reversed} method. * * @param the class of the objects in the deque * @param deque the deque diff --git a/src/java.base/share/classes/java/util/Deque.java b/src/java.base/share/classes/java/util/Deque.java index 474f451c082..13a2e150d97 100644 --- a/src/java.base/share/classes/java/util/Deque.java +++ b/src/java.base/share/classes/java/util/Deque.java @@ -617,7 +617,7 @@ public interface Deque extends Queue, SequencedCollection { * {@inheritDoc} * * @implSpec - * The implementation in this class returns an instance of a reverse-ordered + * The implementation in this interface returns an instance of a reverse-ordered * Deque that delegates its operations to this Deque. * * @return a reverse-ordered view of this collection, as a {@code Deque} diff --git a/src/java.base/share/classes/java/util/LinkedHashSet.java b/src/java.base/share/classes/java/util/LinkedHashSet.java index 94ad9b43312..fd9b52e2589 100644 --- a/src/java.base/share/classes/java/util/LinkedHashSet.java +++ b/src/java.base/share/classes/java/util/LinkedHashSet.java @@ -256,6 +256,8 @@ public class LinkedHashSet /** * {@inheritDoc} + * + * @throws NoSuchElementException {@inheritDoc} * @since 21 */ public E getFirst() { @@ -264,6 +266,8 @@ public class LinkedHashSet /** * {@inheritDoc} + * + * @throws NoSuchElementException {@inheritDoc} * @since 21 */ public E getLast() { @@ -273,6 +277,7 @@ public class LinkedHashSet /** * {@inheritDoc} * + * @throws NoSuchElementException {@inheritDoc} * @since 21 */ public E removeFirst() { @@ -281,6 +286,8 @@ public class LinkedHashSet /** * {@inheritDoc} + * + * @throws NoSuchElementException {@inheritDoc} * @since 21 */ public E removeLast() { diff --git a/src/java.base/share/classes/java/util/List.java b/src/java.base/share/classes/java/util/List.java index 680dd129ef5..e9576455ca7 100644 --- a/src/java.base/share/classes/java/util/List.java +++ b/src/java.base/share/classes/java/util/List.java @@ -786,8 +786,10 @@ public interface List extends SequencedCollection { * {@inheritDoc} * * @implSpec - * The implementation in this class calls {@code add(0, e)}. + * The implementation in this interface calls {@code add(0, e)}. * + * @throws NullPointerException {@inheritDoc} + * @throws UnsupportedOperationException {@inheritDoc} * @since 21 */ default void addFirst(E e) { @@ -798,8 +800,10 @@ public interface List extends SequencedCollection { * {@inheritDoc} * * @implSpec - * The implementation in this class calls {@code add(e)}. + * The implementation in this interface calls {@code add(e)}. * + * @throws NullPointerException {@inheritDoc} + * @throws UnsupportedOperationException {@inheritDoc} * @since 21 */ default void addLast(E e) { @@ -810,9 +814,10 @@ public interface List extends SequencedCollection { * {@inheritDoc} * * @implSpec - * If this List is not empty, the implementation in this class returns the result + * If this List is not empty, the implementation in this interface returns the result * of calling {@code get(0)}. Otherwise, it throws {@code NoSuchElementException}. * + * @throws NoSuchElementException {@inheritDoc} * @since 21 */ default E getFirst() { @@ -827,9 +832,10 @@ public interface List extends SequencedCollection { * {@inheritDoc} * * @implSpec - * If this List is not empty, the implementation in this class returns the result + * If this List is not empty, the implementation in this interface returns the result * of calling {@code get(size() - 1)}. Otherwise, it throws {@code NoSuchElementException}. * + * @throws NoSuchElementException {@inheritDoc} * @since 21 */ default E getLast() { @@ -844,9 +850,11 @@ public interface List extends SequencedCollection { * {@inheritDoc} * * @implSpec - * If this List is not empty, the implementation in this class returns the result + * If this List is not empty, the implementation in this interface returns the result * of calling {@code remove(0)}. Otherwise, it throws {@code NoSuchElementException}. * + * @throws NoSuchElementException {@inheritDoc} + * @throws UnsupportedOperationException {@inheritDoc} * @since 21 */ default E removeFirst() { @@ -861,9 +869,11 @@ public interface List extends SequencedCollection { * {@inheritDoc} * * @implSpec - * If this List is not empty, the implementation in this class returns the result + * If this List is not empty, the implementation in this interface returns the result * of calling {@code remove(size() - 1)}. Otherwise, it throws {@code NoSuchElementException}. * + * @throws NoSuchElementException {@inheritDoc} + * @throws UnsupportedOperationException {@inheritDoc} * @since 21 */ default E removeLast() { @@ -878,7 +888,7 @@ public interface List extends SequencedCollection { * {@inheritDoc} * * @implSpec - * The implementation in this class returns an instance of a reverse-ordered + * The implementation in this interface returns an instance of a reverse-ordered * List that delegates its operations to this List. * * @return a reverse-ordered view of this collection, as a {@code List} diff --git a/src/java.base/share/classes/java/util/NavigableMap.java b/src/java.base/share/classes/java/util/NavigableMap.java index 7871523ba1b..92abc278dd8 100644 --- a/src/java.base/share/classes/java/util/NavigableMap.java +++ b/src/java.base/share/classes/java/util/NavigableMap.java @@ -432,10 +432,12 @@ public interface NavigableMap extends SortedMap { /** * {@inheritDoc} + *

+ * This method is equivalent to {@link #descendingMap descendingMap}. * * @implSpec - * The implementation in this class returns the result of calling the - * {@link #descendingMap descendingMap} method. + * The implementation in this interface returns the result of calling the + * {@code descendingMap} method. * * @return a reverse-ordered view of this map, as a {@code NavigableMap} * @since 21 diff --git a/src/java.base/share/classes/java/util/NavigableSet.java b/src/java.base/share/classes/java/util/NavigableSet.java index 0e27dd088e4..8d7da4eddd3 100644 --- a/src/java.base/share/classes/java/util/NavigableSet.java +++ b/src/java.base/share/classes/java/util/NavigableSet.java @@ -325,9 +325,11 @@ public interface NavigableSet extends SortedSet { * {@inheritDoc} * * @implSpec - * If this set is not empty, the implementation in this class returns the result of calling + * If this set is not empty, the implementation in this interface returns the result of calling * the {@code pollFirst} method. Otherwise, it throws {@code NoSuchElementException}. * + * @throws NoSuchElementException {@inheritDoc} + * @throws UnsupportedOperationException {@inheritDoc} * @since 21 */ default E removeFirst() { @@ -342,9 +344,11 @@ public interface NavigableSet extends SortedSet { * {@inheritDoc} * * @implSpec - * If this set is not empty, the implementation in this class returns the result of calling + * If this set is not empty, the implementation in this interface returns the result of calling * the {@code pollLast} method. Otherwise, it throws {@code NoSuchElementException}. * + * @throws NoSuchElementException {@inheritDoc} + * @throws UnsupportedOperationException {@inheritDoc} * @since 21 */ default E removeLast() { @@ -361,7 +365,7 @@ public interface NavigableSet extends SortedSet { * This method is equivalent to {@link #descendingSet descendingSet}. * * @implSpec - * The implementation in this class returns the result of calling the + * The implementation in this interface returns the result of calling the * {@code descendingSet} method. * * @return a reverse-ordered view of this collection, as a {@code NavigableSet} diff --git a/src/java.base/share/classes/java/util/ReverseOrderDequeView.java b/src/java.base/share/classes/java/util/ReverseOrderDequeView.java index 8c317242df7..a580ad8f7db 100644 --- a/src/java.base/share/classes/java/util/ReverseOrderDequeView.java +++ b/src/java.base/share/classes/java/util/ReverseOrderDequeView.java @@ -163,8 +163,7 @@ class ReverseOrderDequeView implements Deque { @SuppressWarnings("unchecked") public T[] toArray(T[] a) { - // TODO can probably optimize this - return toArray(i -> (T[]) java.lang.reflect.Array.newInstance(a.getClass().getComponentType(), i)); + return ArraysSupport.toArrayReversed(base, a); } public T[] toArray(IntFunction generator) { diff --git a/src/java.base/share/classes/java/util/ReverseOrderListView.java b/src/java.base/share/classes/java/util/ReverseOrderListView.java index 17457d85fb0..027979fd40f 100644 --- a/src/java.base/share/classes/java/util/ReverseOrderListView.java +++ b/src/java.base/share/classes/java/util/ReverseOrderListView.java @@ -285,8 +285,7 @@ class ReverseOrderListView implements List { @SuppressWarnings("unchecked") public T[] toArray(T[] a) { - // TODO can probably optimize this - return toArray(i -> (T[]) java.lang.reflect.Array.newInstance(a.getClass().getComponentType(), i)); + return ArraysSupport.toArrayReversed(base, a); } public T[] toArray(IntFunction generator) { diff --git a/src/java.base/share/classes/java/util/ReverseOrderSortedMapView.java b/src/java.base/share/classes/java/util/ReverseOrderSortedMapView.java index 8a58de6c567..404950e8fd5 100644 --- a/src/java.base/share/classes/java/util/ReverseOrderSortedMapView.java +++ b/src/java.base/share/classes/java/util/ReverseOrderSortedMapView.java @@ -100,6 +100,9 @@ class ReverseOrderSortedMapView extends AbstractMap implements Sorte // inherit add(), which throws UOE public Iterator iterator() { return descendingKeyIterator(base); } public int size() { return base.size(); } + public void clear() { base.keySet().clear(); } + public boolean contains(Object o) { return base.keySet().contains(o); } + public boolean remove(Object o) { return base.keySet().remove(o); } }; } @@ -108,6 +111,9 @@ class ReverseOrderSortedMapView extends AbstractMap implements Sorte // inherit add(), which throws UOE public Iterator iterator() { return descendingValueIterator(base); } public int size() { return base.size(); } + public void clear() { base.values().clear(); } + public boolean contains(Object o) { return base.values().contains(o); } + public boolean remove(Object o) { return base.values().remove(o); } }; } @@ -116,6 +122,9 @@ class ReverseOrderSortedMapView extends AbstractMap implements Sorte // inherit add(), which throws UOE public Iterator> iterator() { return descendingEntryIterator(base); } public int size() { return base.size(); } + public void clear() { base.entrySet().clear(); } + public boolean contains(Object o) { return base.entrySet().contains(o); } + public boolean remove(Object o) { return base.entrySet().remove(o); } }; } diff --git a/src/java.base/share/classes/java/util/ReverseOrderSortedSetView.java b/src/java.base/share/classes/java/util/ReverseOrderSortedSetView.java index 83781c5f6bc..678c82fc311 100644 --- a/src/java.base/share/classes/java/util/ReverseOrderSortedSetView.java +++ b/src/java.base/share/classes/java/util/ReverseOrderSortedSetView.java @@ -172,8 +172,7 @@ class ReverseOrderSortedSetView implements SortedSet { @SuppressWarnings("unchecked") public T[] toArray(T[] a) { - // TODO can probably optimize this - return toArray(i -> (T[]) java.lang.reflect.Array.newInstance(a.getClass().getComponentType(), i)); + return ArraysSupport.toArrayReversed(base, a); } public T[] toArray(IntFunction generator) { diff --git a/src/java.base/share/classes/java/util/SequencedCollection.java b/src/java.base/share/classes/java/util/SequencedCollection.java index 8948be1b967..54237c7a3f7 100644 --- a/src/java.base/share/classes/java/util/SequencedCollection.java +++ b/src/java.base/share/classes/java/util/SequencedCollection.java @@ -45,8 +45,8 @@ package java.util; * {@link Collection#spliterator spliterator}, {@link Collection#stream stream}, * and all overloads of the {@link Collection#toArray toArray} method. *

- * This interface provides methods to add elements, to retrieve elements, and to remove - * elements at either end of the collection. + * This interface provides methods to add, retrieve, and remove elements at either end + * of the collection. *

* This interface also defines the {@link #reversed reversed} method, which provides * a reverse-ordered view of this collection. @@ -95,7 +95,7 @@ public interface SequencedCollection extends Collection { * this collection, and it will be the first element in encounter order. * * @implSpec - * The implementation in this class always throws {@code UnsupportedOperationException}. + * The implementation in this interface always throws {@code UnsupportedOperationException}. * * @param e the element to be added * @throws NullPointerException if the specified element is null and this @@ -113,7 +113,7 @@ public interface SequencedCollection extends Collection { * this collection, and it will be the last element in encounter order. * * @implSpec - * The implementation in this class always throws {@code UnsupportedOperationException}. + * The implementation in this interface always throws {@code UnsupportedOperationException}. * * @param e the element to be added. * @throws NullPointerException if the specified element is null and this @@ -129,7 +129,7 @@ public interface SequencedCollection extends Collection { * Gets the first element of this collection. * * @implSpec - * The implementation in this class obtains an iterator of this collection, and + * The implementation in this interface obtains an iterator of this collection, and * then it obtains an element by calling the iterator's {@code next} method. Any * {@code NoSuchElementException} thrown is propagated. Otherwise, it returns * the element. @@ -145,7 +145,7 @@ public interface SequencedCollection extends Collection { * Gets the last element of this collection. * * @implSpec - * The implementation in this class obtains an iterator of the reversed view + * The implementation in this interface obtains an iterator of the reversed view * of this collection, and then it obtains an element by calling the iterator's * {@code next} method. Any {@code NoSuchElementException} thrown is propagated. * Otherwise, it returns the element. @@ -161,7 +161,7 @@ public interface SequencedCollection extends Collection { * Removes and returns the first element of this collection (optional operation). * * @implSpec - * The implementation in this class obtains an iterator of this collection, and then + * The implementation in this interface obtains an iterator of this collection, and then * it obtains an element by calling the iterator's {@code next} method. Any * {@code NoSuchElementException} thrown is propagated. It then calls the iterator's * {@code remove} method. Any {@code UnsupportedOperationException} thrown is propagated. @@ -183,7 +183,7 @@ public interface SequencedCollection extends Collection { * Removes and returns the last element of this collection (optional operation). * * @implSpec - * The implementation in this class obtains an iterator of the reversed view of this + * The implementation in this interface obtains an iterator of the reversed view of this * collection, and then it obtains an element by calling the iterator's {@code next} method. * Any {@code NoSuchElementException} thrown is propagated. It then calls the iterator's * {@code remove} method. Any {@code UnsupportedOperationException} thrown is propagated. diff --git a/src/java.base/share/classes/java/util/SequencedMap.java b/src/java.base/share/classes/java/util/SequencedMap.java index 886917f9286..c8f88d004bc 100644 --- a/src/java.base/share/classes/java/util/SequencedMap.java +++ b/src/java.base/share/classes/java/util/SequencedMap.java @@ -43,16 +43,14 @@ package java.util; * {@link #sequencedValues sequencedValues}, * and * {@link #sequencedEntrySet sequencedEntrySet} methods all reflect the encounter order - * of this map. Even though the return values of the - * {@link #keySet keySet}, - * {@link #values values}, and - * {@link #entrySet entrySet} methods are not sequenced types, the elements + * of this map. Even though the return values of the {@code keySet}, {@code values}, and + * {@code entrySet} methods are not sequenced types, the elements * in those view collections do reflect the encounter order of this map. Thus, the * iterators returned by the statements - * 

{@code
+ * {@snippet :
  *     var it1 = sequencedMap.entrySet().iterator();
  *     var it2 = sequencedMap.sequencedEntrySet().iterator();
- * }
+ * } * both provide the mappings of {@code sequencedMap} in that map's encounter order. *

* This interface provides methods to add mappings, to retrieve mappings, and to remove @@ -69,9 +67,9 @@ package java.util; * the mappings in order from the last mapping of this map to the first. In addition, all of * the view collections of the reversed view also reflect the inverse of this map's * encounter order. For example, - * 

{@code
+ * {@snippet :
  *     var itr = sequencedMap.reversed().entrySet().iterator();
- * }
+ * } * provides the mappings of this map in the inverse of the encounter order, that is, from * the last mapping to the first mapping. The availability of the {@code reversed} method, * and its impact on the ordering semantics of all applicable methods and views, allow convenient @@ -101,9 +99,9 @@ package java.util; * Depending upon the implementation, the {@code Entry} instances returned by other * means might or might not be connected to the underlying map. For example, consider * an {@code Entry} obtained in the following manner: - * 
{@code
+ * {@snippet :
  *     var entry = sequencedMap.sequencedEntrySet().getFirst();
- * }
+ * } * It is not specified by this interface whether the {@code setValue} method of the * {@code Entry} thus obtained will update a mapping in the underlying map, or whether * it will throw an exception, or whether changes to the underlying map are visible in @@ -125,8 +123,8 @@ package java.util; public interface SequencedMap extends Map { /** * Returns a reverse-ordered view of this map. - * The encounter order of elements in the returned view is the inverse of the encounter - * order of elements in this map. The reverse ordering affects all order-sensitive operations, + * The encounter order of mappings in the returned view is the inverse of the encounter + * order of mappings in this map. The reverse ordering affects all order-sensitive operations, * including those on the view collections of the returned view. If the implementation permits * modifications to this view, the modifications "write through" to the underlying map. * Changes to the underlying map might or might not be visible in this reversed view, @@ -141,7 +139,7 @@ public interface SequencedMap extends Map { * or {@code null} if the map is empty. * * @implSpec - * The implementation in this class obtains the iterator of this map's entrySet. + * The implementation in this interface obtains the iterator of this map's entrySet. * If the iterator has an element, it returns an unmodifiable copy of that element. * Otherwise, it returns null. * @@ -158,7 +156,7 @@ public interface SequencedMap extends Map { * or {@code null} if the map is empty. * * @implSpec - * The implementation in this class obtains the iterator of the entrySet of this map's + * The implementation in this interface obtains the iterator of the entrySet of this map's * reversed view. If the iterator has an element, it returns an unmodifiable copy of * that element. Otherwise, it returns null. * @@ -175,7 +173,7 @@ public interface SequencedMap extends Map { * or {@code null} if the map is empty (optional operation). * * @implSpec - * The implementation in this class obtains the iterator of this map's entrySet. + * The implementation in this interface obtains the iterator of this map's entrySet. * If the iterator has an element, it calls {@code remove} on the iterator and * then returns an unmodifiable copy of that element. Otherwise, it returns null. * @@ -200,7 +198,7 @@ public interface SequencedMap extends Map { * or {@code null} if the map is empty (optional operation). * * @implSpec - * The implementation in this class obtains the iterator of the entrySet of this map's + * The implementation in this interface obtains the iterator of the entrySet of this map's * reversed view. If the iterator has an element, it calls {@code remove} on the iterator * and then returns an unmodifiable copy of that element. Otherwise, it returns null. * @@ -226,7 +224,7 @@ public interface SequencedMap extends Map { * completes normally, the given mapping will be present in this map, and it will be the * first mapping in this map's encounter order. * - * @implSpec The implementation in this class always throws + * @implSpec The implementation in this interface always throws * {@code UnsupportedOperationException}. * * @param k the key @@ -245,7 +243,7 @@ public interface SequencedMap extends Map { * completes normally, the given mapping will be present in this map, and it will be the * last mapping in this map's encounter order. * - * @implSpec The implementation in this class always throws + * @implSpec The implementation in this interface always throws * {@code UnsupportedOperationException}. * * @param k the key @@ -262,7 +260,7 @@ public interface SequencedMap extends Map { * Returns a {@link SequencedSet} view of this map's keySet. * * @implSpec - * The implementation of this method in this class returns a {@code SequencedSet} + * The implementation in this interface returns a {@code SequencedSet} * implementation that delegates all operations either to this map or to this map's * {@link #keySet}, except for its {@link SequencedSet#reversed reversed} method, * which instead returns the result of calling {@code sequencedKeySet} on this map's @@ -286,7 +284,7 @@ public interface SequencedMap extends Map { * Returns a {@link SequencedCollection} view of this map's values collection. * * @implSpec - * The implementation of this method in this class returns a {@code SequencedCollection} + * The implementation in this interface returns a {@code SequencedCollection} * implementation that delegates all operations either to this map or to this map's * {@link #values} collection, except for its {@link SequencedCollection#reversed reversed} * method, which instead returns the result of calling {@code sequencedValues} on this map's @@ -310,7 +308,7 @@ public interface SequencedMap extends Map { * Returns a {@link SequencedSet} view of this map's entrySet. * * @implSpec - * The implementation of this method in this class returns a {@code SequencedSet} + * The implementation in this interface returns a {@code SequencedSet} * implementation that delegates all operations either to this map or to this map's * {@link #entrySet}, except for its {@link SequencedSet#reversed reversed} method, * which instead returns the result of calling {@code sequencedEntrySet} on this map's diff --git a/src/java.base/share/classes/java/util/SequencedSet.java b/src/java.base/share/classes/java/util/SequencedSet.java index b0ae9991b21..c02bfc123ff 100644 --- a/src/java.base/share/classes/java/util/SequencedSet.java +++ b/src/java.base/share/classes/java/util/SequencedSet.java @@ -26,8 +26,9 @@ package java.util; /** - * A collection that is both a {@link SequencedCollection} and a {@link Set}. As such, it can be - * thought of as either as a {@code Set} that also has a well-defined encounter order, or as a + * A collection that is both a {@link SequencedCollection} and a {@link Set}. As such, + * it can be thought of either as a {@code Set} that also has a well-defined + * encounter order, or as a * {@code SequencedCollection} that also has unique elements. *

* This interface has the same requirements on the {@code equals} and {@code hashCode} diff --git a/src/java.base/share/classes/java/util/SortedMap.java b/src/java.base/share/classes/java/util/SortedMap.java index 8a84228bd11..1af9d59e83e 100644 --- a/src/java.base/share/classes/java/util/SortedMap.java +++ b/src/java.base/share/classes/java/util/SortedMap.java @@ -288,7 +288,7 @@ public interface SortedMap extends SequencedMap { * is not supported. * * @implSpec - * The implementation in this class always throws {@code UnsupportedOperationException}. + * The implementation in this interface always throws {@code UnsupportedOperationException}. * * @throws UnsupportedOperationException always * @since 21 @@ -303,7 +303,7 @@ public interface SortedMap extends SequencedMap { * is not supported. * * @implSpec - * The implementation in this class always throws {@code UnsupportedOperationException}. + * The implementation in this interface always throws {@code UnsupportedOperationException}. * * @throws UnsupportedOperationException always * @since 21 @@ -316,7 +316,7 @@ public interface SortedMap extends SequencedMap { * {@inheritDoc} * * @implSpec - * The implementation in this class returns an instance of a reverse-ordered + * The implementation in this interface returns an instance of a reverse-ordered * SortedMap that delegates its operations to this SortedMap. * * @return a reverse-ordered view of this map, as a {@code SortedMap} diff --git a/src/java.base/share/classes/java/util/SortedSet.java b/src/java.base/share/classes/java/util/SortedSet.java index a168c9fed88..48473a1fed5 100644 --- a/src/java.base/share/classes/java/util/SortedSet.java +++ b/src/java.base/share/classes/java/util/SortedSet.java @@ -270,7 +270,7 @@ public interface SortedSet extends Set, SequencedSet { * is not supported. * * @implSpec - * The implementation in this class always throws {@code UnsupportedOperationException}. + * The implementation in this interface always throws {@code UnsupportedOperationException}. * * @throws UnsupportedOperationException always * @since 21 @@ -285,7 +285,7 @@ public interface SortedSet extends Set, SequencedSet { * is not supported. * * @implSpec - * The implementation in this class always throws {@code UnsupportedOperationException}. + * The implementation in this interface always throws {@code UnsupportedOperationException}. * * @throws UnsupportedOperationException always * @since 21 @@ -298,8 +298,9 @@ public interface SortedSet extends Set, SequencedSet { * {@inheritDoc} * * @implSpec - * The implementation in this class returns the result of calling the {@code first} method. + * The implementation in this interface returns the result of calling the {@code first} method. * + * @throws NoSuchElementException {@inheritDoc} * @since 21 */ default E getFirst() { @@ -310,8 +311,9 @@ public interface SortedSet extends Set, SequencedSet { * {@inheritDoc} * * @implSpec - * The implementation in this class returns the result of calling the {@code last} method. + * The implementation in this interface returns the result of calling the {@code last} method. * + * @throws NoSuchElementException {@inheritDoc} * @since 21 */ default E getLast() { @@ -322,10 +324,12 @@ public interface SortedSet extends Set, SequencedSet { * {@inheritDoc} * * @implSpec - * The implementation in this class calls the {@code first} method to obtain the first + * The implementation in this interface calls the {@code first} method to obtain the first * element, then it calls {@code remove(element)} to remove the element, and then it returns * the element. * + * @throws NoSuchElementException {@inheritDoc} + * @throws UnsupportedOperationException {@inheritDoc} * @since 21 */ default E removeFirst() { @@ -338,10 +342,12 @@ public interface SortedSet extends Set, SequencedSet { * {@inheritDoc} * * @implSpec - * The implementation in this class calls the {@code last} method to obtain the last + * The implementation in this interface calls the {@code last} method to obtain the last * element, then it calls {@code remove(element)} to remove the element, and then it returns * the element. * + * @throws NoSuchElementException {@inheritDoc} + * @throws UnsupportedOperationException {@inheritDoc} * @since 21 */ default E removeLast() { @@ -354,7 +360,7 @@ public interface SortedSet extends Set, SequencedSet { * {@inheritDoc} * * @implSpec - * The implementation in this class returns an instance of a reverse-ordered + * The implementation in this interface returns an instance of a reverse-ordered * SortedSet that delegates its operations to this SortedSet. * * @return a reverse-ordered view of this collection, as a {@code SortedSet} diff --git a/src/java.base/share/classes/java/util/concurrent/CopyOnWriteArrayList.java b/src/java.base/share/classes/java/util/concurrent/CopyOnWriteArrayList.java index 24f9689a417..909621bd5ba 100644 --- a/src/java.base/share/classes/java/util/concurrent/CopyOnWriteArrayList.java +++ b/src/java.base/share/classes/java/util/concurrent/CopyOnWriteArrayList.java @@ -405,6 +405,9 @@ public class CopyOnWriteArrayList /** * {@inheritDoc} + * + * @throws NoSuchElementException {@inheritDoc} + * @since 21 */ public E getFirst() { Object[] es = getArray(); @@ -416,6 +419,9 @@ public class CopyOnWriteArrayList /** * {@inheritDoc} + * + * @throws NoSuchElementException {@inheritDoc} + * @since 21 */ public E getLast() { Object[] es = getArray(); @@ -493,6 +499,8 @@ public class CopyOnWriteArrayList /** * {@inheritDoc} + * + * @since 21 */ public void addFirst(E e) { add(0, e); @@ -500,6 +508,8 @@ public class CopyOnWriteArrayList /** * {@inheritDoc} + * + * @since 21 */ public void addLast(E e) { synchronized (lock) { @@ -536,6 +546,9 @@ public class CopyOnWriteArrayList /** * {@inheritDoc} + * + * @throws NoSuchElementException {@inheritDoc} + * @since 21 */ public E removeFirst() { synchronized (lock) { @@ -548,6 +561,9 @@ public class CopyOnWriteArrayList /** * {@inheritDoc} + * + * @throws NoSuchElementException {@inheritDoc} + * @since 21 */ public E removeLast() { synchronized (lock) { @@ -1713,6 +1729,8 @@ public class CopyOnWriteArrayList * to this list. In addition, modifications to this list will be visible * in the reversed view. Sublists and iterators of the reversed view have * the same restrictions as those of this list. + * + * @since 21 */ public List reversed() { return new Reversed<>(this, lock); diff --git a/src/java.base/share/classes/jdk/internal/util/ArraysSupport.java b/src/java.base/share/classes/jdk/internal/util/ArraysSupport.java index e18c32b9c1e..61be28519fc 100644 --- a/src/java.base/share/classes/jdk/internal/util/ArraysSupport.java +++ b/src/java.base/share/classes/jdk/internal/util/ArraysSupport.java @@ -24,6 +24,8 @@ */ package jdk.internal.util; +import java.util.Arrays; +import java.util.Collection; import jdk.internal.access.JavaLangAccess; import jdk.internal.access.SharedSecrets; import jdk.internal.misc.Unsafe; @@ -772,4 +774,36 @@ public class ArraysSupport { } return a; } + + /** + * Dump the contents of the given collection into the given array, in reverse order. + * This mirrors the semantics of Collection.toArray(T[]) in regard to reusing the given + * array, appending null if necessary, or allocating a new array of the same component type. + *

+ * A constraint is that this method should issue exactly one method call on the collection + * to obtain the elements and the size. Having a separate size() call or using an Iterator + * could result in errors if the collection changes size between calls. This implies that + * the elements need to be obtained via a single call to one of the toArray() methods. + * This further implies allocating memory proportional to the number of elements and + * making an extra copy, but this seems unavoidable. + *

+ * An obvious approach would be simply to call coll.toArray(array) and then reverse the + * order of the elements. This doesn't work, because if given array is sufficiently long, + * we cannot tell how many elements were copied into it and thus there is no way to reverse + * the right set of elements while leaving the remaining array elements undisturbed. + * + * @throws ArrayStoreException if coll contains elements that can't be stored in the array + */ + public static T[] toArrayReversed(Collection coll, T[] array) { + T[] newArray = reverse(coll.toArray(Arrays.copyOfRange(array, 0, 0))); + if (newArray.length > array.length) { + return newArray; + } else { + System.arraycopy(newArray, 0, array, 0, newArray.length); + if (array.length > newArray.length) { + array[newArray.length] = null; + } + return array; + } + } }