< 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,103 ****
       * 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}
       * 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.
       * 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.
    --- 85,104 ----
       * 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="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 <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,787 ****
                  return Spliterators.spliterator(this, Spliterator.ORDERED);
              }
          }

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

          /**
    !      * Returns an unmodifiable list containing zero elements.
           *
    !      * 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,801 ****
          static <E> List<E> of() {
              return ImmutableCollections.List0.instance();
          }

          /**
    !      * Returns an immutable list containing one element.
           *
    !      * See <a href="#immutable">Immutable List Static Factory Methods</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}
    --- 790,802 ----
          static <E> List<E> of() {
              return ImmutableCollections.List0.instance();
          }

          /**
    !      * Returns an unmodifiable list containing one element.
           *
    !      * 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,817 ****
          static <E> List<E> of(E e1) {
              return new ImmutableCollections.List1<>(e1);
          }

          /**
    !      * Returns an immutable list containing two elements.
           *
    !      * See <a href="#immutable">Immutable List Static Factory Methods</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
    --- 806,818 ----
          static <E> List<E> of(E e1) {
              return new ImmutableCollections.List1<>(e1);
          }

          /**
    !      * Returns an unmodifiable list containing two elements.
           *
    !      * 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,834 ****
          static <E> List<E> of(E e1, E e2) {
              return new ImmutableCollections.List2<>(e1, e2);
          }

          /**
    !      * Returns an immutable list containing three elements.
           *
    !      * See <a href="#immutable">Immutable List Static Factory Methods</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
    --- 823,835 ----
          static <E> List<E> of(E e1, E e2) {
              return new ImmutableCollections.List2<>(e1, e2);
          }

          /**
    !      * Returns an unmodifiable list containing three elements.
           *
    !      * 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,852 ****
          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.
           *
    !      * See <a href="#immutable">Immutable List Static Factory Methods</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
    --- 841,853 ----
          static <E> List<E> of(E e1, E e2, E e3) {
              return new ImmutableCollections.ListN<>(e1, e2, e3);
          }

          /**
    !      * Returns an unmodifiable list containing four elements.
           *
    !      * 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,871 ****
          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.
           *
    !      * See <a href="#immutable">Immutable List Static Factory Methods</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
    --- 860,872 ----
          static <E> List<E> of(E e1, E e2, E e3, E e4) {
              return new ImmutableCollections.ListN<>(e1, e2, e3, e4);
          }

          /**
    !      * Returns an unmodifiable list containing five elements.
           *
    !      * 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,891 ****
          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.
           *
    !      * See <a href="#immutable">Immutable List Static Factory Methods</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
    --- 880,892 ----
          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 unmodifiable list containing six elements.
           *
    !      * 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,913 ****
              return new ImmutableCollections.ListN<>(e1, e2, e3, e4, e5,
                                                      e6);
          }

          /**
    !      * Returns an immutable list containing seven elements.
           *
    !      * See <a href="#immutable">Immutable List Static Factory Methods</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
    --- 902,914 ----
              return new ImmutableCollections.ListN<>(e1, e2, e3, e4, e5,
                                                      e6);
          }

          /**
    !      * Returns an unmodifiable list containing seven elements.
           *
    !      * 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,936 ****
              return new ImmutableCollections.ListN<>(e1, e2, e3, e4, e5,
                                                      e6, e7);
          }

          /**
    !      * Returns an immutable list containing eight elements.
           *
    !      * See <a href="#immutable">Immutable List Static Factory Methods</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
    --- 925,937 ----
              return new ImmutableCollections.ListN<>(e1, e2, e3, e4, e5,
                                                      e6, e7);
          }

          /**
    !      * Returns an unmodifiable list containing eight elements.
           *
    !      * 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,960 ****
              return new ImmutableCollections.ListN<>(e1, e2, e3, e4, e5,
                                                      e6, e7, e8);
          }

          /**
    !      * Returns an immutable list containing nine elements.
           *
    !      * See <a href="#immutable">Immutable List Static Factory Methods</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
    --- 949,961 ----
              return new ImmutableCollections.ListN<>(e1, e2, e3, e4, e5,
                                                      e6, e7, e8);
          }

          /**
    !      * Returns an unmodifiable list containing nine elements.
           *
    !      * 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,985 ****
              return new ImmutableCollections.ListN<>(e1, e2, e3, e4, e5,
                                                      e6, e7, e8, e9);
          }

          /**
    !      * Returns an immutable list containing ten elements.
           *
    !      * See <a href="#immutable">Immutable List Static Factory Methods</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
    --- 974,986 ----
              return new ImmutableCollections.ListN<>(e1, e2, e3, e4, e5,
                                                      e6, e7, e8, e9);
          }

          /**
    !      * Returns an unmodifiable list containing ten elements.
           *
    !      * 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,1010 ****
              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.
           *
           * @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
    --- 1000,1011 ----
              return new ImmutableCollections.ListN<>(e1, e2, e3, e4, e5,
                                                      e6, e7, e8, e9, e10);
          }

          /**
    !      * 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,1042 ****
    --- 1038,1068 ----
                      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 >