changeset 8270:f2fe1654f65c

review comments from David Holmes Contributed-by: David Holmes <david.holmes@oracle.com>
author mduigou
date Sat, 20 Apr 2013 14:25:00 -0700
parents 62ee7f5ff8d1
children 9bcec44fa73d
files src/share/classes/java/util/stream/CloseableStream.java src/share/classes/java/util/stream/Collector.java src/share/classes/java/util/stream/DoubleStream.java src/share/classes/java/util/stream/IntStream.java src/share/classes/java/util/stream/LongStream.java src/share/classes/java/util/stream/Stream.java
diffstat 6 files changed, 279 insertions(+), 169 deletions(-) [+]
line wrap: on
line diff
--- a/src/share/classes/java/util/stream/CloseableStream.java	Sat Apr 20 17:25:38 2013 -0400
+++ b/src/share/classes/java/util/stream/CloseableStream.java	Sat Apr 20 14:25:00 2013 -0700
@@ -30,7 +30,7 @@
  * The close method is invoked to release resources that the object is
  * holding (such as open files).
  *
- * @param <T> the type of stream elements
+ * @param <T> The type of stream elements
  * @since 1.8
  */
 public interface CloseableStream<T> extends Stream<T>, AutoCloseable {
@@ -41,7 +41,7 @@
      * {@code try}-with-resources statement.  Does nothing if called when
      * the resource has already been closed.
      *
-     * This method does not allow throwing checked {@code Exception} like
+     * This method does not allow throwing checked {@code Exception}s like
      * {@link AutoCloseable#close() AutoCloseable.close()}. Cases where the
      * close operation may fail require careful attention by implementers. It
      * is strongly advised to relinquish the underlying resources and to
--- a/src/share/classes/java/util/stream/Collector.java	Sat Apr 20 17:25:38 2013 -0400
+++ b/src/share/classes/java/util/stream/Collector.java	Sat Apr 20 14:25:00 2013 -0700
@@ -46,10 +46,10 @@
  * mutable reduction tasks:
  * <pre>{@code
  *     // Accumulate elements into a List
- *     List list = stream.collect(Collectors.toList());
+ *     List<String> list = stream.collect(Collectors.toList());
  *
  *     // Accumulate elements into a TreeSet
- *     List list = stream.collect(Collectors.toCollection(TreeSet::new));
+ *     Set<String> list = stream.collect(Collectors.toCollection(TreeSet::new));
  *
  *     // Convert elements to strings and concatenate them, separated by commas
  *     String joined = stream.map(Object::toString)
@@ -238,7 +238,7 @@
          * a {@link Set}.
          */
         UNORDERED,
-        
+
         /**
          * Indicates that this collector operates by strict mutation of its
          * result container. This means that the {@link #accumulator()} and
--- a/src/share/classes/java/util/stream/DoubleStream.java	Sat Apr 20 17:25:38 2013 -0400
+++ b/src/share/classes/java/util/stream/DoubleStream.java	Sat Apr 20 14:25:00 2013 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -42,9 +42,10 @@
 
 /**
  * A sequence of primitive double elements supporting sequential and parallel
- * bulk operations. Streams support lazy transformative operations (transforming
- * a stream to another stream) such as {@code filter} and {@code map}, and
- * consuming operations, such as {@code forEach}, {@code findFirst}, and {@code
+ * bulk operations. Streams support lazy intermediate operations (transforming
+ * a stream to another stream) such as {@code filter} and {@code map}, and terminal
+ * operations (consuming the contents of a stream to produce a result or
+ * side-effect), such as {@code forEach}, {@code findFirst}, and {@code
  * iterator}.  Once an operation has been performed on a stream, it
  * is considered <em>consumed</em> and no longer usable for other operations.
  *
@@ -56,7 +57,15 @@
  * stream operations preserve the <a href="package-summary.html#Ordering">
  * encounter order</a> of their source, and terminal operations
  * respect the encounter order of their source, if the source
- * has an encounter order.
+ * has an encounter order.  Provided that and parameters to stream operations
+ * satisfy the <a href="package-summary.html#NonInterference">non-interference
+ * requirements</a>, and excepting differences arising from the absence of
+ * a defined encounter order, the result of a stream pipeline should be the
+ * stable across multiple executions of the same operations on the same source.
+ * However, the timing and thread in which side-effects occur (for those
+ * operations which are allowed to produce side-effects, such as
+ * {@link #forEach(DoubleConsumer)}), are explicitly nondeterministic for parallel
+ * execution of stream pipelines.
  *
  * <p>Unless otherwise noted, passing a {@code null} argument to any stream
  * method may result in a {@link NullPointerException}.
@@ -107,36 +116,36 @@
      * <p>This is an <a href="package-summary.html#StreamOps">
      *     intermediate operation</a>.
      *
-     * @param <U> The element type of the new stream
+     * @param <U> the element type of the new stream
      * @param mapper a <a href="package-summary.html#NonInterference">
-     *               non-interfering, stateless</a> function to apply to
-     *               each element
+     *               non-interfering, stateless</a> function to apply to each
+     *               element
      * @return the new stream
      */
     <U> Stream<U> mapToObj(DoubleFunction<? extends U> mapper);
 
     /**
-     * Returns an {@code IntStream} consisting of the results of applying
-     * the given function to the elements of this stream.
+     * Returns an {@code IntStream} consisting of the results of applying the
+     * given function to the elements of this stream.
      *
-     * <p>This is an <a href="package-summary.html#StreamOps">
-     *     intermediate operation</a>.
+     * <p>This is an <a href="package-summary.html#StreamOps">intermediate
+     * operation</a>.
      *
      * @param mapper a <a href="package-summary.html#NonInterference">
-     *               non-interfering, stateless</a> function to apply to
-     *               each element
+     *               non-interfering, stateless</a> function to apply to each
+     *               element
      * @return the new stream
      */
     IntStream mapToInt(DoubleToIntFunction mapper);
 
     /**
-     * Returns a {@code LongStream} consisting of the results of applying
-     * the given function to the elements of this stream.
+     * Returns a {@code LongStream} consisting of the results of applying the
+     * given function to the elements of this stream.
      *
-     * <p>This is an <a href="package-summary.html#StreamOps">
-     *     intermediate operation</a>.
+     * <p>This is an <a href="package-summary.html#StreamOps">intermediate
+     * operation</a>.
      *
-     * @param mapper A <a href="package-summary.html#NonInterference">
+     * @param mapper a <a href="package-summary.html#NonInterference">
      *               non-interfering, stateless</a> function to apply to each
      *               element
      * @return the new stream
@@ -144,16 +153,28 @@
     LongStream mapToLong(DoubleToLongFunction mapper);
 
     /**
-     * Returns a stream consisting of the results of replacing each
-     * element of this stream with the contents of the stream
-     * produced by applying the provided function to each element.
+     * Returns a stream consisting of the results of replacing each element of
+     * this stream with the contents of the stream produced by applying the
+     * provided mapping function to each element.
      *
      * <p>This is an <a href="package-summary.html#StreamOps">intermediate
      * operation</a>.
      *
+     * @apiNote
+     * The {@code flatMap()} operation has the effect of applying a one-to-many
+     * tranformation to the elements of the stream, and then flattening the
+     * resulting elements into a new stream. For example, if {@code orders}
+     * is a stream of purchase orders, and each purchase order contains a
+     * collection of line items, then the following produces a stream of line
+     * items:
+     * <pre>{@code
+     *     orderStream.flatMap(order -> order.getLineItems().stream())...
+     * }</pre>
+     *
      * @param mapper a <a href="package-summary.html#NonInterference">
-     *               non-interfering, stateless</a> function to apply to each
-     *               element which produces a stream of new values
+     *               non-interfering, stateless</a> function to apply to
+     *               each element which produces an {@code DoubleStream} of new
+     *               values
      * @return the new stream
      * @see Stream#flatMap(Function)
      */
@@ -220,11 +241,12 @@
      *
      * @param maxSize the number of elements the stream should be limited to
      * @return the new stream
+     * @throws IllegalArgumentException if {@code maxSize} is negative
      */
     DoubleStream limit(long maxSize);
 
     /**
-     * Produces a stream consisting of the remaining elements of this stream
+     * Returns a stream consisting of the remaining elements of this stream
      * after discarding the first {@code startingOffset} elements (or all
      * elements if the stream has fewer than {@code startingOffset} elements).
      *
@@ -233,6 +255,7 @@
      *
      * @param startingOffset the number of leading elements to skip
      * @return the new stream
+     * @throws IllegalArgumentException if {@code startingOffset} is negative
      */
     DoubleStream substream(long startingOffset);
 
@@ -240,7 +263,8 @@
      * Returns a stream consisting of the elements of this stream after
      * discarding the first {@code startingOffset} elements (or all elements
      * if the stream has fewer than {@code startingOffset} elements), and
-     * truncating the remainder to be no longer than {@code maxSize} in length.
+     * truncating the remainder to be no longer than
+     * {@code endingOffset - startOffset} in length.
      *
      * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
      * stateful intermediate operation</a>.
@@ -248,11 +272,14 @@
      * @param startingOffset the starting position of the substream, inclusive
      * @param endingOffset the ending position of the substream, exclusive
      * @return the new stream
+     * @throws IllegalArgumentException if {@code startingOffset} or
+     * {@code endingOffset} is negative or {@code startingOffset} is greater
+     * than {@code endingOffset}
      */
     DoubleStream substream(long startingOffset, long endingOffset);
 
     /**
-     * Performs an operation for each element of this stream.
+     * Performs an action for each element of this stream.
      *
      * <p>This is a <a href="package-summary.html#StreamOps">terminal
      * operation</a>.
@@ -261,27 +288,27 @@
      * guarantee to respect the encounter order of the stream, as doing so
      * would sacrifice the benefit of parallelism.  For any given element, the
      * action may be performed at whatever time and in whatever thread the
-     * library chooses.  If the operation accesses shared state, it is
+     * library chooses.  If the action accesses shared state, it is
      * responsible for providing the required synchronization.
      *
-     * @param consumer a <a href="package-summary.html#NonInterference">
-     *                 non-interfering</a> action to perform on the elements
+     * @param action a <a href="package-summary.html#NonInterference">
+     *               non-interfering</a> action to perform on the elements
      */
-    void forEach(DoubleConsumer consumer);
+    void forEach(DoubleConsumer action);
 
     /**
-     * Performs an operation for each element of this stream, guaranteeing that
+     * Performs an action for each element of this stream, guaranteeing that
      * each element is processed in encounter order for streams that have a
      * defined encounter order.
      *
      * <p>This is a <a href="package-summary.html#StreamOps">terminal
      * operation</a>.
      *
-     * @param consumer a <a href="package-summary.html#NonInterference">
-     *                 non-interfering</a> action to perform on the elements
+     * @param action a <a href="package-summary.html#NonInterference">
+     *               non-interfering</a> action to perform on the elements
      * @see #forEach(DoubleConsumer)
      */
-    void forEachOrdered(DoubleConsumer consumer);
+    void forEachOrdered(DoubleConsumer action);
 
     /**
      * Returns an array containing the elements of this stream.
@@ -295,8 +322,8 @@
 
     /**
      * Performs a <a href="package-summary.html#Reduction">reduction</a> on the
-     * elements of this stream, using the provided identity value and
-     * an <a href="package-summary.html#Associativity">associative</a>
+     * elements of this stream, using the provided identity value and an
+     * <a href="package-summary.html#Associativity">associative</a>
      * accumulation function, and returns the reduced value.  This is equivalent
      * to:
      * <pre>{@code
@@ -319,6 +346,7 @@
      *
      * @apiNote Sum, min, max, and average are all special cases of reduction.
      * Summing a stream of numbers can be expressed as:
+
      * <pre>{@code
      *     double sum = numbers.reduce(0, (a, b) -> a+b);
      * }</pre>
@@ -336,9 +364,8 @@
      *
      * @param identity the identity value for the accumulating function
      * @param op an <a href="package-summary.html#Associativity">associative</a>
-     *           <a href="package-summary.html#NonInterference">
-     *           non-interfering, stateless</a> function for combining two
-     *           values
+     *                    <a href="package-summary.html#NonInterference">non-interfering,
+     *                    stateless</a> function for combining two values
      * @return the result of the reduction
      * @see #sum()
      * @see #min()
@@ -405,7 +432,7 @@
      * operation</a>.
      *
      * @param <R> type of the result
-     * @param resultFactory function that creates a new result container.
+     * @param resultFactory a function that creates a new result container.
      *                      For a parallel execution, this function may be
      *                      called multiple times and must return a fresh value
      *                      each time.
@@ -485,6 +512,8 @@
      *     return mapToLong(e -> 1L).sum();
      * }</pre>
      *
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>.
+     *
      * @return the count of elements in this stream
      */
     long count();
@@ -517,8 +546,8 @@
 
     /**
      * Returns whether any elements of this stream match the provided
-     * predicate.  May not evaluate the predicate on all elements if
-     * not necessary for determining the result.
+     * predicate.  May not evaluate the predicate on all elements if not
+     * necessary for determining the result.
      *
      * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
      * terminal operation</a>.
@@ -527,7 +556,7 @@
      *                  stateless</a> predicate to apply to elements of this
      *                  stream
      * @return {@code true} if any elements of the stream match the provided
-     * predicate
+     * predicate otherwise {@code false}
      */
     boolean anyMatch(DoublePredicate predicate);
 
@@ -539,11 +568,11 @@
      * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
      * terminal operation</a>.
      *
-     * @param predicate A <a href="package-summary.html#NonInterference">non-interfering,
+     * @param predicate a <a href="package-summary.html#NonInterference">non-interfering,
      *                  stateless</a> predicate to apply to elements of this
      *                  stream
      * @return {@code true} if all elements of the stream match the provided
-     * predicate
+     * predicate otherwise {@code false}
      */
     boolean allMatch(DoublePredicate predicate);
 
@@ -559,7 +588,7 @@
      *                  stateless</a> predicate to apply to elements of this
      *                  stream
      * @return {@code true} if no elements of the stream match the provided
-     * predicate
+     * predicate otherwise {@code false}
      */
     boolean noneMatch(DoublePredicate predicate);
 
@@ -572,8 +601,8 @@
      * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
      * terminal operation</a>.
      *
-     * @return an {@code OptionalDouble} describing the first element of this ,
-     * stream or an empty {@code OptionalDouble} if the stream is empty
+     * @return an {@code OptionalDouble} describing the first element of this
+     * stream, or an empty {@code OptionalDouble} if the stream is empty
      */
     OptionalDouble findFirst();
 
--- a/src/share/classes/java/util/stream/IntStream.java	Sat Apr 20 17:25:38 2013 -0400
+++ b/src/share/classes/java/util/stream/IntStream.java	Sat Apr 20 14:25:00 2013 -0700
@@ -43,9 +43,10 @@
 
 /**
  * A sequence of primitive integer elements supporting sequential and parallel
- * bulk operations. Streams support lazy transformative operations (transforming
- * a stream to another stream) such as {@code filter} and {@code map}, and
- * consuming operations, such as {@code forEach}, {@code findFirst}, and {@code
+ * bulk operations. Streams support lazy intermediate operations (transforming
+ * a stream to another stream) such as {@code filter} and {@code map}, and terminal
+ * operations (consuming the contents of a stream to produce a result or
+ * side-effect), such as {@code forEach}, {@code findFirst}, and {@code
  * iterator}.  Once an operation has been performed on a stream, it
  * is considered <em>consumed</em> and no longer usable for other operations.
  *
@@ -57,7 +58,15 @@
  * stream operations preserve the <a href="package-summary.html#Ordering">
  * encounter order</a> of their source, and terminal operations
  * respect the encounter order of their source, if the source
- * has an encounter order.
+ * has an encounter order.  Provided that and parameters to stream operations
+ * satisfy the <a href="package-summary.html#NonInterference">non-interference
+ * requirements</a>, and excepting differences arising from the absence of
+ * a defined encounter order, the result of a stream pipeline should be the
+ * stable across multiple executions of the same operations on the same source.
+ * However, the timing and thread in which side-effects occur (for those
+ * operations which are allowed to produce side-effects, such as
+ * {@link #forEach(IntConsumer)}), are explicitly nondeterministic for parallel
+ * execution of stream pipelines.
  *
  * <p>Unless otherwise noted, passing a {@code null} argument to any stream
  * method may result in a {@link NullPointerException}.
@@ -95,8 +104,8 @@
      * operation</a>.
      *
      * @param mapper a <a href="package-summary.html#NonInterference">
-     *               non-interfering, stateless</a> function to apply to
-     *               each element
+     *               non-interfering, stateless</a> function to apply to each
+     *               element
      * @return the new stream
      */
     IntStream map(IntUnaryOperator mapper);
@@ -110,8 +119,8 @@
      *
      * @param <U> the element type of the new stream
      * @param mapper a <a href="package-summary.html#NonInterference">
-     *               non-interfering, stateless</a> function to apply to
-     *               each element
+     *               non-interfering, stateless</a> function to apply to each
+     *               element
      * @return the new stream
      */
     <U> Stream<U> mapToObj(IntFunction<? extends U> mapper);
@@ -120,12 +129,12 @@
      * Returns a {@code LongStream} consisting of the results of applying the
      * given function to the elements of this stream.
      *
-     * <p>This is an <a href="package-summary.html#StreamOps">
-     *     intermediate operation</a>.
+     * <p>This is an <a href="package-summary.html#StreamOps">intermediate
+     * operation</a>.
      *
      * @param mapper a <a href="package-summary.html#NonInterference">
-     *               non-interfering, stateless</a> function to apply to
-     *               each element
+     *               non-interfering, stateless</a> function to apply to each
+     *               element
      * @return the new stream
      */
     LongStream mapToLong(IntToLongFunction mapper);
@@ -138,8 +147,8 @@
      * operation</a>.
      *
      * @param mapper a <a href="package-summary.html#NonInterference">
-     *               non-interfering, stateless</a> function to apply to
-     *               each element
+     *               non-interfering, stateless</a> function to apply to each
+     *               element
      * @return the new stream
      */
     DoubleStream mapToDouble(IntToDoubleFunction mapper);
@@ -147,11 +156,22 @@
     /**
      * Returns a stream consisting of the results of replacing each element of
      * this stream with the contents of the stream produced by applying the
-     * provided function to each element.
+     * provided mapping function to each element.
      *
      * <p>This is an <a href="package-summary.html#StreamOps">intermediate
      * operation</a>.
      *
+     * @apiNote
+     * The {@code flatMap()} operation has the effect of applying a one-to-many
+     * tranformation to the elements of the stream, and then flattening the
+     * resulting elements into a new stream. For example, if {@code orders}
+     * is a stream of purchase orders, and each purchase order contains a
+     * collection of line items, then the following produces a stream of line
+     * items:
+     * <pre>{@code
+     *     orderStream.flatMap(order -> order.getLineItems().stream())...
+     * }</pre>
+     *
      * @param mapper a <a href="package-summary.html#NonInterference">
      *               non-interfering, stateless</a> function to apply to
      *               each element which produces an {@code IntStream} of new
@@ -222,6 +242,7 @@
      *
      * @param maxSize the number of elements the stream should be limited to
      * @return the new stream
+     * @throws IllegalArgumentException if {@code maxSize} is negative
      */
     IntStream limit(long maxSize);
 
@@ -235,6 +256,7 @@
      *
      * @param startingOffset the number of leading elements to skip
      * @return the new stream
+     * @throws IllegalArgumentException if {@code startingOffset} is negative
      */
     IntStream substream(long startingOffset);
 
@@ -242,7 +264,8 @@
      * Returns a stream consisting of the elements of this stream after
      * discarding the first {@code startingOffset} elements (or all elements
      * if the stream has fewer than {@code startingOffset} elements), and
-     * truncating the remainder to be no longer than {@code maxSize} in length.
+     * truncating the remainder to be no longer than
+     * {@code endingOffset - startOffset} in length.
      *
      * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
      * stateful intermediate operation</a>.
@@ -250,6 +273,9 @@
      * @param startingOffset the starting position of the substream, inclusive
      * @param endingOffset the ending position of the substream, exclusive
      * @return the new stream
+     * @throws IllegalArgumentException if {@code startingOffset} or
+     * {@code endingOffset} is negative or {@code startingOffset} is greater
+     * than {@code endingOffset}
      */
     IntStream substream(long startingOffset, long endingOffset);
 
@@ -272,7 +298,7 @@
     void forEach(IntConsumer action);
 
     /**
-     * Performs an operation for each element of this stream, guaranteeing that
+     * Performs an action for each element of this stream, guaranteeing that
      * each element is processed in encounter order for streams that have a
      * defined encounter order.
      *
@@ -280,7 +306,7 @@
      * operation</a>.
      *
      * @param action a <a href="package-summary.html#NonInterference">
-     *                 non-interfering</a> action to perform on the elements
+     *               non-interfering</a> action to perform on the elements
      * @see #forEach(IntConsumer)
      */
     void forEachOrdered(IntConsumer action);
@@ -297,8 +323,8 @@
 
     /**
      * Performs a <a href="package-summary.html#Reduction">reduction</a> on the
-     * elements of this stream, using the provided identity value and
-     * an <a href="package-summary.html#Associativity">associative</a>
+     * elements of this stream, using the provided identity value and an
+     * <a href="package-summary.html#Associativity">associative</a>
      * accumulation function, and returns the reduced value.  This is equivalent
      * to:
      * <pre>{@code
@@ -337,7 +363,7 @@
      * operations parallelize more gracefully, without needing additional
      * synchronization and with greatly reduced risk of data races.
      *
-     * @param identity The identity value for the accumulating function
+     * @param identity the identity value for the accumulating function
      * @param op an <a href="package-summary.html#Associativity">associative</a>
      *                    <a href="package-summary.html#NonInterference">non-interfering,
      *                    stateless</a> function for combining two values
@@ -378,8 +404,8 @@
      * operation</a>.
      *
      * @param op an <a href="package-summary.html#Associativity">associative</a>
-     *              <a href="package-summary.html#NonInterference">non-interfering,
-     *              stateless</a> function for combining two values
+     *           <a href="package-summary.html#NonInterference">non-interfering,
+     *           stateless</a> function for combining two values
      * @return the result of the reduction
      * @see #reduce(int, IntBinaryOperator)
      */
@@ -399,14 +425,14 @@
      *     return result;
      * }</pre>
      *
-     * Like {@link #reduce(int, IntBinaryOperator)}, {@code collect} operations
-     * can be parallelized without requiring additional sychronization.
+     * <p>Like {@link #reduce(int, IntBinaryOperator)}, {@code collect} operations
+     * can be parallelized without requiring additional synchronization.
      *
      * <p>This is a <a href="package-summary.html#StreamOps">terminal
      * operation</a>.
      *
      * @param <R> type of the result
-     * @param resultFactory function that creates a new result container.
+     * @param resultFactory a function that creates a new result container.
      *                      For a parallel execution, this function may be
      *                      called multiple times and must return a fresh value
      *                      each time.
@@ -433,7 +459,7 @@
      *     return reduce(0, Integer::sum);
      * }</pre>
      *
-     * @return The sum of elements in this stream
+     * @return the sum of elements in this stream
      */
     int sum();
 
@@ -446,9 +472,11 @@
      *     return reduce(Integer::min);
      * }</pre>
      *
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>.
+     *
+
      * @return an {@code OptionalInt} containing the minimum element of this
-     * stream, or an empty optional if the stream is empty
-     *
+     * stream, or an empty {@code OptionalInt} if the stream is empty
      */
     OptionalInt min();
 
@@ -461,8 +489,11 @@
      *     return reduce(Integer::max);
      * }</pre>
      *
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal
+     * operation</a>.
+     *
      * @return an {@code OptionalInt} containing the maximum element of this
-     * stream, or an empty optional if the stream is empty
+     * stream, or an empty {@code OptionalInt} if the stream is empty
      */
     OptionalInt max();
 
@@ -474,6 +505,8 @@
      *     return mapToLong(e -> 1L).sum();
      * }</pre>
      *
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>.
+     *
      * @return the count of elements in this stream
      */
     long count();
