8266571: Sequenced Collections

Reviewed-by: alanb

src/java.base/share/classes/java/util/AbstractMap.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2023, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -25,6 +25,11 @@
 
 package java.util;
 
+import java.util.stream.Stream;
+import java.util.function.Consumer;
+import java.util.function.IntFunction;
+import java.util.function.Predicate;
+
 /**
  * This class provides a skeletal implementation of the {@code Map}
  * interface, to minimize the effort required to implement this interface.
@@ -875,7 +880,48 @@ public int hashCode() {
         public String toString() {
             return key + "=" + value;
         }
-
     }
 
+    /**
+     * Delegates all Collection methods to the provided non-sequenced map view,
+     * except add() and addAll(), which throw UOE. This provides the common
+     * implementation of each of the sequenced views of the SequencedMap.
+     * Each view implementation is a subclass that provides an instance of the
+     * non-sequenced view as a delegate and an implementation of reversed().
+     * Each view also inherits the default implementations for the sequenced
+     * methods from SequencedCollection or SequencedSet.
+     * <p>
+     * Ideally this would be a private class within SequencedMap, but private
+     * classes aren't permitted within interfaces.
+     *
+     * @param <E> the view's element type
+     */
+    /* non-public */ abstract static class ViewCollection<E> implements Collection<E> {
+        UnsupportedOperationException uoe() { return new UnsupportedOperationException(); }
+        final Collection<E> view;
+
+        ViewCollection(Collection<E> view) { this.view = view; }
+
+        public boolean add(E t) { throw uoe(); }
+        public boolean addAll(Collection<? extends E> c) { throw uoe(); }
+        public void clear() { view.clear(); }
+        public boolean contains(Object o) { return view.contains(o); }
+        public boolean containsAll(Collection<?> c) { return view.containsAll(c); }
+        public boolean equals(Object o) { return view.equals(o); }
+        public void forEach(Consumer<? super E> c) { view.forEach(c); }
+        public int hashCode() { return view.hashCode(); }
+        public boolean isEmpty() { return view.isEmpty(); }
+        public Iterator<E> iterator() { return view.iterator(); }
+        public Stream<E> parallelStream() { return view.parallelStream(); }
+        public boolean remove(Object o) { return view.remove(o); }
+        public boolean removeAll(Collection<?> c) { return view.removeAll(c); }
+        public boolean removeIf(Predicate<? super E> filter) { return view.removeIf(filter); }
+        public boolean retainAll(Collection<?> c) { return view.retainAll(c); }
+        public int size() { return view.size(); }
+        public Spliterator<E> spliterator() { return view.spliterator(); }
+        public Stream<E> stream() { return view.stream(); }
+        public Object[] toArray() { return view.toArray(); }
+        public <T> T[] toArray(IntFunction<T[]> generator) { return view.toArray(generator); }
+        public <T> T[] toArray(T[] a) { return view.toArray(a); }
+    }
 }

src/java.base/share/classes/java/util/ArrayDeque.java

@@ -74,9 +74,8 @@
  * exception for its correctness: <i>the fail-fast behavior of iterators
  * should be used only to detect bugs.</i>
  *
- * <p>This class and its iterator implement all of the
- * <em>optional</em> methods of the {@link Collection} and {@link
- * Iterator} interfaces.
+ * <p>This class and its iterator implement all of the <em>optional</em> methods of the
+ * {@link Collection}, {@link SequencedCollection}, and {@link Iterator} interfaces.
  *
  * <p>This class is a member of the
  * <a href="{@docRoot}/java.base/java/util/package-summary.html#CollectionsFramework">

