RFR 8048689: Clarify documentation on BaseStream.spliterator

[Chris Hegarty]

Looks good to me Paul.

-Chris.

On 20/01/15 16:51, Paul Sandoz 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();
>