RFR: 8015320: Pull spliterator() up from Collection to Iterable

[Paul Sandoz]

On Jul 10, 2013, at 10:33 AM, Paul Sandoz <paul.sandoz at oracle.com> wrote:
> 
> On Jul 10, 2013, at 12:52 AM, Henry Jen <henry.jen at oracle.com> wrote:
> 
>> Hi,
>> 
>> Please review the webrev at
>> 
>> http://cr.openjdk.java.net/~henryjen/ccc/8015320.0/webrev/
>> 
>> This allows turning an Iterable into a stream with spliterator() methods
>> if the implementation provides one(like many Collection implementations)
>> rather than be forced to use less-efficient iterator().
>> 
>> Two small changes are not directly related,
>> - cleanup on SpliteratorCollisions.java test
>> - add a @see Spliterator for ConcurrentModificationException
>> 
> 
> Looks good.
> 

Drat, i spoke too soon.

I suggest the following change to the JavaDOc of Iterable.spliterator():

    /**
     * Creates a {@link Spliterator} over the elements described by this
     * {@code Iterable}.
     *
     * @implSpec
     * The default implementation creates an
     * <em><a href="Spliterator.html#binding">early-binding</a></em> spliterator
     * from the iterable's {@code Iterator}.  The spliterator inherits the
     * <em>fail-fast</em> properties of the iterable's iterator.

     * @implNote
     * The default implementation should usually be overridden.  The spliterator
     * returned by the default implementation has poor splitting capabilities,
     * is unsized, and does not report any spliterator characteristics.
     * Implementing classes can nearly always provide a better implementation.
     *
     * @return a {@code Spliterator} over the elements described by this
     * {@code Iterable}.
     * @since 1.8
     */
    default Spliterator<T> spliterator() {


Paul.