changeset 7561:04ecd3ef518c

Update doc for stream sources and lazy/non-lazy spliterators. Requires update to Spliterator for definition of laziness.
author psandoz
date Tue, 05 Mar 2013 15:41:47 +0100
parents 087eb459f122
children 8f30d1466232
files src/share/classes/java/util/stream/Streams.java src/share/classes/java/util/stream/package-info.java
diffstat 2 files changed, 44 insertions(+), 60 deletions(-) [+]
line wrap: on
line diff
--- a/src/share/classes/java/util/stream/Streams.java	Mon Mar 04 14:04:51 2013 -0500
+++ b/src/share/classes/java/util/stream/Streams.java	Tue Mar 05 15:41:47 2013 +0100
@@ -122,11 +122,9 @@
      * Creates a new sequential {@code Stream} whose source is a lazy
      * {@code Spliterator}.
      * <p>
-     * The {@code Spliterator} must be <b>lazy</b> and not commit to the
-     * sequence of elements it covers until it is invoked with a method that
-     * requires the sequence of elements be known.  For example, when the size
-     * estimate is required or when traversal occurs, but not when the
-     * characteristics are required.  See
+     * 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.
      *
@@ -142,11 +140,9 @@
      * Creates a new parallel {@code Stream} whose source is a lazy
      * {@code Spliterator}.
      * <p>
-     * The {@code Spliterator} must be <b>lazy</b> and not commit to the
-     * sequence of elements it covers until it is invoked with a method that
-     * requires the sequence of elements be known.  For example, when the size
-     * estimate is required or when traversal occurs, but not when the
-     * characteristics are required.  See
+     * 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.
      *
@@ -215,11 +211,9 @@
      * Creates a new sequential {@code IntStream} whose source is a lazy
      * {@code Spliterator.OfInt}.
      * <p>
-     * The {@code Spliterator.OfInt} must be <b>lazy</b> and not commit to the
-     * sequence of elements it covers until it is invoked with a method that
-     * requires the sequence of elements be known.  For example, when the size
-     * estimate is required or when traversal occurs, but not when the
-     * characteristics are required.  See
+     * 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.
      *
@@ -234,11 +228,9 @@
      * Creates a new parallel {@code IntStream} whose source is a lazy
      * {@code Spliterator.OfInt}.
      * <p>
-     * The {@code Spliterator.OfInt} must be <b>lazy</b> and not commit to the
-     * sequence of elements it covers until it is invoked with a method that
-     * requires the sequence of elements be known.  For example, when the size
-     * estimate is required or when traversal occurs, but not when the
-     * characteristics are required.  See
+     * 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.
      *
@@ -306,11 +298,9 @@
      * Creates a new sequential {@code LongStream} whose source is a lazy
      * {@code Spliterator.OfLong}.
      * <p>
-     * The {@code Spliterator.OfLong} must be <b>lazy</b> and not commit to the
-     * sequence of elements it covers until it is invoked with a method that
-     * requires the sequence of elements be known.  For example, when the size
-     * estimate is required or when traversal occurs, but not when the
-     * characteristics are required.  See
+     * 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.
      *
@@ -325,11 +315,9 @@
      * Creates a new parallel {@code LongStream} whose source is a lazy
      * {@code Spliterator.OfLong}.
      * <p>
-     * The {@code Spliterator.OfLong} must be <b>lazy</b> and not commit to the
-     * sequence of elements it covers until it is invoked with a method that
-     * requires the sequence of elements be known.  For example, when the size
-     * estimate is required or when traversal occurs, but not when the
-     * characteristics are required.  See
+     * 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.
      *
@@ -399,11 +387,9 @@
      * Creates a new sequential {@code DoubleStream} whose source is a lazy
      * {@code Spliterator.OfDouble}.
      * <p>
-     * The {@code Spliterator.OfDouble} must be <b>lazy</b> and not commit to
-     * the sequence of elements it covers until it is invoked with a method that
-     * requires the sequence of elements be known.  For example, when the size
-     * estimate is required or when traversal occurs, but not when the
-     * characteristics are required.  See
+     * 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.
      *
@@ -418,11 +404,9 @@
      * Creates a new parallel {@code DoubleStream} whose source is a lazy
      * {@code Spliterator.OfDouble}.
      * <p>
-     * The {@code Spliterator.OfDouble} must be <b>lazy</b> and not commit to
-     * the sequence of elements it covers until it is invoked with a method that
-     * requires the sequence of elements be known.  For example, when the size
-     * estimate is required or when traversal occurs, but not when the
-     * characteristics are required.  See
+     * 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.
      *
--- a/src/share/classes/java/util/stream/package-info.java	Mon Mar 04 14:04:51 2013 -0500
+++ b/src/share/classes/java/util/stream/package-info.java	Tue Mar 05 15:41:47 2013 +0100
@@ -78,40 +78,40 @@
  *
  * <h3><a name="StreamSources">Stream sources</a></h3>
  *
- * <p>A pipeline is initially constructed from a stream source. A stream source supplies a {@code Spliterator} that
- * covers elements of the source and provides element traversal operations for a possibly-parallel computation.  The
- * {@code Spliterator} is used to construct the initial {@code Stream} in the pipeline.  See methods on
- * {@link java.util.stream.Streams} for such construction.
+ * <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
+ * 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 {@code Spliterator}.  If so, that {@code Spliterator} must be <b>lazy</b> and not
- * commit to the sequence of elements it covers until the terminal operation commences.  More specifically the
- * {@code Spliterator} must not commit until it is invoked with a method that requires the sequence of elements be
- * known, for example when the size estimate is required or when traversal occurs.
+ * <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>If the contents of the source can be and are modified before the point at which the terminal operation commences
- * then those modifications must be reflected in the covered elements.  After that point, and depending on the
- * properties of the source, modifications might not be reflected in the covered elements and the throwing of a
- * {@code ConcurrentModificationException} may occur.
+ * <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, in the following code a list is created consisting of two strings "one" and "two", a stream is
- * created from that list, then the list is modified adding a third string "three", finally the elements of the stream
- * are collected and joined together. Since the list was modified before the terminal {@code collect} operation
- * commenced the result will be a string of "one two three":
+ * <p>For example, consider the following code:
  * <pre>
  *     List<String> l = new ArrayList(Arrays.asList("one", "two"));
  *     Stream<String> sl = l.stream();
  *     l.add("three");
  *     String s = sl.collect(toStringJoiner(" ")).toString();
  * </pre>
- * However, if the list is modified after the terminal operation commences then a
- * {@code ConcurrentModificationException} will occur, such as:
+ * First a list is created consisting of two strings: "one"; and "two". Then a stream is created from that list.
+ * Next the list is modified by adding a third string: "three".  Finally the elements of the stream are collected
+ * and joined together.  Since the list was modified before the terminal {@code collect} operation commenced
+ * the result will be a string of "one two three". However, if the list is modified after the terminal operation
+ * commences, as in:
  * <pre>
  *     List<String> l = new ArrayList(Arrays.asList("one", "two"));
  *     Stream<String> sl = l.stream();
  *     String s = sl.peek(s -> l.add("BAD LAMBDA")).collect(toStringJoiner(" ")).toString();
  * </pre>
- * Note: the lambda expression in the {@code peek} operation is modifying mutable state, see the section on
- * <em>Non-interference</em> for further details on the <em>non-interference</em> rules lambda expressions should obey.
+ * 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 do so indirectly using a
  * {@code Supplier} of a non-lazy {@code Spliterator}.  The {@code Spliterator} will be obtained from the