RFR(m): 8177290 add copy factory methods for unmodifiable List, Set, Map

[Stuart Marks]

Updated webrev, based on comments from Brian and Roger:

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

s'marks


On 10/30/17 3:50 PM, Stuart Marks wrote:
> (also includes 8184690: add Collectors for collecting into unmodifiable List, 
> Set, and Map)
> 
> Hi all,
> 
> Here's an updated webrev for this changeset; the previous review thread is here:
> 
>      
> http://mail.openjdk.java.net/pipermail/core-libs-dev/2017-September/049261.html
> 
> This webrev includes the following:
> 
> * specification revisions to provide clearer definitions of "view" collections, 
> "unmodifiable" collections, and "unmodifiable views"
> 
> * new List.copyOf(), Set.copyOf(), and Map.copyOf() "copy factory" methods
> 
> * new Collectors.toUnmodifiableList, Set, and Map methods
> 
> * tests for the new API methods
> 
> I've added some assertions that require some independence between the source 
> collection (or map) and the result of the copyOf() method.
> 
> I've made a small but significant change to Set.copyOf compared to the previous 
> round. Previously, it specified that the first of any equal elements was 
> preserved. Now, it is explicitly unspecified which of any equals elements is 
> preserved. This is consistent with Set.addAll, Collectors.toSet, and the newly 
> added Collectors.toUnmodifiableSet, none of which specify which of duplicate 
> elements is preserved.
> 
> (The outlier here is Stream.distinct, which specifies that the first element of 
> any duplicates is preserved, if the stream is ordered.)
> 
> I've also made some minor wording/editorial changes in response to suggestions 
> from David Holmes and Roger Riggs. I've kept the wording changes that give 
> emphasis to "unmodifiable" over "immutable." The term "immutable" is 
> inextricably intertwined with "persistent" when it comes to data structures, and 
> I believe we'll be explaining this forever if Java's "immutable" means something 
> different from everybody else's.
> 
> Webrev:
> 
>      http://cr.openjdk.java.net/~smarks/reviews/8177290/webrev.1/
> 
> Bugs:
> 
>      https://bugs.openjdk.java.net/browse/JDK-8177290
>          add copy factory methods for unmodifiable List, Set, Map
> 
>      https://bugs.openjdk.java.net/browse/JDK-8184690
>          add Collectors for collecting into unmodifiable List, Set, and Map
> 
> Thanks,
> 
> s'marks