Add copy factory methods for unmodifiable List, Set, Map

Summary

Add new APIs for creation of the unmodifiable collections that were previously created only by the List.of/Set.of/Map.of family of Collections static factory methods. Adjust terminology to prefer "unmodifiable" over "immutable".

This CSR covers two related enhancement requests:

• JDK-8177290: add copy factory methods for unmodifiable List, Set, Map
• JDK-8184690: add Collectors for collecting into unmodifiable List, Set, and Map

Problem

The static factory methods added by JEP 269 (JDK-8048330) allow for convenient creation of unmodifiable collections, given elements that are listed explicitly, or that happen to be an in array. Sometimes it's necessary to compute the elements before creating the collection, or sometimes the exact number of elements is unknown until runtime. In these cases, the only way to create an unmodifiable collection is to create an array of the exact size and to copy the elements into it, and then to create the unmodifiable collection using that array. This necessitates an extra copy, it's tedious, and it's also inconvenient.

The specification for the factory methods in JDK 9 described "immutable" collections. These collections are not in fact immutable, because they can contain mutable elements. They are also easily confused with "immutable persistent" data structures.

Solution

Add new APIs that can create an unmodifiable collection from another Collection or Map or from a Stream.

Adjust terminology in the specification to prefer the term "unmodifiable" over "immutable".

Specification

Provide definitions for "view" collections, "unmodifiable" collections, and "unmodifiable view" collections. Adjust some existing collections APIs to use these new definitions. This clarifies the specifications of the existing APIs but is otherwise not intended to change any semantics. Also use these new definitions in the specifications for newly added APIs.

Add a family of copyOf() methods to java.util.List, Set, and Map to copy the elements from an existing collection or Map.

Add a family of collectors to java.util.stream.Collectors that will create an unmodifiable List, Set, or Map from a stream.

See attached files specdiff.3.zip and webrev.3.zip for full details. They are also posted here:

http://cr.openjdk.java.net/~smarks/reviews/8177290/specdiff.3/overview-summary.html

http://cr.openjdk.java.net/~smarks/reviews/8177290/webrev.3/