@@ -501,8 +534,8 @@
 
     /**
      * Returns whether any elements of this stream match the provided
-     * predicate.  May not evaluate the predicate on all elements if
-     * not necessary for determining the result.
+     * predicate.  May not evaluate the predicate on all elements if not
+     * necessary for determining the result.
      *
      * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
      * terminal operation</a>.
@@ -523,11 +556,11 @@
      * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
      * terminal operation</a>.
      *
-     * @param predicate A <a href="package-summary.html#NonInterference">non-interfering,
+     * @param predicate a <a href="package-summary.html#NonInterference">non-interfering,
      *                  stateless</a> predicate to apply to elements of this
      *                  stream
      * @return {@code true} if all elements of the stream match the provided
-     * predicate {@code false}
+     * predicate otherwise {@code false}
      */
     boolean allMatch(IntPredicate predicate);
 
@@ -600,7 +633,7 @@
 
     /**
      * Returns a {@code Stream} consisting of the elements of this stream,
-     * boxed to {@code Integer}.
+     * each boxed to an {@code Integer}.
      *
      * @return a {@code Stream} consistent of the elements of this stream,
      * each boxed to an {@code Integer}
--- a/src/share/classes/java/util/stream/LongStream.java	Sat Apr 20 17:25:38 2013 -0400
+++ b/src/share/classes/java/util/stream/LongStream.java	Sat Apr 20 14:25:00 2013 -0700
@@ -43,9 +43,10 @@
 
 /**
  * A sequence of primitive long elements supporting sequential and parallel
- * bulk operations. Streams support lazy transformative operations (transforming
- * a stream to another stream) such as {@code filter} and {@code map}, and
- * consuming operations, such as {@code forEach}, {@code findFirst}, and {@code
+ * bulk operations. Streams support lazy intermediate operations (transforming
+ * a stream to another stream) such as {@code filter} and {@code map}, and terminal
+ * operations (consuming the contents of a stream to produce a result or
+ * side-effect), such as {@code forEach}, {@code findFirst}, and {@code
  * iterator}.  Once an operation has been performed on a stream, it
  * is considered <em>consumed</em> and no longer usable for other operations.
  *
@@ -57,7 +58,15 @@
  * stream operations preserve the <a href="package-summary.html#Ordering">
  * encounter order</a> of their source, and terminal operations
  * respect the encounter order of their source, if the source
- * has an encounter order.
+ * has an encounter order.  Provided that and parameters to stream operations
+ * satisfy the <a href="package-summary.html#NonInterference">non-interference
+ * requirements</a>, and excepting differences arising from the absence of
+ * a defined encounter order, the result of a stream pipeline should be the
+ * stable across multiple executions of the same operations on the same source.
+ * However, the timing and thread in which side-effects occur (for those
+ * operations which are allowed to produce side-effects, such as
+ * {@link #forEach(LongConsumer)}), are explicitly nondeterministic for parallel
+ * execution of stream pipelines.
  *
  * <p>Unless otherwise noted, passing a {@code null} argument to any stream
  * method may result in a {@link NullPointerException}.
@@ -95,8 +104,8 @@
      * operation</a>.
      *
      * @param mapper a <a href="package-summary.html#NonInterference">
-     *               non-interfering, stateless</a> function to apply to
-     *               each element
+     *               non-interfering, stateless</a> function to apply to each
+     *               element
      * @return the new stream
      */
     LongStream map(LongUnaryOperator mapper);
