RFR(m): 8177290 add copy factory methods for unmodifiable List, Set, Map
stuart.marks at oracle.com
Thu Nov 2 00:53:33 UTC 2017
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
> 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
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.
> 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:
>> 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
>>> 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.
>>> add copy factory methods for unmodifiable List, Set, Map
>>> add Collectors for collecting into unmodifiable List, Set, and Map
More information about the core-libs-dev