< prev index next >

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

Print this page

    rev 47953 : 8177290: add copy factory methods for unmodifiable List, Set, Map
    8184690: add Collectors for collecting into unmodifiable List, Set, and Map
    Reviewed-by: alanb, briangoetz, dholmes, jrose, rriggs, scolebourne

    @@ -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.

    @@ -775,13 +776,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

    @@ -789,13 +790,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}

    @@ -805,13 +806,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

    @@ -822,13 +823,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

    @@ -840,13 +841,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

    @@ -859,13 +860,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

    @@ -879,13 +880,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

    @@ -901,13 +902,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

    @@ -924,13 +925,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

    @@ -948,13 +949,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

    @@ -973,13 +974,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

    @@ -999,12 +1000,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

    @@ -1037,6 +1038,31 @@
                     return new ImmutableCollections.List2<>(elements[0], elements[1]);
                 default:
                     return new ImmutableCollections.ListN<>(elements);
             }
         }
    +
    +    /**
    +     * Returns an <a href="#unmodifiable">unmodifiable List</a> containing the elements of
    +     * the given Collection, in its iteration order. The given Collection must not be null,
    +     * and it must not contain any null elements. If the given Collection is subsequently
    +     * modified, the returned List will not reflect such modifications.
    +     *
    +     * @implNote
    +     * If the given Collection is an <a href="#unmodifiable">unmodifiable List</a>,
    +     * calling copyOf will generally not create a copy.
    +     *
    +     * @param <E> the {@code List}'s element type
    +     * @param coll a {@code Collection} from which elements are drawn, must be non-null
    +     * @return a {@code List} containing the elements of the given {@code Collection}
    +     * @throws NullPointerException if coll is null, or if it contains any nulls
    +     * @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());
    +        }
    +    }
     }

< prev index next >