src/java.base/share/classes/java/util/ArrayList.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2023, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -428,6 +428,35 @@ public E get(int index) {
         return elementData(index);
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * @throws NoSuchElementException {@inheritDoc}
+     * @since 21
+     */
+    public E getFirst() {
+        if (size == 0) {
+            throw new NoSuchElementException();
+        } else {
+            return elementData(0);
+        }
+    }
+
+    /**
+     * {@inheritDoc}
+     *
+     * @throws NoSuchElementException {@inheritDoc}
+     * @since 21
+     */
+    public E getLast() {
+        int last = size - 1;
+        if (last < 0) {
+            throw new NoSuchElementException();
+        } else {
+            return elementData(last);
+        }
+    }
+
     /**
      * Replaces the element at the specified position in this list with
      * the specified element.
@@ -491,6 +520,24 @@ public void add(int index, E element) {
         size = s + 1;
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * @since 21
+     */
+    public void addFirst(E element) {
+        add(0, element);
+    }
+
+    /**
+     * {@inheritDoc}
+     *
+     * @since 21
+     */
+    public void addLast(E element) {
+        add(element);
+    }
+
     /**
      * Removes the element at the specified position in this list.
      * Shifts any subsequent elements to the left (subtracts one from their
@@ -510,6 +557,41 @@ public E remove(int index) {
         return oldValue;
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * @throws NoSuchElementException {@inheritDoc}
+     * @since 21
+     */
+    public E removeFirst() {
+        if (size == 0) {
+            throw new NoSuchElementException();
+        } else {
+            Object[] es = elementData;
+            @SuppressWarnings("unchecked") E oldValue = (E) es[0];
+            fastRemove(es, 0);
+            return oldValue;
+        }
+    }
+
+    /**
+     * {@inheritDoc}
+     *
+     * @throws NoSuchElementException {@inheritDoc}
+     * @since 21
+     */
+    public E removeLast() {
+        int last = size - 1;
+        if (last < 0) {
+            throw new NoSuchElementException();
+        } else {
+            Object[] es = elementData;
+            @SuppressWarnings("unchecked") E oldValue = (E) es[last];
+            fastRemove(es, last);
+            return oldValue;
+        }
+    }
+
     /**
      * {@inheritDoc}
      */

src/java.base/share/classes/java/util/Collection.java

@@ -33,8 +33,11 @@
 /**
  * The root interface in the <i>collection hierarchy</i>.  A collection
  * represents a group of objects, known as its <i>elements</i>.  Some
- * collections allow duplicate elements and others do not.  Some are ordered
- * and others unordered.  The JDK does not provide any <i>direct</i>
+ * collections allow duplicate elements and others do not.  Some are ordered,
+ * and others are unordered. Collections that have a defined
+ * <a href="SequencedCollection.html#encounter">encounter order</a>
+ * are generally subtypes of the {@link SequencedCollection} interface.
+ * The JDK does not provide any <i>direct</i>
  * implementations of this interface: it provides implementations of more
  * specific subinterfaces like {@code Set} and {@code List}.  This interface
  * is typically used to pass collections around and manipulate them where
@@ -121,8 +124,9 @@
  * Other examples of view collections include collections that provide a
  * different representation of the same elements, for example, as
  * provided by {@link List#subList List.subList},
- * {@link NavigableSet#subSet NavigableSet.subSet}, or
- * {@link Map#entrySet Map.entrySet}.
+ * {@link NavigableSet#subSet NavigableSet.subSet},
+ * {@link Map#entrySet Map.entrySet}, or
+ * {@link SequencedCollection#reversed SequencedCollection.reversed}.
  * Any changes made to the backing collection are visible in the view collection.
  * Correspondingly, any changes made to the view collection &mdash; if changes
  * are permitted &mdash; are written through to the backing collection.
@@ -202,7 +206,8 @@
  * serializability of such collections is described in the specification of the method
  * that creates them, or in some other suitable place. In cases where the serializability
  * of a collection is not specified, there is no guarantee about the serializability of such
- * collections. In particular, many <a href="#view">view collections</a> are not serializable.
+ * collections. In particular, many <a href="#view">view collections</a> are not serializable,
+ * even if the original collection is serializable.
  *
  * <p>A collection implementation that implements the {@code Serializable} interface cannot
  * be guaranteed to be serializable. The reason is that in general, collections
@@ -501,7 +506,9 @@ default <T> T[] toArray(IntFunction<T[]> generator) {
      * the specified collection is modified while the operation is in progress.
      * (This implies that the behavior of this call is undefined if the
      * specified collection is this collection, and this collection is
-     * nonempty.)
+     * nonempty.) If the specified collection has a defined
+     * <a href="SequencedCollection.html#encounter">encounter order</a>,
+     * processing of its elements generally occurs in that order.
      *
      * @param c collection containing elements to be added to this collection
      * @return {@code true} if this collection changed as a result of the call