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

[Roger Riggs]

Hi Stuart,

Collection.java:

The mix of "should" and "must" in Collection.java can be confusing.
Typically "should" is interpreted as "must" from a conformance point of 
view.
For example,

147 * <p>An <i>unmodifiable collection</i> is a collection, all of whose
148 * mutator methods (as defined above) are specified to throw
149 * {@code UnsupportedOperationException}. Such a collection thus 
cannot be
150 * modified by calling any methods on it. For a collection to be properly
151 * unmodifiable, any view collections derived from it *must *also be 
unmodifiable.
152 * For example, if a List is unmodifiable, the List returned by
153 * {@link List#subList List.subList} *should *also be unmodifiable.

That leaves room for a non-compliant collection which could not 
technically be called "unmodifiable".

138 * does not support the operation. Such methods *should *(but are not 
required
139 * to) throw an {@code UnsupportedOperationException} if the 
invocation would
140 * have no effect on the collection. For example, invoking the
141 * {@link #addAll addAll} method on a collection that does not support
142 * the {@link #add add} operation *should *throw the exception if
143 * the collection passed as an argument is empty.

These two sentences both allow not throwing UOE and requiring UOE. Can 
they be worded to be consistent (or similarly qualified.)

Set.java: 706:  Would using "unique elements" clarify the contents of 
the result?
Saying "Duplicate elements are permitted," may be misleading.
Perhaps "The given Collection may contain duplicate elements"...

Similarly in Collectors.to toUnmodifiableSet:
"Duplicate elements are allowed," can be misleading, especially the word 
allowed.

Collectors.toUnmodifiableMap
      * If the mapped keys
1474      * might have duplicates, use {@link 
#toUnmodifiableMap(Function, Function, BinaryOperator)}
1475      * instead.

It would helpful to say why to use the version with the BinaryOperator, 
for example to say"
"To determine which of the duplicate elements to retain".  or similar.

Collectors:1606:  impl note:  With three different NPE throws, it is 
helpful to use the 2-arg
form of requireNonNull to indicate which parameter offends.

Roger

On 10/30/2017 6: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