Spec update for Streams

[Brian Goetz]

Below are some spec updates to Stream.sort, Stream.distinct, and 
Stream.collect which capture some guarantees about ordering that we 
discussed but which were never incorporated into the spec.  Notably:

  - Sorting is stable iff the stream is ordered
  - Duplicate removal is stable iff the stream is ordered (i.e., if 
there are duplicates, a stable implementation would preserve the first one)
  - If a stream is parallel and a Collector is concurrent and either the 
stream or the collector is unordered, then a concurrent reduction is 
performed by stream.collect(Collector).

Corresponding spec follows, please review.


diff --git a/src/share/classes/java/util/stream/Stream.java 
b/src/share/classes/java/util/stream/Stream.java
--- a/src/share/classes/java/util/stream/Stream.java
+++ b/src/share/classes/java/util/stream/Stream.java
@@ -293,6 +293,11 @@
       * Returns a stream consisting of the distinct elements (according to
       * {@link Object#equals(Object)}) of this stream.
       *
+     * <p>For ordered streams, the selection of distinct elements is stable
+     * (for duplicated elements, the element appearing first in the 
encounter
+     * order is preserved.)  For unordered streams, no stability guarantees
+     * are made.
+     *
       * <p>This is a <a href="package-summary.html#StreamOps">stateful
       * intermediate operation</a>.
       *
@@ -306,6 +311,9 @@
       * {@code Comparable}, a {@code java.lang.ClassCastException} may 
be thrown
       * when the terminal operation is executed.
       *
+     * <p>For ordered streams, the sort is stable.  For unordered 
streams, no
+     * stability guarantees are made.
+     *
       * <p>This is a <a href="package-summary.html#StreamOps">stateful
       * intermediate operation</a>.
       *
@@ -317,6 +325,9 @@
       * Returns a stream consisting of the elements of this stream, sorted
       * according to the provided {@code Comparator}.
       *
+     * <p>For ordered streams, the sort is stable.  For unordered 
streams, no
+     * stability guarantees are made.
+     *
       * <p>This is a <a href="package-summary.html#StreamOps">stateful
       * intermediate operation</a>.
       *
@@ -678,6 +689,13 @@
       * collection strategies and composition of collect operations such as
       * multiple-level grouping or partitioning.
       *
+     * <p>If the stream is parallel, and the {@code Collector}
+     * is {@link Collector.Characteristics.CONCURRENT concurrent}, and
+     * either the stream is unordered or the collector is
+     * {@link Collector.Characteristics.UNORDERED unordered},
+     * then a concurrent reduction will be performed (see {@link 
Collector} for
+     * details on concurrent reduction.)
+     *
       * <p>This is a <a href="package-summary.html#StreamOps">terminal
       * operation</a>.
       *