RFR JDK-8010096 : Initial java.util.Spliterator putback

[Chris Hegarty]

Nice work Paul, some small comments.

- new javadocs tags, @implSpec, @apiNote, etc. I really like the use of
   implSpec to define the behavior of this implementations default
   methods. There is probably a separate thread, but any idea when these
   will be generated in the javadoc, not just the lambda docs?

- Iterator.remove @since 1.8? I see there is a conflict here between
   when the method was originally added and its default

  - Spliterator class level examples are not showing in the specdiff.
    Are these really API Notes? Maybe they are.

-Chris.

On 03/28/2013 03:59 PM, Paul Sandoz wrote:
> Hi,
>
> http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=8010096
>
> Webrev:
> http://cr.openjdk.java.net/~psandoz/lambda/spliterator/jdk-8010096/webrev/
>
> Spec diff:
> http://cr.openjdk.java.net/~psandoz/lambda/spliterator/jdk-8010096/specdiff/overview-summary.html
>
> Relevant JavaDoc generated from lambda repo (required for viewing @apiNote, @implSpec, @implNote declarations):
> http://cr.openjdk.java.net/~psandoz/lambda/spliterator/jdk-8010096/api/java/
>
> Note: some of the JavaDoc generated from the lambda repo may contain additional methods or specification that is relevant to the stream framework.
>
> --
>
> To enable bulk operations, in parallel, on a data source it is required that such a source efficiently partition itself into smaller parts, where parts are processed concurrently, and each part is traversed sequentially.
>
> A new data interface is required that defines the contract for efficient partitioning and traversal.
>
> Collections need to implement that new data interface so the JSR-335 stream library can support bulk operations on common collection implementations, such as List/Set and arrays, in addition to other forms of data source e.g. third party collections.
>
> java.util.Spliterator, and primitive specializations of, is the key data interface that enables partitioning and traversal. JSR-335 java.util.stream.Stream instances will be constructed from spliterators.
>
> Collection is extended to define the default method spliterator(). Implementations are expected to override this method. The default implementation utilizes the collection's iterator and size to provide a spliterator implementation that permits limited parallism.  Default overriding implementations are also provided for List, Set and SortedSet that support additional properties associated with those collections.
>
> Together with Spliterator some implementations are provided for creating Spliterator instances from data sources that are iterators and arrays.
>
> Note: Optimal spliterator implementations for many collection implementations in java.util and java.util.concurrent are present in the lambda repository and will duly make their way into TL after this webrev has been reviewed and pushed.
>
> --
>
> Once this webrev is reviewed and pushed then the Stream API can follow, and then the fun really begins :-)
>
> The class com.sun.tools.jdi/EventSetImpl has been modified but is likely to change when spliterator implementations are pushed. This class cannot decide if it wants to be a List or a Set!! The compiler cannot work out if the default implementation of spliterator() for List or Set should apply. When the concrete collection implementations of spliterator arrive this class will not need to implement spliterator() and will inherit the implementation from ArrayList (implementations on classes always win over default implementations on interfaces).
>
> Unfortunately to build TL with this patch applied requires one also apply:
>
>    http://hg.openjdk.java.net/lambda/lambda/jdk/rev/fbcafacf92ef
>
> Which i suspect was lost in the wash and should have been pushed to TL a while ago. Will follow up with Robert on that one.
>
> A JPRT of TL with both patches applied did not show any abnormal test failures.
>
> Paul.
>