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

[Paul Sandoz]

On Aug 8, 2013, at 11:59 AM, Chris Hegarty <chris.hegarty at oracle.com> wrote:

> On 08/08/2013 10:00 AM, Paul Sandoz wrote:
>> Hi,
>> 
>> The following patch updates documentation for various spliterators:
>> 
>>   http://cr.openjdk.java.net/~psandoz/tl/JDK-8014824-split-docs/webrev/
>> 
>> Mostly this is just clarifying stuff that was missing, but there are a few cases of a spec change to Collections (CCC will be created):
>> 
>>   http://cr.openjdk.java.net/~psandoz/tl/JDK-8014824-split-docs/specdiff/overview-summary.html
>> 
>> This is for the Collection.empty/singleton/nCopies relaxing the reporting of characteristics for spliterators containing 0 or 1 elements. It's more efficient to share code for empty and singleton spliterator implementations (and instance for the former) rather than attempting to conform the required characteristics of the collection, which will anyway have little or no benefit in terms of the client trying to optimize based on those characteristics.
> 
> I understand the reason for these spec clarifications, but it just doesn't feel right, to me, that we return Collections that do not obey their own specification, even if we explicitly spell it out.
> 
> What is to stop others from doing the same? In which case a user can never depend on the specified characteristics being returned.
> 

You raise a good point, although we can never stop this, it is setting a poor example.

We could state something like the following on Collection:

* If the collection contains at most one element then the collections's spliterator is not 
* required to report characteristics specified
* by the {@link java.util.Set#spliterator()}. Since the
* spliterator covers at most one element such characteristics do not aid clients
* to control, specialize or simplify computation.

then perhaps it is not necessary to update the docs on Collections.

Note that it is easy to come across empty spliterators in convoluted ways. See Collections.nCopies which defers to using range which returns an empty stream if the range is zero.


> -Chris.
> 
> P.S. sorry if this has already been discussed, and agreed upon, elsewhere.
> 

As of now there has not been sufficient discussion on this.

Paul.