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

[Chris Hegarty]

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.

-Chris.

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

>
> Paul.
>