@@ -110,51 +119,62 @@
      *
      * @param <U> the element type of the new stream
      * @param mapper a <a href="package-summary.html#NonInterference">
-     *               non-interfering, stateless</a> function to apply to
-     *               each element
+     *               non-interfering, stateless</a> function to apply to each
+     *               element
      * @return the new stream
      */
     <U> Stream<U> mapToObj(LongFunction<? extends U> mapper);
 
     /**
-     * Produces an {@code IntStream} consisting of the results of applying
-     * the given function to the elements of this stream.
+     * Returns an {@code IntStream} consisting of the results of applying the
+     * given function to the elements of this stream.
      *
-     * <p>This is an <a href="package-summary.html#StreamOps">
-     *     intermediate operation</a>.
+     * <p>This is an <a href="package-summary.html#StreamOps">intermediate
+     * operation</a>.
      *
      * @param mapper a <a href="package-summary.html#NonInterference">
-     *               non-interfering, stateless</a> function to apply to
-     *               each element
+     *               non-interfering, stateless</a> function to apply to each
+     *               element
      * @return the new stream
      */
     IntStream mapToInt(LongToIntFunction mapper);
 
     /**
-     * Returns a {@code DoubleStream} consisting of the results of applying
-     * the given function to the elements of this stream.
+     * Returns a {@code DoubleStream} consisting of the results of applying the
+     * given function to the elements of this stream.
      *
-     * <p>This is an <a href="package-summary.html#StreamOps">
-     *     intermediate operation</a>.
+     * <p>This is an <a href="package-summary.html#StreamOps">intermediate
+     * operation</a>.
      *
      * @param mapper a <a href="package-summary.html#NonInterference">
-     *               non-interfering, stateless</a> function to apply to
-     *               each element
+     *               non-interfering, stateless</a> function to apply to each
+     *               element
      * @return the new stream
      */
     DoubleStream mapToDouble(LongToDoubleFunction mapper);
 
     /**
-     * Returns a stream consisting of the results of replacing each
-     * element of this stream with the contents of the stream
-     * produced by applying the provided function to each element.
+     * Returns a stream consisting of the results of replacing each element of
+     * this stream with the contents of the stream produced by applying the
+     * provided mapping function to each element.
      *
      * <p>This is an <a href="package-summary.html#StreamOps">intermediate
      * operation</a>.
      *
+     * @apiNote
+     * The {@code flatMap()} operation has the effect of applying a one-to-many
+     * tranformation to the elements of the stream, and then flattening the
+     * resulting elements into a new stream. For example, if {@code orders}
+     * is a stream of purchase orders, and each purchase order contains a
+     * collection of line items, then the following produces a stream of line
+     * items:
+     * <pre>{@code
+     *     orderStream.flatMap(order -> order.getLineItems().stream())...
+     * }</pre>
+     *
      * @param mapper a <a href="package-summary.html#NonInterference">
      *               non-interfering, stateless</a> function to apply to
-     *               each element which produces an stream of new
+     *               each element which produces an {@code LongStream} of new
      *               values
      * @return the new stream
      * @see Stream#flatMap(Function)
@@ -222,6 +242,7 @@
      *
      * @param maxSize the number of elements the stream should be limited to
      * @return the new stream
+     * @throws IllegalArgumentException if {@code maxSize} is negative
      */
     LongStream limit(long maxSize);
 
