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

rev 17661 : 8177290: add copy factory methods for unmodifiable List, Set, Map
8184690: add Collectors for collecting into unmodifiable List, Set, and Map
Reviewed-by: XXX

@@ -85,19 +85,20 @@
  * the insertion of an ineligible element into the list may throw an
  * exception or it may succeed, at the option of the implementation.
  * Such exceptions are marked as "optional" in the specification for this
  * interface.
  *
- * <h2><a id="immutable">Immutable List Static Factory Methods</a></h2>
- * <p>The {@link List#of(Object...) List.of()} static factory methods
- * provide a convenient way to create immutable lists. The {@code List}
+ * <h2><a id="unmodifiable">Unmodifiable Lists</a></h2>
+ * <p>The {@link List#of(Object...) List.of} and
+ * {@link List#copyOf List.copyOf} static factory methods
+ * provide a convenient way to create unmodifiable lists. The {@code List}
  * instances created by these methods have the following characteristics:
  *
  * <ul>
- * <li>They are <em>structurally immutable</em>. Elements cannot be added, removed,
- * or replaced. Calling any mutator method will always cause
- * {@code UnsupportedOperationException} to be thrown.
+ * <li>They are <a href="Collection.html#unmodifiable"><i>unmodifiable</i></a>. Elements cannot
+ * be added, removed, or replaced. Calling any mutator method on the List
+ * will always cause {@code UnsupportedOperationException} to be thrown.
  * However, if the contained elements are themselves mutable,
  * this may cause the List's contents to appear to change.
  * <li>They disallow {@code null} elements. Attempts to create them with
  * {@code null} elements result in {@code NullPointerException}.
  * <li>They are serializable if all elements are serializable.

@@ -774,13 +775,13 @@
             return Spliterators.spliterator(this, Spliterator.ORDERED);
         }
     }
 
     /**
-     * Returns an immutable list containing zero elements.
+     * Returns an unmodifiable list containing zero elements.
      *
-     * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
+     * See <a href="#unmodifiable">Unmodifiable Lists</a> for details.
      *
      * @param <E> the {@code List}'s element type
      * @return an empty {@code List}
      *
      * @since 9

@@ -788,13 +789,13 @@
     static <E> List<E> of() {
         return ImmutableCollections.List0.instance();
     }
 
     /**
-     * Returns an immutable list containing one element.
+     * Returns an unmodifiable list containing one element.
      *
-     * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
+     * See <a href="#unmodifiable">Unmodifiable Lists</a> for details.
      *
      * @param <E> the {@code List}'s element type
      * @param e1 the single element
      * @return a {@code List} containing the specified element
      * @throws NullPointerException if the element is {@code null}

@@ -804,13 +805,13 @@
     static <E> List<E> of(E e1) {
         return new ImmutableCollections.List1<>(e1);
     }
 
     /**
-     * Returns an immutable list containing two elements.
+     * Returns an unmodifiable list containing two elements.
      *
-     * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
+     * See <a href="#unmodifiable">Unmodifiable Lists</a> for details.
      *
      * @param <E> the {@code List}'s element type
      * @param e1 the first element
      * @param e2 the second element
      * @return a {@code List} containing the specified elements

@@ -821,13 +822,13 @@
     static <E> List<E> of(E e1, E e2) {
         return new ImmutableCollections.List2<>(e1, e2);
     }
 
     /**
-     * Returns an immutable list containing three elements.
+     * Returns an unmodifiable list containing three elements.
      *
-     * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
+     * See <a href="#unmodifiable">Unmodifiable Lists</a> for details.
      *
      * @param <E> the {@code List}'s element type
      * @param e1 the first element
      * @param e2 the second element
      * @param e3 the third element

@@ -839,13 +840,13 @@
     static <E> List<E> of(E e1, E e2, E e3) {
         return new ImmutableCollections.ListN<>(e1, e2, e3);
     }
 
     /**
-     * Returns an immutable list containing four elements.
+     * Returns an unmodifiable list containing four elements.
      *
-     * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
+     * See <a href="#unmodifiable">Unmodifiable Lists</a> for details.
      *
      * @param <E> the {@code List}'s element type
      * @param e1 the first element
      * @param e2 the second element
      * @param e3 the third element

@@ -858,13 +859,13 @@
     static <E> List<E> of(E e1, E e2, E e3, E e4) {
         return new ImmutableCollections.ListN<>(e1, e2, e3, e4);
     }
 
     /**
-     * Returns an immutable list containing five elements.
+     * Returns an unmodifiable list containing five elements.
      *
-     * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
+     * See <a href="#unmodifiable">Unmodifiable Lists</a> for details.
      *
      * @param <E> the {@code List}'s element type
      * @param e1 the first element
      * @param e2 the second element
      * @param e3 the third element

@@ -878,13 +879,13 @@
     static <E> List<E> of(E e1, E e2, E e3, E e4, E e5) {
         return new ImmutableCollections.ListN<>(e1, e2, e3, e4, e5);
     }
 
     /**
-     * Returns an immutable list containing six elements.
+     * Returns an unmodifiable list containing six elements.
      *
-     * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
+     * See <a href="#unmodifiable">Unmodifiable Lists</a> for details.
      *
      * @param <E> the {@code List}'s element type
      * @param e1 the first element
      * @param e2 the second element
      * @param e3 the third element

@@ -900,13 +901,13 @@
         return new ImmutableCollections.ListN<>(e1, e2, e3, e4, e5,
                                                 e6);
     }
 
     /**
-     * Returns an immutable list containing seven elements.
+     * Returns an unmodifiable list containing seven elements.
      *
-     * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
+     * See <a href="#unmodifiable">Unmodifiable Lists</a> for details.
      *
      * @param <E> the {@code List}'s element type
      * @param e1 the first element
      * @param e2 the second element
      * @param e3 the third element

@@ -923,13 +924,13 @@
         return new ImmutableCollections.ListN<>(e1, e2, e3, e4, e5,
                                                 e6, e7);
     }
 
     /**
-     * Returns an immutable list containing eight elements.
+     * Returns an unmodifiable list containing eight elements.
      *
-     * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
+     * See <a href="#unmodifiable">Unmodifiable Lists</a> for details.
      *
      * @param <E> the {@code List}'s element type
      * @param e1 the first element
      * @param e2 the second element
      * @param e3 the third element

@@ -947,13 +948,13 @@
         return new ImmutableCollections.ListN<>(e1, e2, e3, e4, e5,
                                                 e6, e7, e8);
     }
 
     /**
-     * Returns an immutable list containing nine elements.
+     * Returns an unmodifiable list containing nine elements.
      *
-     * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
+     * See <a href="#unmodifiable">Unmodifiable Lists</a> for details.
      *
      * @param <E> the {@code List}'s element type
      * @param e1 the first element
      * @param e2 the second element
      * @param e3 the third element

@@ -972,13 +973,13 @@
         return new ImmutableCollections.ListN<>(e1, e2, e3, e4, e5,
                                                 e6, e7, e8, e9);
     }
 
     /**
-     * Returns an immutable list containing ten elements.
+     * Returns an unmodifiable list containing ten elements.
      *
-     * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
+     * See <a href="#unmodifiable">Unmodifiable Lists</a> for details.
      *
      * @param <E> the {@code List}'s element type
      * @param e1 the first element
      * @param e2 the second element
      * @param e3 the third element

@@ -998,12 +999,12 @@
         return new ImmutableCollections.ListN<>(e1, e2, e3, e4, e5,
                                                 e6, e7, e8, e9, e10);
     }
 
     /**
-     * Returns an immutable list containing an arbitrary number of elements.
-     * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
+     * Returns an unmodifiable list containing an arbitrary number of elements.
+     * See <a href="#unmodifiable">Unmodifiable Lists</a> for details.
      *
      * @apiNote
      * This method also accepts a single array as an argument. The element type of
      * the resulting list will be the component type of the array, and the size of
      * the list will be equal to the length of the array. To create a list with

@@ -1036,6 +1037,25 @@
                 return new ImmutableCollections.List2<>(elements[0], elements[1]);
             default:
                 return new ImmutableCollections.ListN<>(elements);
         }
     }
+
+    /**
+     * Returns an unmodifiable List containing the elements of the given Collection,
+     * in iteration order. See <a href="#unmodifiable">Unmodifiable Lists</a> for
+     * information about the characteristics of the returned List.
+     *
+     * @param <E> the {@code List}'s element type
+     * @param coll the collection from which elements are drawn
+     * @return the new List
+     * @since 10
+     */
+    @SuppressWarnings("unchecked")
+    static <E> List<E> copyOf(Collection<? extends E> coll) {
+        if (coll instanceof ImmutableCollections.AbstractImmutableList) {
+            return (List<E>)coll;
+        } else {
+            return (List<E>)List.of(coll.toArray());
+        }
+    }
 }