RFR 8048689: Clarify documentation on BaseStream.spliterator

[Paul Sandoz]

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();