RFR 8014824: Document Spliterator characteristics and binding policy of java util collection impls

[Mike Duigou]

On Aug 9 2013, at 06:04 , Paul Sandoz wrote:

> Hi Peter,
> 
> On Aug 8, 2013, at 12:44 PM, Peter Levart <peter.levart at gmail.com> wrote:
> 
>> Hi Paul,
>> 
>> Shouldn't Spliterators.EmptySpliterator also be IMMUTABLE, DISTINCT and ORDERED? Like Collections.singletonSpliterator...
>> 
> 
> Perhaps, for consistency. IIRC at the time it was felt a little odd to declare such characteristics when no elements are present.

Not commenting on the specific decisions but to express general policy:

For the empty/singleton cases it seems like the flags should match as close as possible those which would be found on a "real" collection used in the same context. The "specialness" of singleton/empty should be mostly for source efficiency and not alter the computation. For collections in general a common source of frustration comes from problems arising when there is a difference between the behaviour of the general and the "optimization". Consider:

List<String> bar = new ArrayList<>();
bar.add("Hello World");
List<String> foobar = Collections.unmodifiableList(bar);

List<String> fubar = Collections.singeltonList("Hello World");

Any cases where the behaviour of foobar and fubar differ are going to be a source of frustration for users. We end up having to work hard to ensure that such cases don't crop up. (Which is in part why exercises like adding Collections.unmodifiableNavigableMap/Set are so painful).

>> Although a mutable Collection implementation or immutable with size()>1 can never be Set and List at the same time, A singleton immutable Collection I think could be. Likewise for empty immutable Collection... So why couldn't a spliterator obtained from singleton List be DISTINCT? Likewise why couldn't a spliterator obtained from singleton Set be ORDERED?...
> 
> That could be an option, but i was hesitant about explicitly stating such optional constraints on Set/List.
> 
> For the current Collection implementations i would prefer not to enforce the reporting of characteristics for a size of 0 or 1.
> 
> 
>> These are runtime characteristics, not characteristics of a particular collection type.
>> 
> 
> For N > 1 I would argue characteristics of top-level spliterators do map to a particular collection type. Nearly all of the characteristics for at most one element are irrelevant for optimizing computation (SIZED/SUBSIZED/IMMUTABLE/NONULL are probably the most useful of the not very useful). It's almost as if nothing == everything in this case i.e. reporting no/few characteristics is the same as reporting all/most characteristics :-)
> 
> There is now Collections.emptyNavigableMap/emptySortedMap implying SORTED should also be reported for the empty spliterator, unless we optionally constrain SortedSet. 
> 
> There are currently no type safe ways to obtain a singleton NavigableMap/SortedSet, but perhaps there could be in the future? (there was probably a good reason for not adding them with the empty versions but i dunno what that reason was).

They weren't added mostly to keep the scope of adding the checked/unmodifiable/synchronized issue from being too involved. They could still be added.

> Reporting SORTED for all singletons is problematic because the singleton element may not be Comparable.

There's also the question of what to do when someone calls sort on it. There's an open question on whether Collections.sort should pre-check for size <= 1 and do nothing rather than throw UOE for Collections.singletonList(). It turns out most people find the UOE merely annoying and not useful. 

> 
> So i thought rather than attempting to be explicit about 0 or 1 element and the type holding that element it was just easier all round to do some hand-waving on Collections or Collection i.e. all bets are off as to what characteristics are reported (beyond that of SIZED/SUBSIZED/IMMUTABLE/NONNULL?) and it does not matter cause you will anyway not be able to to anything useful with them.
> 
> --
> 
> Perhaps i can separate out this webrev, i presume there is little issue with the other doc updates, if so i can commit those for this bug and spin up another for this aspect.
> 
> Paul.