@@ -235,6 +256,7 @@
      *
      * @param startingOffset the number of leading elements to skip
      * @return the new stream
+     * @throws IllegalArgumentException if {@code startingOffset} is negative
      */
     LongStream substream(long startingOffset);
 
@@ -250,6 +272,9 @@
      * @param startingOffset the starting position of the substream, inclusive
      * @param endingOffset the ending position of the substream, exclusive
      * @return the new stream
+     * @throws IllegalArgumentException if {@code startingOffset} or
+     * {@code endingOffset} is negative or {@code startingOffset} is greater
+     * than {@code endingOffset}
      */
     LongStream substream(long startingOffset, long endingOffset);
 
@@ -297,8 +322,8 @@
 
     /**
      * Performs a <a href="package-summary.html#Reduction">reduction</a> on the
-     * elements of this stream, using the provided identity value and
-     * an <a href="package-summary.html#Associativity">associative</a>
+     * elements of this stream, using the provided identity value and an
+     * <a href="package-summary.html#Associativity">associative</a>
      * accumulation function, and returns the reduced value.  This is equivalent
      * to:
      * <pre>{@code
@@ -378,8 +403,8 @@
      * operation</a>.
      *
      * @param op an <a href="package-summary.html#Associativity">associative</a>
-     *              <a href="package-summary.html#NonInterference">non-interfering,
-     *              stateless</a> function for combining two values
+     *           <a href="package-summary.html#NonInterference">non-interfering,
+     *           stateless</a> function for combining two values
      * @return the result of the reduction
      * @see #reduce(long, LongBinaryOperator)
      */
