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

[Stuart Marks]

On 11/17/17 9:43 PM, John Rose wrote:
> Late to the party, but these lines rub me the wrong way:
> 
> @return the new {@code List}
> @return the new {@code Set}
> @return the new {@code Map}
> 
> The word "new" is a loaded term, which usually means
> (or can be easily mistaken to mean) that a new object
> identity is guaranteed.  Thus, "new" shouldn't be used
> to specify the behavior of value-based classes.
> 
> Given that that the underlying objects are of VBCs,
> and that we are encouraging programmers to rely on
> the efficiency of chained copies, it should say something
> like this instead:
> 
> @return a {@code List} containing the same elements as the given collection
> @return a {@code Set} containing the same elements as the given collection
> @return a {@code Map} containing the same mappings as the given map
> 
> (Or even s/return a/return an unmodifiable/.)

OK, per your other message, we'll stick with 
Collectors.toUnmodifiableList/Set/Map, in the hope that in the future we can 
work on improving various incarnations of toList() to have more desirable 
properties.

Meanwhile, I agree that "@return the new {@code List}" is wrong and I'll adjust 
it (respectively, Set and Map).

Another point from our discussions is that the copyOf() methods should get an 
@implNote that says they'll try not to make unnecessary copies.

Also included are some markup changes and a small Set.copyOf implementation 
change suggested upthread.

Final(?) webrev:

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

Specdiff:

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

s'marks