java9.util

Class Lists

java.lang.Object

java9.util.Lists

public final class Lists
extends Object

A place for the implementations of the new Java 9 static interface methods in the List interface specified in JEP 269 "Unmodifiable List Static Factory Methods".

Unmodifiable Lists

The Lists.of and Lists.copyOf static factory methods provide a convenient way to create unmodifiable lists. The List instances created by these methods have the following characteristics:

• They are unmodifiable. Elements cannot be added, removed, or replaced. Calling any mutator method on the List will always cause UnsupportedOperationException to be thrown. However, if the contained elements are themselves mutable, this may cause the List's contents to appear to change.
• They disallow null elements. Attempts to create them with null elements result in NullPointerException.
• They are serializable if all elements are serializable.
• 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.
• They are value-based. 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 ( ==), identity hash code, and synchronization) are unreliable and should be avoided.

Since:

9

Method Summary

Modifier and Type	Method and Description
static <E> List<E>	copyOf(Collection<? extends E> coll) Returns an unmodifiable List containing the elements of the given Collection, in its iteration order.
static <E> List<E>	of() Returns an unmodifiable list containing zero elements.
static <E> List<E>	of(E... elements) Returns an unmodifiable list containing an arbitrary number of elements.
static <E> List<E>	of(E e1) Returns an unmodifiable list containing one element.
static <E> List<E>	of(E e1, E e2) Returns an unmodifiable list containing two elements.
static <E> List<E>	of(E e1, E e2, E e3) Returns an unmodifiable list containing three elements.
static <E> List<E>	of(E e1, E e2, E e3, E e4) Returns an unmodifiable list containing four elements.
static <E> List<E>	of(E e1, E e2, E e3, E e4, E e5) Returns an unmodifiable list containing five elements.
static <E> List<E>	of(E e1, E e2, E e3, E e4, E e5, E e6) Returns an unmodifiable list containing six elements.
static <E> List<E>	of(E e1, E e2, E e3, E e4, E e5, E e6, E e7) Returns an unmodifiable list containing seven elements.
static <E> List<E>	of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8) Returns an unmodifiable list containing eight elements.
static <E> List<E>	of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9) Returns an unmodifiable list containing nine elements.
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) Returns an unmodifiable list containing ten elements.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

of

public static <E> List<E> of()

Returns an unmodifiable list containing zero elements. See Unmodifiable Lists for details.

Type Parameters:

E - the List's element type

Returns:

an empty List

Since:

9

of

public static <E> List<E> of(E e1)

Returns an unmodifiable list containing one element. See Unmodifiable Lists for details.

Type Parameters:

E - the List's element type

Parameters:

e1 - the single element

Returns:

a List containing the specified element

Throws:

NullPointerException - if the element is null

Since:

9

of

public static <E> List<E> of(E e1,
                             E e2)

Returns an unmodifiable list containing two elements. See Unmodifiable Lists for details.

Type Parameters:

E - the List's element type

Parameters:

e1 - the first element

e2 - the second element

Returns:

a List containing the specified elements

Throws:

NullPointerException - if an element is null

Since:

9

of

public static <E> List<E> of(E e1,
                             E e2,
                             E e3)

Returns an unmodifiable list containing three elements. See Unmodifiable Lists for details.

Type Parameters:

E - the List's element type

Parameters:

e1 - the first element

e2 - the second element

e3 - the third element

Returns:

a List containing the specified elements

Throws:

NullPointerException - if an element is null

Since:

9

of

public static <E> List<E> of(E e1,
                             E e2,
                             E e3,
                             E e4)

Returns an unmodifiable list containing four elements. See Unmodifiable Lists for details.

Type Parameters:

E - the List's element type

Parameters:

e1 - the first element

e2 - the second element

e3 - the third element

e4 - the fourth element

Returns:

a List containing the specified elements

Throws:

NullPointerException - if an element is null

Since:

9

of

public static <E> List<E> of(E e1,
                             E e2,
                             E e3,
                             E e4,
                             E e5)

Returns an unmodifiable list containing five elements. See Unmodifiable Lists for details.