@@ -399,17 +424,17 @@
      *     return result;
      * }</pre>
      *
-     * Like {@link #reduce(long, LongBinaryOperator)}, {@code collect} operations
-     * can be parallelized without requiring additional sychronization.
+     * <p>Like {@link #reduce(long, LongBinaryOperator)}, {@code collect} operations
+     * can be parallelized without requiring additional synchronization.
      *
      * <p>This is a <a href="package-summary.html#StreamOps">terminal
      * operation</a>.
      *
      * @param <R> type of the result
-     * @param resultFactory function that creates a new result container.  For
-     *                      a parallel execution, this function may be called
-     *                      multiple times and must return a fresh value each
-     *                      time.
+     * @param resultFactory a function that creates a new result container.
+     *                      For a parallel execution, this function may be
+     *                      called multiple times and must return a fresh value
+     *                      each time.
      * @param accumulator an <a href="package-summary.html#Associativity">associative</a>
      *                    <a href="package-summary.html#NonInterference">non-interfering,
      *                    stateless</a> function for incorporating an additional
@@ -446,8 +471,11 @@
      *     return reduce(Long::min);
      * }</pre>
      *
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>.
+     *
+
      * @return an {@code OptionalLong} containing the minimum element of this
-     * stream, or an empty optional if the stream is empty
+     * stream, or an empty {@code OptionalLong} if the stream is empty
      */
     OptionalLong min();
 
@@ -460,8 +488,11 @@
      *     return reduce(Long::max);
      * }</pre>
      *
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal
+     * operation</a>.
+     *
      * @return an {@code OptionalLong} containing the maximum element of this
