RFR 8048689: Clarify documentation on BaseStream.spliterator

[Lance Andersen]

Hi Paul,

I think this is OK though probably should have a CCC as the javadoc is being updated which providing more detail vs just a couple of typos.

Best
Lance
On Jan 20, 2015, at 11:51 AM, Paul Sandoz <paul.sandoz at oracle.com> wrote:

> Hi,
> 
> http://cr.openjdk.java.net/~psandoz/jdk9/JDK-8048689-BaseStream-spliterator/webrev/
> 
> Some clarifications to the characteristics of the Spliterator returned from BaseStream.spliterator() (otherwise known as the "escape-hatch" spliterator).
> 
> Implementations are free to report fewer characteristics than all those that could be derived from the stream pipeline.
> 
> For example, the current implementation does not support the propagation of NONNULL, IMMUTABLE or CONCURRENT through the stream pipeline. It could, we have room in the bit field for characteristic/flag propagation, but we did not think it worth the effort.
> 
> Paul.
> 
> diff -r 66508b45ff35 src/java.base/share/classes/java/util/stream/BaseStream.java
> --- a/src/java.base/share/classes/java/util/stream/BaseStream.java      Tue Jan 20 16:22:05 2015 +0000
> +++ b/src/java.base/share/classes/java/util/stream/BaseStream.java      Tue Jan 20 16:35:32 2015 +0000
> @@ -79,6 +79,14 @@
>      * <p>This is a <a href="package-summary.html#StreamOps">terminal
>      * operation</a>.
>      *
> +     * <p>
> +     * The returned spliterator should report the set of characteristics derived
> +     * from the stream pipeline (namely the characteristics derived from the
> +     * stream source spliterator and the intermediate operations).
> +     * Implementations may report a sub-set of those characteristics.  For
> +     * example, it may be too expensive to compute the entire set for some or
> +     * all possible stream pipelines.
> +     *
>      * @return the element spliterator for this stream
>      */
>     Spliterator<T> spliterator();
> 



Lance Andersen| Principal Member of Technical Staff | +1.781.442.2037
Oracle Java Engineering 
1 Network Drive 
Burlington, MA 01803
Lance.Andersen at oracle.com