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

[Stuart Marks]

On 11/1/17 1:50 PM, Roger Riggs wrote:
> Collection.java: Lines 110, 133, 166
> The bold labels probably want to be on their own lines and not terminated by 
> "." to look like headings
> (or be headings if the CSS supports them)
I'll change these to be actual headings.
> List.java: Consistency of markup references to unmodifiable List|Set|Map.
> The List.of constructors put the reference on a separate line, but the copyOf 
> constructor
> does not.  You could probably omit the blank line.
Yeah, I should update all of these at some point. Given that there are 30-odd 
more methods to change, plus I have a pile of other collections doc changes to 
work on, I think I'll do these in a separate doc pass.
> (BTW, the copyOf constructor does not always create a copy; I'm not sure if 
> the method
> name will result in an incorrect assumption but it may be misleading or a spec 
> issue.)
Right. I haven't been able to come up with any names that had the right 
semantics and that didn't also have connotations that were misleading in some 
other way. I observe that Guava's Immutable collections have copyOf() methods 
with pretty much the same semantics. The Guava docs do note that their methods 
try to avoid making a copy if they can, but they explicitly say that the 
circumstances under which this occurs are unspecified. I've considered adding an 
@apiNote to this effect, but I haven't been able to convince myself that it 
would be helpful to do so. It would seem to raise new issues that we're 
unwilling to answer, such as exactly when is a copy is made vs. when the 
argument is returned. Better, I think, to have people make a copy whenever they 
think they need a copy, and have the implementation short-circuit this when it can.

s'marks

>
> The same observations are true for Map and Set constructors.
>
> Thanks, Roger
>
>
>
>
> On 10/31/2017 7:49 PM, Stuart Marks wrote:
>> 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
>