-     * stream, or an empty optional if the stream is empty
+     * stream, or an empty {@code OptionalLong} if the stream is empty
      */
     OptionalLong max();
 
@@ -470,10 +501,12 @@
      * a <a href="package-summary.html#MutableReduction">reduction</a> and is
      * equivalent to:
      * <pre>{@code
-     *     return map(e -> 1).sum();
+     *     return map(e -> 1L).sum();
      * }</pre>
      *
-     * @return The count of elements in this stream
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>.
+     *
+     * @return the count of elements in this stream
      */
     long count();
 
@@ -499,9 +532,9 @@
     LongSummaryStatistics summaryStatistics();
 
     /**
-     * Returns whether any elements of this stream match the provided predicate.
-     * May not evaluate the predicate on all elements if not necessary for
-     * determining the result.
+     * Returns whether any elements of this stream match the provided
+     * predicate.  May not evaluate the predicate on all elements if not
+     * necessary for determining the result.
      *
      * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
      * terminal operation</a>.
@@ -526,7 +559,7 @@
      *                  stateless</a> predicate to apply to elements of this
      *                  stream
      * @return {@code true} if all elements of the stream match the provided
-     * predicate {@code false}
+     * predicate otherwise {@code false}
      */
     boolean allMatch(LongPredicate predicate);
 