Type Parameters:

E - the List's element type

Parameters:

e1 - the first element

e2 - the second element

e3 - the third element

e4 - the fourth element

e5 - the fifth element

Returns:

a List containing the specified elements

Throws:

NullPointerException - if an element is null

Since:

9

of

public static <E> List<E> of(E e1,
                             E e2,
                             E e3,
                             E e4,
                             E e5,
                             E e6)

Returns an unmodifiable list containing six elements. See Unmodifiable Lists for details.

Type Parameters:

E - the List's element type

Parameters:

e1 - the first element

e2 - the second element

e3 - the third element

e4 - the fourth element

e5 - the fifth element

e6 - the sixth element

Returns:

a List containing the specified elements

Throws:

NullPointerException - if an element is null

Since:

9

of

public static <E> List<E> of(E e1,
                             E e2,
                             E e3,
                             E e4,
                             E e5,
                             E e6,
                             E e7)

Returns an unmodifiable list containing seven elements. See Unmodifiable Lists for details.

Type Parameters:

E - the List's element type

Parameters:

e1 - the first element

e2 - the second element

e3 - the third element

e4 - the fourth element

e5 - the fifth element

e6 - the sixth element

e7 - the seventh element

Returns:

a List containing the specified elements

Throws:

NullPointerException - if an element is null

Since:

9

of

public static <E> List<E> of(E e1,
                             E e2,
                             E e3,
                             E e4,
                             E e5,
                             E e6,
                             E e7,
                             E e8)

Returns an unmodifiable list containing eight elements. See Unmodifiable Lists for details.

Type Parameters:

E - the List's element type

Parameters:

e1 - the first element

e2 - the second element

e3 - the third element

e4 - the fourth element

e5 - the fifth element

e6 - the sixth element

e7 - the seventh element

e8 - the eighth element

Returns:

a List containing the specified elements

Throws:

NullPointerException - if an element is null

Since:

9

of

public static <E> List<E> of(E e1,
                             E e2,
                             E e3,
                             E e4,
                             E e5,
                             E e6,
                             E e7,
                             E e8,
                             E e9)

Returns an unmodifiable list containing nine elements. See Unmodifiable Lists for details.

Type Parameters:

E - the List's element type

Parameters:

e1 - the first element

e2 - the second element

e3 - the third element

e4 - the fourth element

e5 - the fifth element

e6 - the sixth element

e7 - the seventh element

e8 - the eighth element

e9 - the ninth element

Returns:

a List containing the specified elements

Throws:

NullPointerException - if an element is null

Since:

9

of

public 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)

Returns an unmodifiable list containing ten elements. See Unmodifiable Lists for details.

Type Parameters:

E - the List's element type

Parameters:

e1 - the first element

e2 - the second element

e3 - the third element

e4 - the fourth element

e5 - the fifth element

e6 - the sixth element

e7 - the seventh element

e8 - the eighth element

e9 - the ninth element

e10 - the tenth element

Returns:

a List containing the specified elements

Throws:

NullPointerException - if an element is null

Since:

9

of

@SafeVarargs
public static <E> List<E> of(E... elements)

Returns an unmodifiable list containing an arbitrary number of elements. See Unmodifiable Lists for details.

API Note:
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:

     String[] array = ... ;
     List<String[]> list = Lists.<String[]>of(array);
 

This will cause the Lists.of(E) method to be invoked instead.

Type Parameters:

E - the List's element type

Parameters:

elements - the elements to be contained in the list

Returns:

a List containing the specified elements

Throws:

NullPointerException - if an element is null or if the array is null

Since:

9

copyOf

public static <E> List<E> copyOf(Collection<? extends E> coll)

Returns an unmodifiable List 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.

Implementation Note: If the given Collection is an unmodifiable List, calling copyOf will generally not create a copy.

Type Parameters:

E - the List's element type

Parameters:

coll - the collection from which elements are drawn, must be non-null

Returns:

a List containing the elements of the given Collection

Throws:

NullPointerException - if coll is null, or if it contains any nulls

Since:

10