changeset 7577:5344e45a16c5

Another go at docs for spliterator late-binding and spliterator-based stream construction methods.
author psandoz
date Fri, 08 Mar 2013 14:04:14 +0100
parents d5b536e37988
children 9d1608e74301
files src/share/classes/java/util/Spliterator.java src/share/classes/java/util/stream/Streams.java src/share/classes/java/util/stream/package-info.java
diffstat 3 files changed, 343 insertions(+), 170 deletions(-) [+]
line wrap: on
line diff
--- a/src/share/classes/java/util/Spliterator.java	Thu Mar 07 21:48:41 2013 -0800
+++ b/src/share/classes/java/util/Spliterator.java	Fri Mar 08 14:04:14 2013 +0100
@@ -52,6 +52,18 @@
  * be defined in the future, so implementors should not assign
  * meanings to unlisted values.
  *
+ * <p> A Spliterator that does not report {@code IMMUTABLE} or
+ * {@code CONCURRENT} is expected to have a documented policy concerning:
+ * <em>binding</em> to the element source; and structural interference of
+ * the element source detected during traversal.  A <em>late-binding</em>
+ * Spliterator does not bind to the source of elements it covers until
+ * traversed, split, or queried for estimated size.  Structural modifications
+ * made to the element source prior to binding are reflected in the elements
+ * covered when the Spliterator is bound.  Structural interference detected
+ * during traversal, due to modifications, after the Spliterator is bound may,
+ * for example, result in the throwing of a
+ * {@link ConcurrentModificationException}.
+ *
  * <p> To accommodate broad usage, this interface places no further
  * absolute demands on Spliterators. However, most default methods are
  * sub-optimal for most Spliterator implementations, and so should be
--- a/src/share/classes/java/util/stream/Streams.java	Thu Mar 07 21:48:41 2013 -0800
+++ b/src/share/classes/java/util/stream/Streams.java	Fri Mar 08 14:04:14 2013 +0100
@@ -82,87 +82,123 @@
     }
 
     /**
-     * Creates a new sequential {@code Stream} whose source is a
-     * {@code Supplier} of a non-lazy {@code Spliterator}.
+     * Creates a new sequential {@code Stream} from a {@code Supplier} of
+     * {@code Spliterator}.
      * <p>
-     * The non-lazy {@code Spliterator} is obtained from the {@code Supplier}
-     * when the terminal operation of the stream pipeline commences.  See
-     * <a href="package-summary.html#StreamSources">Stream sources</a> for more
-     * details.
+     * Exactly one spliterator is obtained from the supplier after, and never
+     * before, the terminal operation of the stream pipeline commences.
+     * <p>
+     * It is recommended that the spliterator not report a characteristic of
+     * {@code IMMUTABLE} and {@code CONCURRENT}, and not be
+     * <em>late-binding</em>.   Otherwise, it is more efficient to use the
+     * method {@link #stream(java.util.Spliterator)}.
+     * <p>
+     * The supplier provides a level of indirection that reduces the scope of
+     * potential interference to the interval starting with the commencing of
+     * the terminal operation and ending with the producing a result or
+     * side-effect.  See
+     * <a href="package-summary.html#Non-Interference">Non-Interference</a> for
+     * more details.
      *
-     * @param source A {@code Supplier} of a {@code Spliterator}
+     * @param supplier A {@code Supplier} of a {@code Spliterator}
      * @param characteristics Characteristics of the supplied
      *        {@code Spliterator}.  The characteristics must be equal to
      *        {@code source.get().getCharacteristics()}
      * @param <T> Type of elements
      * @return A new sequential {@code Stream}
      */