@@ -583,7 +616,7 @@
      * Returns a {@code DoubleStream} consisting of the elements of this stream,
      * converted to {@code double}.
      *
-     * @return A {@code DoubleStream} consisting of the elements of this stream,
+     * @return a {@code DoubleStream} consisting of the elements of this stream,
      * converted to {@code double}
      */
     DoubleStream doubles();
@@ -592,8 +625,8 @@
      * Returns a {@code Stream} consisting of the elements of this stream,
      * each boxed to a {@code Long}.
      *
-     * @return A {@code Stream} consistent of the elements of this stream,
-     * boxed to {@code Long}
+     * @return a {@code Stream} consistent of the elements of this stream,
+     * each boxed to {@code Long}
      */
     Stream<Long> boxed();
 
--- a/src/share/classes/java/util/stream/Stream.java	Sat Apr 20 17:25:38 2013 -0400
+++ b/src/share/classes/java/util/stream/Stream.java	Sat Apr 20 14:25:00 2013 -0700
@@ -89,8 +89,8 @@
 public interface Stream<T> extends BaseStream<T, Stream<T>> {
 
     /**
-     * Returns a stream consisting of the elements of this stream that match the
-     * given predicate.
+     * Returns a stream consisting of the elements of this stream that match 
+     * the given predicate.
      *
      * <p>This is an <a href="package-summary.html#StreamOps">intermediate
      * operation</a>.
@@ -146,8 +146,8 @@
     LongStream mapToLong(ToLongFunction<? super T> mapper);
 
     /**
-     * Returns a {@code DoubleStream} consisting of the results of applying
-     * the given function to the elements of this stream.
+     * Returns a {@code DoubleStream} consisting of the results of applying the
+     * given function to the elements of this stream.
      *
      * <p>This is an <a href="package-summary.html#StreamOps">intermediate
      * operation</a>.
@@ -269,6 +269,7 @@
      *
      * <p>This is a <a href="package-summary.html#StreamOps">stateful
      * intermediate operation</a>.
+     *
      * @param comparator a <a href="package-summary.html#NonInterference">
      *                   non-interfering, stateless</a> {@code Comparator} to
      *                   be used to compare stream elements
@@ -300,7 +301,7 @@
      *         .collect(Collectors.intoList());
      * }</pre>
      *
-     * @param consumer A <a href="package-summary.html#NonInterference">
+     * @param consumer a <a href="package-summary.html#NonInterference">
      *                 non-interfering</a> action to perform on the elements as
      *                 they are consumed from the stream
      * @return the new stream
@@ -316,6 +317,7 @@
      *
      * @param maxSize the number of elements the stream should be limited to
      * @return the new stream
+     * @throws IllegalArgumentException if {@code maxSize} is negative
      */
     Stream<T> limit(long maxSize);
 
@@ -329,6 +331,7 @@
      *
      * @param startingOffset the number of leading elements to skip
      * @return the new stream
+     * @throws IllegalArgumentException if {@code startingOffset} is negative
      */
     Stream<T> substream(long startingOffset);
 
@@ -336,7 +339,8 @@
      * Returns a stream consisting of the elements of this stream after
      * discarding the first {@code startingOffset} elements (or all elements
      * if the stream has fewer than {@code startingOffset} elements), and
-     * truncating the remainder to be no longer than {@code maxSize} in length.
+     * truncating the remainder to be no longer than
+     * {@code endingOffset - startOffset} in length.
      *
      * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
      * stateful intermediate operation</a>.
@@ -344,6 +348,9 @@
      * @param startingOffset the starting position of the substream, inclusive
      * @param endingOffset the ending position of the substream, exclusive
      * @return the new stream
+     * @throws IllegalArgumentException if {@code startingOffset} or
+     * {@code endingOffset} is negative or {@code startingOffset} is greater
+     * than {@code endingOffset}
      */
     Stream<T> substream(long startingOffset, long endingOffset);
 
@@ -489,6 +496,8 @@
      *                    stateless</a> function for combining two values
      * @return the result of the reduction
      * @see #reduce(Object, BinaryOperator)
+     * @see #min()
+     * @see #max()
      */
     Optional<T> reduce(BinaryOperator<T> accumulator);
 
@@ -643,6 +652,21 @@
     <R> R collect(Collector<? super T, R> collector);
 
     /**
+     * Returns the minimum element of this stream according to the provided
+     * {@code Comparator}.  This is a special case of a
+     * <a href="package-summary.html#MutableReduction">reduction</a>.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>.
+     *
+     * @param comparator a <a href="package-summary.html#NonInterference">non-interfering,
+     *                   stateless</a> {@code Comparator} to use to compare
+     *                   elements of this stream
+     * @return an {@code Optional} describing the minimum element of this stream,
+     * or an empty {@code Optional} if the stream is empty
+     */
+    Optional<T> min(Comparator<? super T> comparator);
+
+    /**
      * Returns the maximum element of this stream according to the provided
      * {@code Comparator}.  This is a special case of a
      * <a href="package-summary.html#MutableReduction">reduction</a>.
@@ -659,27 +683,16 @@
     Optional<T> max(Comparator<? super T> comparator);
 
     /**
-     * Returns the minimum element of this stream according to the provided
-     * {@code Comparator}.  This is a special case of a
-     * <a href="package-summary.html#MutableReduction">reduction</a>.
+     * Returns the count of elements in this stream.  This is a special case of
+     * a <a href="package-summary.html#MutableReduction">reduction</a> and is
+     * equivalent to:
+     * <pre>{@code
+     *     return mapToLong(e -> 1L).sum();
+     * }</pre>
      *
      * <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>.
      *
-     * @param comparator a <a href="package-summary.html#NonInterference">non-interfering,
-     *                   stateless</a> {@code Comparator} to use to compare
-     *                   elements of this stream
-     * @return an {@code Optional} describing the minimum element of this stream,
-     * or an empty {@code Optional} if the stream is empty
-     */
-    Optional<T> min(Comparator<? super T> comparator);
-
-    /**
-     * Returns the count of elements in this stream.  This is a special case of a
-     * <a href="package-summary.html#MutableReduction">reduction</a>.
-     *
-     * <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>.
-     *
-     * @return the count of elements in this stream.
+     * @return the count of elements in this stream
      */
     long count();
 
@@ -700,32 +713,34 @@
     boolean anyMatch(Predicate<? super T> predicate);
 
     /**
-     * Returns whether all elements of this stream match the provided
-     * predicate.  May not evaluate the predicate on all elements if
-     * not necessary for determining the result.
+     * Returns whether all elements of this stream match the provided predicate.
+     * May not evaluate the predicate on all elements if not necessary for
+     * determining the result.
      *
      * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
      * terminal operation</a>.
      *
-     * @param predicate A <a href="package-summary.html#NonInterference">non-interfering,
-     *                  stateless</a> predicate to apply to elements of this stream
+     * @param predicate a <a href="package-summary.html#NonInterference">non-interfering,
+     *                  stateless</a> predicate to apply to elements of this
+     *                  stream
      * @return {@code true} if all elements of the stream match the provided
      * predicate otherwise {@code false}
      */
     boolean allMatch(Predicate<? super T> predicate);
 
     /**
-     * Returns whether no elements of this stream match the provided
-     * predicate.  May not evaluate the predicate on all elements if
-     * not necessary for determining the result.
+     * Returns whether no elements of this stream match the provided predicate.
+     * May not evaluate the predicate on all elements if not necessary for
+     * determining the result.
      *
      * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
      * terminal operation</a>.
      *
      * @param predicate a <a href="package-summary.html#NonInterference">non-interfering,
-     *                  stateless</a> predicate to apply to elements of this stream
+     *                  stateless</a> predicate to apply to elements of this
+     *                  stream
      * @return {@code true} if no elements of the stream match the provided
-     * predicate {@code false}
+     * predicate otherwise {@code false}
      */
     boolean noneMatch(Predicate<? super T> predicate);
 
@@ -738,7 +753,7 @@
      * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
      * terminal operation</a>.
      *
-     * @return An {@code Optional} describing the first element of this stream,
+     * @return an {@code Optional} describing the first element of this stream,
      * or an empty {@code Optional} if the stream is empty
      * @throws NullPointerException if the element selected is null
      */