--- a/jdk/src/java.base/share/classes/java/util/List.java Tue Dec 08 16:43:58 2015 -0800
+++ b/jdk/src/java.base/share/classes/java/util/List.java Tue Dec 08 13:48:22 2015 -0800
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1997, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2015, 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
@@ -87,6 +87,28 @@
* Such exceptions are marked as "optional" in the specification for this
* interface.
*
+ * <h2><a name="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. Attempts to do so result in {@code UnsupportedOperationException}.
+ * 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.
+ * <li>The order of elements in the list is the same as the order of the
+ * provided arguments, or of the elements in the provided array.
+ * <li>They are <a href="../lang/doc-files/ValueBased.html">value-based</a>.
+ * Callers should make no assumptions about the identity of the returned instances.
+ * Factories are free to create new instances or reuse existing ones. Therefore,
+ * identity-sensitive operations on these instances (reference equality ({@code ==}),
+ * identity hash code, and synchronization) are unreliable and should be avoided.
+ * </ul>
+ *
* <p>This interface is a member of the
* <a href="{@docRoot}/../technotes/guides/collections/index.html">
* Java Collections Framework</a>.
@@ -731,4 +753,312 @@
default Spliterator<E> spliterator() {
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
+ */
+ static <E> List<E> of() {
+ return Collections.emptyList();
+ }
+
+ /**
+ * 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}
+ *
+ * @since 9
+ */
+ static <E> List<E> of(E e1) {
+ return Collections.singletonList(Objects.requireNonNull(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
+ * @throws NullPointerException if an element is {@code null}
+ *
+ * @since 9
+ */
+ static <E> List<E> of(E e1, E e2) {
+ return Collections.unmodifiableList(
+ Arrays.asList(Objects.requireNonNull(e1),
+ Objects.requireNonNull(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
+ * @return a {@code List} containing the specified elements
+ * @throws NullPointerException if an element is {@code null}
+ *
+ * @since 9
+ */
+ static <E> List<E> of(E e1, E e2, E e3) {
+ return Collections.unmodifiableList(
+ Arrays.asList(Objects.requireNonNull(e1),
+ Objects.requireNonNull(e2),
+ Objects.requireNonNull(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
+ * @param e4 the fourth element
+ * @return a {@code List} containing the specified elements
+ * @throws NullPointerException if an element is {@code null}
+ *
+ * @since 9
+ */
+ static <E> List<E> of(E e1, E e2, E e3, E e4) {
+ return Collections.unmodifiableList(
+ Arrays.asList(Objects.requireNonNull(e1),
+ Objects.requireNonNull(e2),
+ Objects.requireNonNull(e3),
+ Objects.requireNonNull(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
+ * @param e4 the fourth element
+ * @param e5 the fifth element
+ * @return a {@code List} containing the specified elements
+ * @throws NullPointerException if an element is {@code null}
+ *
+ * @since 9
+ */
+ static <E> List<E> of(E e1, E e2, E e3, E e4, E e5) {
+ return Collections.unmodifiableList(
+ Arrays.asList(Objects.requireNonNull(e1),
+ Objects.requireNonNull(e2),
+ Objects.requireNonNull(e3),
+ Objects.requireNonNull(e4),
+ Objects.requireNonNull(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
+ * @param e4 the fourth element
+ * @param e5 the fifth element
+ * @param e6 the sixth element
+ * @return a {@code List} containing the specified elements
+ * @throws NullPointerException if an element is {@code null}
+ *
+ * @since 9
+ */
+ static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6) {
+ return Collections.unmodifiableList(
+ Arrays.asList(Objects.requireNonNull(e1),
+ Objects.requireNonNull(e2),
+ Objects.requireNonNull(e3),
+ Objects.requireNonNull(e4),
+ Objects.requireNonNull(e5),
+ Objects.requireNonNull(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
+ * @param e4 the fourth element
+ * @param e5 the fifth element
+ * @param e6 the sixth element
+ * @param e7 the seventh element
+ * @return a {@code List} containing the specified elements
+ * @throws NullPointerException if an element is {@code null}
+ *
+ * @since 9
+ */
+ static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7) {
+ return Collections.unmodifiableList(
+ Arrays.asList(Objects.requireNonNull(e1),
+ Objects.requireNonNull(e2),
+ Objects.requireNonNull(e3),
+ Objects.requireNonNull(e4),
+ Objects.requireNonNull(e5),
+ Objects.requireNonNull(e6),
+ Objects.requireNonNull(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
+ * @param e4 the fourth element
+ * @param e5 the fifth element
+ * @param e6 the sixth element
+ * @param e7 the seventh element
+ * @param e8 the eighth element
+ * @return a {@code List} containing the specified elements
+ * @throws NullPointerException if an element is {@code null}
+ *
+ * @since 9
+ */
+ static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8) {
+ return Collections.unmodifiableList(
+ Arrays.asList(Objects.requireNonNull(e1),
+ Objects.requireNonNull(e2),
+ Objects.requireNonNull(e3),
+ Objects.requireNonNull(e4),
+ Objects.requireNonNull(e5),
+ Objects.requireNonNull(e6),
+ Objects.requireNonNull(e7),
+ Objects.requireNonNull(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
+ * @param e4 the fourth element
+ * @param e5 the fifth element
+ * @param e6 the sixth element
+ * @param e7 the seventh element
+ * @param e8 the eighth element
+ * @param e9 the ninth element
+ * @return a {@code List} containing the specified elements
+ * @throws NullPointerException if an element is {@code null}
+ *
+ * @since 9
+ */
+ static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9) {
+ return Collections.unmodifiableList(
+ Arrays.asList(Objects.requireNonNull(e1),
+ Objects.requireNonNull(e2),
+ Objects.requireNonNull(e3),
+ Objects.requireNonNull(e4),
+ Objects.requireNonNull(e5),
+ Objects.requireNonNull(e6),
+ Objects.requireNonNull(e7),
+ Objects.requireNonNull(e8),
+ Objects.requireNonNull(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
+ * @param e4 the fourth element
+ * @param e5 the fifth element
+ * @param e6 the sixth element
+ * @param e7 the seventh element
+ * @param e8 the eighth element
+ * @param e9 the ninth element
+ * @param e10 the tenth element
+ * @return a {@code List} containing the specified elements
+ * @throws NullPointerException if an element is {@code null}
+ *
+ * @since 9
+ */
+ static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9, E e10) {
+ return Collections.unmodifiableList(
+ Arrays.asList(Objects.requireNonNull(e1),
+ Objects.requireNonNull(e2),
+ Objects.requireNonNull(e3),
+ Objects.requireNonNull(e4),
+ Objects.requireNonNull(e5),
+ Objects.requireNonNull(e6),
+ Objects.requireNonNull(e7),
+ Objects.requireNonNull(e8),
+ Objects.requireNonNull(e9),
+ Objects.requireNonNull(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
+ * a single element that is an array, do the following:
+ *
+ * <pre>{@code
+ * String[] array = ... ;
+ * List<String[]> list = List.<String[]>of(array);
+ * }</pre>
+ *
+ * This will cause the {@link List#of(Object) List.of(E)} method
+ * to be invoked instead.
+ *
+ * @param <E> the {@code List}'s element type
+ * @param elements the elements to be contained in the list
+ * @return a {@code List} containing the specified elements
+ * @throws NullPointerException if an element is {@code null} or if the array is {@code null}
+ *
+ * @since 9
+ */
+ @SafeVarargs
+ @SuppressWarnings("varargs")
+ static <E> List<E> of(E... elements) {
+ elements = elements.clone(); // throws NPE if es is null
+ for (E e : elements) {
+ Objects.requireNonNull(e);
+ }
+ return Collections.unmodifiableList(Arrays.asList(elements));
+ }
}