-    public static<T> Stream<T> stream(Supplier<? extends Spliterator<T>> source, int characteristics) {
-        Objects.requireNonNull(source);
-        return new ReferencePipeline<>(source,
+    public static<T> Stream<T> stream(Supplier<? extends Spliterator<T>> supplier, int characteristics) {
+        Objects.requireNonNull(supplier);
+        return new ReferencePipeline<>(supplier,
                                        StreamOpFlag.fromCharacteristics(characteristics) & ~StreamOpFlag.IS_PARALLEL);
     }
 
     /**
-     * Creates a new parallel {@code Stream} whose source is a {@code Supplier}
-     * of a non-lazy {@code Spliterator}.
+     * Creates a new parallel {@code Stream} from a {@code Supplier} of
+     * {@code Spliterator}.
      * <p>
-     * The non-lazy {@code Spliterator} is obtained from the {@code Supplier}
-     * when the terminal operation of the stream pipeline commences.
-     * See <a href="package-summary.html#StreamSources">Stream sources</a> for
+     * Exactly one spliterator is obtained from the supplier after, and never
+     * before, the terminal operation of the stream pipeline commences.
+     * <p>
+     * It is recommended that the spliterator not report a characteristic of
+     * {@code IMMUTABLE} and {@code CONCURRENT}, and not be
+     * <em>late-binding</em>.   Otherwise, it is more efficient to use the
+     * method {@link #stream(java.util.Spliterator)}.
+     * <p>
+     * The supplier provides a level of indirection that reduces the scope of
+     * potential interference to the interval starting with the commencing of
+     * the terminal operation and ending with the producing a result or
+     * side-effect.  See
+     * <a href="package-summary.html#Non-Interference">Non-Interference</a> for
      * more details.
      *
-     * @param source A {@code Supplier} of a {@code Spliterator}
+     * @param supplier A {@code Supplier} of a {@code Spliterator}
      * @param characteristics Characteristics of the supplied
-     *        {@code Spliterator}. The characteristics must be equal to
+     *        {@code Spliterator}.  The characteristics must be equal to
      *        {@code source.get().getCharacteristics()}
      * @param <T> Type of elements
      * @return A new parallel {@code Stream}
      */
-    public static<T> Stream<T> parallelStream(Supplier<? extends Spliterator<T>> source, int characteristics) {
-        Objects.requireNonNull(source);
-        return new ReferencePipeline<>(source,
+    public static<T> Stream<T> parallelStream(Supplier<? extends Spliterator<T>> supplier, int characteristics) {
+        Objects.requireNonNull(supplier);
+        return new ReferencePipeline<>(supplier,
                                        StreamOpFlag.fromCharacteristics(characteristics) | StreamOpFlag.IS_PARALLEL);
     }
 
     /**
-     * Creates a new sequential {@code Stream} whose source is a lazy
-     * {@code Spliterator}.
+     * Creates a new sequential {@code Stream} from a {@code Spliterator}.
      * <p>
-     * The {@code Spliterator} will not be operated on, such that it commits
-     * to the elements it covers, until the terminal operation commences.
-     * See
-     * <a href="package-summary.html#StreamSources">Stream sources</a> for more
-     * details.
+     * The spliterator is traversed, split or queried for estimated size after,
+     * and never before, the terminal operation of the stream pipeline
+     * commences.
+     * <p>
+     * It is strongly recommended the spliterator report a characteristic of
+     * {@code IMMUTABLE} or {@code CONCURRENT}, or be <em>late-binding</em> and
+     * not bind to the elements it covers until traversed, split or queried for
+     * estimated size.  Otherwise, the method
+     * {@link #stream(java.util.function.Supplier, int)} should be used.  Such a
+     * recommendation significantly reduces the scope of potential interference
+     * to the interval starting with the commencing of the terminal operation
+     * and ending with the producing a result or side-effect.  See
+     * <a href="package-summary.html#Non-Interference">Non-Interference</a> for
+     * more details.
      *
-     * @param source A {@code Spliterator}
+     * @param spliterator A {@code Spliterator}
      * @param <T> Type of elements
      * @return A new sequential {@code Stream}
      */
-    public static<T> Stream<T> stream(Spliterator<T> source) {
-        Objects.requireNonNull(source);
-        return new ReferencePipeline<>(() -> source,
-                                       StreamOpFlag.fromCharacteristics(source) & ~StreamOpFlag.IS_PARALLEL);
+    public static<T> Stream<T> stream(Spliterator<T> spliterator) {
+        Objects.requireNonNull(spliterator);
+        return new ReferencePipeline<>(() -> spliterator,
+                                       StreamOpFlag.fromCharacteristics(spliterator) & ~StreamOpFlag.IS_PARALLEL);
     }
 
     /**
-     * Creates a new parallel {@code Stream} whose source is a lazy
-     * {@code Spliterator}.
+     * Creates a new parallel {@code Stream} from a {@code Spliterator}.
      * <p>
-     * The {@code Spliterator} will not be operated on, such that it commits
-     * to the elements it covers, until the terminal operation commences.
-     * See
-     * <a href="package-summary.html#StreamSources">Stream sources</a> for more
-     * details.
+     * The spliterator is traversed, split or queried for estimated size after,
+     * and never before, the terminal operation of the stream pipeline
+     * commences.
+     * <p>
+     * It is strongly recommended the spliterator report a characteristic of
+     * {@code IMMUTABLE} or {@code CONCURRENT}, or be <em>late-binding</em> and
+     * not bind to the elements it covers until traversed, split or queried for
+     * estimated size.  Otherwise, the method
+     * {@link #stream(java.util.function.Supplier, int)} should be used.  Such a
+     * recommendation significantly reduces the scope of potential interference
+     * to the interval starting with the commencing of the terminal operation
+     * and ending with the producing a result or side-effect.  See
+     * <a href="package-summary.html#Non-Interference">Non-Interference</a> for
+     * more details.
      *
-     * @param source A {@code Spliterator}
+     * @param spliterator A {@code Spliterator}
      * @param <T> Type of elements
      * @return A new parallel {@code Stream}
      */
-    public static<T> Stream<T> parallelStream(Spliterator<T> source) {
-        Objects.requireNonNull(source);
-        return new ReferencePipeline<>(() -> source,
-                                       StreamOpFlag.fromCharacteristics(source) | StreamOpFlag.IS_PARALLEL);
+    public static<T> Stream<T> parallelStream(Spliterator<T> spliterator) {
+        Objects.requireNonNull(spliterator);
+        return new ReferencePipeline<>(() -> spliterator,
+                                       StreamOpFlag.fromCharacteristics(spliterator) | StreamOpFlag.IS_PARALLEL);
     }
 
     // IntStream construction
@@ -177,79 +213,115 @@
     }
 
     /**
-     * Creates a new sequential {@code IntStream} whose source is a
-     * {@code Supplier} of a non-lazy {@code Spliterator.OfInt}.
+     * Creates a new sequential {@code IntStream} from a {@code Supplier} of
+     * {@code Spliterator.OfInt}.
      * <p>
-     * The non-lazy {@code Spliterator.OfInt} is obtained from the
-     * {@code Supplier} when the terminal operation of the stream pipeline
-     * commences.
-     * See <a href="package-summary.html#StreamSources">Stream sources</a> for
+     * Exactly one spliterator is obtained from the supplier after, and never
+     * before, the terminal operation of the stream pipeline commences.
+     * <p>
+     * It is recommended that the spliterator not report a characteristic of
+     * {@code IMMUTABLE} and {@code CONCURRENT}, and not be
+     * <em>late-binding</em>.   Otherwise, it is more efficient to use the
+     * method {@link #intStream(java.util.Spliterator.OfInt)}.
+     * <p>
+     * The supplier provides a level of indirection that reduces the scope of
+     * potential interference to the interval starting with the commencing of
+     * the terminal operation and ending with the producing a result or
+     * side-effect.  See
+     * <a href="package-summary.html#Non-Interference">Non-Interference</a> for
      * more details.
      *
-     * @param source A {@code Supplier} of a {@code Spliterator.OfInt}
+     * @param supplier A {@code Supplier} of a {@code Spliterator.OfInt}
      * @param characteristics Characteristics of the supplied
      *        {@code Spliterator.OfInt}. The characteristics must be equal to
      *        {@code source.get().getCharacteristics()}
      * @return A new sequential {@code IntStream}
      */
-    public static IntStream intStream(Supplier<? extends Spliterator.OfInt> source, int characteristics) {
-        return new IntPipeline<>(source,
+    public static IntStream intStream(Supplier<? extends Spliterator.OfInt> supplier, int characteristics) {
+        return new IntPipeline<>(supplier,
                                  StreamOpFlag.fromCharacteristics(characteristics) & ~StreamOpFlag.IS_PARALLEL);
     }
 
     /**
-     * Creates a new parallel {@code IntStream} whose source is a
-     * {@code Supplier} of a non-lazy {@code Spliterator.OfInt}.
+     * Creates a new parallel {@code IntStream} from a {@code Supplier} of
+     * {@code Spliterator.OfInt}.
      * <p>
-     * The non-lazy {@code Spliterator.OfInt} is obtained from the
-     * {@code Supplier} when the terminal operation of the stream pipeline
-     * commences.
-     * See <a href="package-summary.html#StreamSources">Stream sources</a> for
+     * Exactly one spliterator is obtained from the supplier after, and never
+     * before, the terminal operation of the stream pipeline commences.
+     * <p>
+     * It is recommended that the spliterator not report a characteristic of
+     * {@code IMMUTABLE} and {@code CONCURRENT}, and not be
+     * <em>late-binding</em>.   Otherwise, it is more efficient to use the
+     * method {@link #intStream(java.util.Spliterator.OfInt)}.
+     * <p>
+     * The supplier provides a level of indirection that reduces the scope of
+     * potential interference to the interval starting with the commencing of
+     * the terminal operation and ending with the producing a result or
+     * side-effect.  See
+     * <a href="package-summary.html#Non-Interference">Non-Interference</a> for
      * more details.
      *
-     * @param source A {@code Supplier} of a {@code Spliterator.OfInt}
+     * @param supplier A {@code Supplier} of a {@code Spliterator.OfInt}
      * @param characteristics Characteristics of the supplied
      *        {@code Spliterator.OfInt}. The characteristics must be equal to
      *        {@code source.get().getCharacteristics()}
      * @return A new parallel {@code IntStream}
      */
-    public static IntStream intParallelStream(Supplier<? extends Spliterator.OfInt> source, int characteristics) {
-        return new IntPipeline<>(source,
+    public static IntStream intParallelStream(Supplier<? extends Spliterator.OfInt> supplier, int characteristics) {
+        return new IntPipeline<>(supplier,
                                  StreamOpFlag.fromCharacteristics(characteristics) | StreamOpFlag.IS_PARALLEL);
     }
 
     /**
-     * Creates a new sequential {@code IntStream} whose source is a lazy
+     * Creates a new sequential {@code IntStream} from a
      * {@code Spliterator.OfInt}.
      * <p>
-     * The {@code Spliterator.OfInt} will not be operated on, such that it
-     * commits to the elements it covers, until the terminal operation
-     * commences.  See
-     * <a href="package-summary.html#StreamSources">Stream sources</a> for more
-     * details.
+     * The spliterator is traversed, split or queried for estimated size after,
+     * and never before, the terminal operation of the stream pipeline
+     * commences.
+     * <p>
+     * It is strongly recommended the spliterator report a characteristic of
+     * {@code IMMUTABLE} or {@code CONCURRENT}, or be <em>late-binding</em> and
+     * not bind to the elements it covers until traversed, split or queried for
+     * estimated size.  Otherwise, the method
+     * {@link #intStream(java.util.function.Supplier, int)} should be used.
+     * Such a recommendation significantly reduces the scope of potential
+     * interference to the interval starting with the commencing of the terminal
+     * operation and ending with the producing a result or side-effect.  See
+     * <a href="package-summary.html#Non-Interference">Non-Interference</a> for
+     * more details.
      *
-     * @param source A {@code Spliterator.OfInt}
+     * @param spliterator A {@code Spliterator.OfInt}
      * @return A new sequential {@code IntStream}
      */
-    public static IntStream intStream(Spliterator.OfInt source) {
-        return intStream(() -> source, source.characteristics());
+    public static IntStream intStream(Spliterator.OfInt spliterator) {
+        return intStream(() -> spliterator, spliterator.characteristics());
     }
 
     /**
-     * Creates a new parallel {@code IntStream} whose source is a lazy
+     * Creates a new parallel {@code IntStream} from a
      * {@code Spliterator.OfInt}.
      * <p>
-     * The {@code Spliterator.OfInt} will not be operated on, such that it
-     * commits to the elements it covers, until the terminal operation
-     * commences.  See
-     * <a href="package-summary.html#StreamSources">Stream sources</a> for more
-     * details.
+     * The spliterator is traversed, split or queried for estimated size after,
+     * and never before, the terminal operation of the stream pipeline
+     * commences.
+     * <p>
+     * It is strongly recommended the spliterator report a characteristic of
+     * {@code IMMUTABLE} or {@code CONCURRENT}, or be <em>late-binding</em> and
+     * not bind to the elements it covers until traversed, split or queried for
+     * estimated size.  Otherwise, the method
+     * {@link #intStream(java.util.function.Supplier, int)} should be used.
+     * Such a recommendation significantly reduces the scope of potential
+     * interference to the interval starting with the commencing of the terminal
+     * operation and ending with the producing a result or side-effect.  See
+     * <a href="package-summary.html#Non-Interference">Non-Interference</a> for
+     * more details.
      *
-     * @param source A {@code Spliterator.OfInt}
+     * @param spliterator A {@code Spliterator.OfInt}
      * @return A new parallel {@code IntStream}
      */
-    public static IntStream intParallelStream(Spliterator.OfInt source) {
-        return intParallelStream(() -> source, source.characteristics());
+    public static IntStream intParallelStream(Spliterator.OfInt spliterator) {
+        return intParallelStream(() -> spliterator, spliterator.characteristics());
     }
 
     // LongStream construction
@@ -264,79 +336,115 @@
     }
 
     /**
-     * Creates a new sequential {@code LongStream} whose source is a
-     * {@code Supplier} of a non-lazy {@code Spliterator.OfLong}.
+     * Creates a new sequential {@code LongStream} from a {@code Supplier} of
+     * {@code Spliterator.OfLong}.
      * <p>
-     * The non-lazy {@code Spliterator.OfLong} is obtained from the
-     * {@code Supplier} when the terminal operation of the stream pipeline
-     * commences.  See
-     * <a href="package-summary.html#StreamSources">Stream sources</a> for more
-     * details.
+     * Exactly one spliterator is obtained from the supplier after, and never
+     * before, the terminal operation of the stream pipeline commences.
+     * <p>
+     * It is recommended that the spliterator not report a characteristic of
+     * {@code IMMUTABLE} and {@code CONCURRENT}, and not be
+     * <em>late-binding</em>.   Otherwise, it is more efficient to use the
+     * method {@link #longStream(java.util.Spliterator.OfLong)}.
+     * <p>
+     * The supplier provides a level of indirection that reduces the scope of
+     * potential interference to the interval starting with the commencing of
+     * the terminal operation and ending with the producing a result or
+     * side-effect.  See
+     * <a href="package-summary.html#Non-Interference">Non-Interference</a> for
+     * more details.
      *
-     * @param source A {@code Supplier} of a {@code Spliterator.OfLong}
+     * @param supplier A {@code Supplier} of a {@code Spliterator.OfLong}
      * @param characteristics Characteristics of the supplied
      *        {@code Spliterator.OfLong}. The characteristics must be equal to
      *        {@code source.get().getCharacteristics()}
      * @return A new sequential {@code LongStream}
      */
-    public static LongStream longStream(Supplier<? extends Spliterator.OfLong> source, int characteristics) {
-        return new LongPipeline<>(source,
+    public static LongStream longStream(Supplier<? extends Spliterator.OfLong> supplier, int characteristics) {
+        return new LongPipeline<>(supplier,
                                   StreamOpFlag.fromCharacteristics(characteristics) & ~StreamOpFlag.IS_PARALLEL);
     }
 
     /**
-     * Creates a new parallel {@code LongStream} whose source is a
-     * {@code Supplier} of a non-lazy {@code Spliterator.OfLong}.
+     * Creates a new parallel {@code LongStream} from a {@code Supplier} of
+     * {@code Spliterator.OfLong}.
      * <p>
-     * The non-lazy {@code Spliterator.OfLong} is obtained from the
-     * {@code Supplier} when the terminal operation of the stream pipeline
-     * commences.  See
-     * <a href="package-summary.html#StreamSources">Stream sources</a> for more
-     * details.
+     * Exactly one spliterator is obtained from the supplier after, and never
+     * before, the terminal operation of the stream pipeline commences.
+     * <p>
+     * It is recommended that the spliterator not report a characteristic of
+     * {@code IMMUTABLE} and {@code CONCURRENT}, and not be
+     * <em>late-binding</em>.   Otherwise, it is more efficient to use the
+     * method {@link #longStream(java.util.Spliterator.OfLong)}.
+     * <p>
+     * The supplier provides a level of indirection that reduces the scope of
+     * potential interference to the interval starting with the commencing of
+     * the terminal operation and ending with the producing a result or
+     * side-effect.  See
+     * <a href="package-summary.html#Non-Interference">Non-Interference</a> for
+     * more details.
      *
-     * @param source A {@code Supplier} of a {@code Spliterator.OfLong}
+     * @param supplier A {@code Supplier} of a {@code Spliterator.OfLong}
      * @param characteristics Characteristics of the supplied
      *        {@code Spliterator.OfLong}. The characteristics must be equal to
      *        {@code source.get().getCharacteristics()}
      * @return A new parallel {@code LongStream}
      */
-    public static LongStream longParallelStream(Supplier<? extends Spliterator.OfLong> source, int characteristics) {
-        return new LongPipeline<>(source,
+    public static LongStream longParallelStream(Supplier<? extends Spliterator.OfLong> supplier, int characteristics) {
+        return new LongPipeline<>(supplier,
                                   StreamOpFlag.fromCharacteristics(characteristics) | StreamOpFlag.IS_PARALLEL);
     }
 
     /**
-     * Creates a new sequential {@code LongStream} whose source is a lazy
+     * Creates a new sequential {@code LongStream} from a
      * {@code Spliterator.OfLong}.
      * <p>
-     * The {@code Spliterator.OfLong} will not be operated on, such that it
-     * commits to the elements it covers, until the terminal operation
-     * commences.  See
-     * <a href="package-summary.html#StreamSources">Stream sources</a> for more
-     * details.
+     * The spliterator is traversed, split or queried for estimated size after,
+     * and never before, the terminal operation of the stream pipeline
+     * commences.
+     * <p>
+     * It is strongly recommended the spliterator report a characteristic of
+     * {@code IMMUTABLE} or {@code CONCURRENT}, or be <em>late-binding</em> and
+     * not bind to the elements it covers until traversed, split or queried for
+     * estimated size.  Otherwise, the method
+     * {@link #longStream(java.util.function.Supplier, int)} should be used.
+     * Such a recommendation significantly reduces the scope of potential
+     * interference to the interval starting with the commencing of the terminal
+     * operation and ending with the producing a result or side-effect.  See
+     * <a href="package-summary.html#Non-Interference">Non-Interference</a> for
+     * more details.
      *
-     * @param source A {@code Spliterator.OfLong}
+     * @param spliterator A {@code Spliterator.OfLong}
      * @return A new sequential {@code LongStream}
      */
-    public static LongStream longStream(Spliterator.OfLong source) {
-        return longStream(() -> source, source.characteristics());
+    public static LongStream longStream(Spliterator.OfLong spliterator) {
+        return longStream(() -> spliterator, spliterator.characteristics());
     }
 
     /**
-     * Creates a new parallel {@code LongStream} whose source is a lazy
+     * Creates a new parallel {@code LongStream} from a
      * {@code Spliterator.OfLong}.
      * <p>
-     * The {@code Spliterator.OfLong} will not be operated on, such that it
-     * commits to the elements it covers, until the terminal operation
-     * commences.  See
-     * <a href="package-summary.html#StreamSources">Stream sources</a> for more
-     * details.
+     * The spliterator is traversed, split or queried for estimated size after,
+     * and never before, the terminal operation of the stream pipeline
+     * commences.
+     * <p>
+     * It is strongly recommended the spliterator report a characteristic of
+     * {@code IMMUTABLE} or {@code CONCURRENT}, or be <em>late-binding</em> and
+     * not bind to the elements it covers until traversed, split or queried for
+     * estimated size.  Otherwise, the method
+     * {@link #longStream(java.util.function.Supplier, int)} should be used.
+     * Such a recommendation significantly reduces the scope of potential
+     * interference to the interval starting with the commencing of the terminal
+     * operation and ending with the producing a result or side-effect.  See
+     * <a href="package-summary.html#Non-Interference">Non-Interference</a> for
+     * more details.
      *
-     * @param source A {@code Spliterator.OfLong}
+     * @param spliterator A {@code Spliterator.OfLong}
      * @return A new parallel {@code LongStream}
      */
-    public static LongStream longParallelStream(Spliterator.OfLong source) {
-        return longParallelStream(() -> source, source.characteristics());
+    public static LongStream longParallelStream(Spliterator.OfLong spliterator) {
+        return longParallelStream(() -> spliterator, spliterator.characteristics());
     }
 
     // DoubleStream construction
@@ -351,81 +459,117 @@
     }
 
     /**
-     * Creates a new sequential {@code DoubleStream} whose source is a
-     * {@code Supplier} of a non-lazy {@code Spliterator.OfDouble}.
+     * Creates a new sequential {@code DoubleStream} from a {@code Supplier} of
+     * {@code Spliterator.OfDouble}.
      * <p>
-     * The non-lazy {@code Spliterator.OfDouble} is obtained from the
-     * {@code Supplier} when the terminal operation of the stream pipeline
-     * commences.  See
-     * <a href="package-summary.html#StreamSources">Stream sources</a> for more
-     * details.
+     * Exactly one spliterator is obtained from the supplier after, and never
+     * before, the terminal operation of the stream pipeline commences.
+     * <p>
+     * It is recommended that the spliterator not report a characteristic of
+     * {@code IMMUTABLE} and {@code CONCURRENT}, and not be
+     * <em>late-binding</em>.   Otherwise, it is more efficient to use the
+     * method {@link #doubleStream(java.util.Spliterator.OfDouble)}.
+     * <p>
+     * The supplier provides a level of indirection that reduces the scope of
+     * potential interference to the interval starting with the commencing of
+     * the terminal operation and ending with the producing a result or
+     * side-effect.  See
+     * <a href="package-summary.html#Non-Interference">Non-Interference</a> for
+     * more details.
      *
-     * @param source A {@code Supplier} of a {@code Spliterator.OfDouble}
+     * @param supplier A {@code Supplier} of a {@code Spliterator.OfDouble}
      * @param characteristics Characteristics of the supplied
      *        {@code Spliterator.OfDouble}. The characteristics must be equal to
      *        {@code source.get().getCharacteristics()}
      * @return A new sequential {@code DoubleStream}
      */
-    public static DoubleStream doubleStream(Supplier<? extends Spliterator.OfDouble> source,
+    public static DoubleStream doubleStream(Supplier<? extends Spliterator.OfDouble> supplier,
                                             int characteristics) {
-        return new DoublePipeline<>(source,
+        return new DoublePipeline<>(supplier,
                                     StreamOpFlag.fromCharacteristics(characteristics) & ~StreamOpFlag.IS_PARALLEL);
     }
 
     /**
-     * Creates a new parallel {@code DoubleStream} whose source is a
-     * {@code Supplier} of a non-lazy {@code Spliterator.OfDouble}.
+     * Creates a new parallel {@code DoubleStream} from a {@code Supplier} of
+     * {@code Spliterator.OfDouble}.
      * <p>
-     * The non-lazy {@code Spliterator.OfDouble} is obtained from the
-     * {@code Supplier} when the terminal operation of the stream pipeline
-     * commences.  See
-     * <a href="package-summary.html#StreamSources">Stream sources</a> for more
-     * details.
+     * Exactly one spliterator is obtained from the supplier after, and never
+     * before, the terminal operation of the stream pipeline commences.
+     * <p>
+     * It is recommended that the spliterator not report a characteristic of
+     * {@code IMMUTABLE} and {@code CONCURRENT}, and not be
+     * <em>late-binding</em>.   Otherwise, it is more efficient to use the
+     * method {@link #doubleStream(java.util.Spliterator.OfDouble)}.
+     * <p>
+     * The supplier provides a level of indirection that reduces the scope of
+     * potential interference to the interval starting with the commencing of
+     * the terminal operation and ending with the producing a result or
+     * side-effect.  See
+     * <a href="package-summary.html#Non-Interference">Non-Interference</a> for
+     * more details.
      *
-     * @param source A {@code Supplier} of a {@code Spliterator.OfDouble}
+     * @param supplier A {@code Supplier} of a {@code Spliterator.OfDouble}
      * @param characteristics Characteristics of the supplied
      *        {@code Spliterator.OfDouble}. The characteristics must be equal to
      *        {@code source.get().getCharacteristics()}
      * @return A new parallel {@code DoubleStream}
      */
-    public static DoubleStream doubleParallelStream(Supplier<? extends Spliterator.OfDouble> source,
+    public static DoubleStream doubleParallelStream(Supplier<? extends Spliterator.OfDouble> supplier,
                                                     int characteristics) {
-        return new DoublePipeline<>(source,
+        return new DoublePipeline<>(supplier,
                                     StreamOpFlag.fromCharacteristics(characteristics) | StreamOpFlag.IS_PARALLEL);
     }
 
     /**
-     * Creates a new sequential {@code DoubleStream} whose source is a lazy
+     * Creates a new sequential {@code DoubleStream} from a
      * {@code Spliterator.OfDouble}.
      * <p>
-     * The {@code Spliterator.OfDouble} will not be operated on, such that it
-     * commits to the elements it covers, until the terminal operation
-     * commences.  See
-     * <a href="package-summary.html#StreamSources">Stream sources</a> for more
-     * details.
+     * The spliterator is traversed, split or queried for estimated size after,
+     * and never before, the terminal operation of the stream pipeline
+     * commences.
+     * <p>
+     * It is strongly recommended the spliterator report a characteristic of
+     * {@code IMMUTABLE} or {@code CONCURRENT}, or be <em>late-binding</em> and
+     * not bind to the elements it covers until traversed, split or queried for
+     * estimated size.  Otherwise, the method
+     * {@link #doubleStream(java.util.function.Supplier, int)} should be used.
+     * Such a recommendation significantly reduces the scope of potential
+     * interference to the interval starting with the commencing of the terminal
+     * operation and ending with the producing a result or side-effect.  See
+     * <a href="package-summary.html#Non-Interference">Non-Interference</a> for
+     * more details.
      *
-     * @param source A {@code Spliterator.OfDouble}
+     * @param spliterator A {@code Spliterator.OfDouble}
      * @return A new sequential {@code DoubleStream}
      */
-    public static DoubleStream doubleStream(Spliterator.OfDouble source) {
-        return doubleStream(() -> source, source.characteristics());
+    public static DoubleStream doubleStream(Spliterator.OfDouble spliterator) {
+        return doubleStream(() -> spliterator, spliterator.characteristics());
     }
 
     /**
-     * Creates a new parallel {@code DoubleStream} whose source is a lazy
+     * Creates a new parallel {@code DoubleStream} from a
      * {@code Spliterator.OfDouble}.
      * <p>
-     * The {@code Spliterator.OfDouble} will not be operated on, such that it
-     * commits to the elements it covers, until the terminal operation
-     * commences.  See
-     * <a href="package-summary.html#StreamSources">Stream sources</a> for more
-     * details.
+     * The spliterator is traversed, split or queried for estimated size after,
+     * and never before, the terminal operation of the stream pipeline
+     * commences.
+     * <p>
+     * It is strongly recommended the spliterator report a characteristic of
+     * {@code IMMUTABLE} or {@code CONCURRENT}, or be <em>late-binding</em> and
+     * not bind to the elements it covers until traversed, split or queried for
+     * estimated size.  Otherwise, the method
+     * {@link #doubleStream(java.util.function.Supplier, int)} should be used.
+     * Such a recommendation significantly reduces the scope of potential
+     * interference to the interval starting with the commencing of the terminal
+     * operation and ending with the producing a result or side-effect.  See
+     * <a href="package-summary.html#Non-Interference">Non-Interference</a> for
+     * more details.
      *
-     * @param source A {@code Spliterator.OfDouble}
+     * @param spliterator A {@code Spliterator.OfDouble}
      * @return A new parallel {@code DoubleStream}
      */
-    public static DoubleStream doubleParallelStream(Spliterator.OfDouble source) {
-        return doubleParallelStream(() -> source, source.characteristics());
+    public static DoubleStream doubleParallelStream(Spliterator.OfDouble spliterator) {
+        return doubleParallelStream(() -> spliterator, spliterator.characteristics());
     }
 
     // Infinite Stream generators
--- a/src/share/classes/java/util/stream/package-info.java	Thu Mar 07 21:48:41 2013 -0800
+++ b/src/share/classes/java/util/stream/package-info.java	Fri Mar 08 14:04:14 2013 +0100
@@ -78,19 +78,40 @@
  *
  * <h3><a name="StreamSources">Stream sources</a></h3>
  *
- * <p>A pipeline is initially constructed from a {@link Spliterator} instance supplied by a stream source.
- * The {@code Spliterator} instance covers elements of the source and provides element traversal operations
+ * XXX - change to section to stream construction gradually introducing more
+ *       complex ways to construct
+ *     - construction from Collection
+ *     - construction from Iterator
+ *     - construction from array
+ *     - construction from generators
+ *     - construction from spliterator
+ *
+ * XXX - the following is quite low-level but important aspect of stream constriction
+ *
+ * <p>A pipeline is initially constructed from a spliterator (see {@link Spliterator}) supplied by a stream source.
+ * The spliterator covers elements of the source and provides element traversal operations
  * for a possibly-parallel computation.  See methods on {@link java.util.stream.Streams} for construction
  * of pipelines using spliterators.
  *
- * <p>A source may directly supply a lazy {@code Spliterator} instance [link to definition on Spliterator when available].
- * If so, the {@code Spliterator} will not be operated on, such that it commits to the elements it covers,
- * until the terminal operation commences.  For example, methods such as {@link java.util.Spliterator#estimateSize()} and
- * {@link java.util.Spliterator#forEach(java.util.function.Consumer)} will not be invoked before the terminal
- * operation commences.
+ * <p>A source may directly supply a spliterator.  If so, the spliterator is traversed, split, or queried
+ * for estimated size after, and never before, the terminal operation commences. It is strongly recommended
+ * that the spliterator report a characteristic of {@code IMMUTABLE} or {@code CONCURRENT}, or be
+ * <em>late-binding</em> and not bind to the elements it covers until traversed, split or queried for
+ * estimated size
  *
- * <p>A source can be modified before the terminal operation commences and those modifications will be reflected in the
- * covered elements.  Afterwards, and depending on the properties of the source, further modifications
+ * <p>If a source cannot directly supply a recommended spliterator then it may indirectly supply a spliterator
+ * using a {@code Supplier}.  The spliterator is obtained from the supplier after, and never before, the terminal
+ * operation of the stream pipeline commences.
+ *
+ * <p>Such requirements significantly reduce the scope of potential interference to the interval starting
+ * with the commencing of the terminal operation and ending with the producing a result or side-effect.  See
+ * <a href="package-summary.html#Non-Interference">Non-Interference</a> for
+ * more details.
+ *
+ * XXX - move the following to the non-interference section
+ *
+ * <p>A source can be modified before the terminal operation commences and those modifications will be reflected in
+ * the covered elements.  Afterwards, and depending on the properties of the source, further modifications
  * might not be reflected and the throwing of a {@code ConcurrentModificationException} may occur.
  *
  * <p>For example, consider the following code:
@@ -113,10 +134,6 @@
  * then a {@code ConcurrentModificationException} will be thrown since the {@code peek} operation will attempt
  * to add the string "BAD LAMBDA" to the list after the terminal operation has commenced.
  *
- * <p>If a source cannot directly supply a lazy {@code Spliterator}, then it may lazily supply a non-lazy
- * {@code Spliterator} using a {@code Supplier}. The {@code Spliterator} will only be obtained from the
- * {@code Supplier} when the terminal operation commences.
- *
  * <h3><a name="StreamOps">Stream operations</a></h3>
  *
  * <p>Stream operations are divided into two categories: <em>intermediate</em> and <em>terminal</em>.  An
@@ -190,7 +207,7 @@
  * result of executing {@code map(x -> x*2)} must be {@code [2, 4, 6]}.  However, if the source has no
  * defined encounter order, than any permutation of the values {@code [2, 4, 6]} would be a valid result.
  *
- * <h2>Non-interference</h2>
+ * <h2><a name="Non-Interference">Non-interference</h2>
  *
  * XXX Multiple forms of interference: mutating source from outside, mutating source from lambda,
  * lambdas sharing mutable state