changeset 8250:3ec06ef568a8

Spec updates for Collection as part of JDK-8012542
author briangoetz
date Thu, 18 Apr 2013 15:47:35 -0400
parents e07385a7e27a
children 493c45493934
files src/share/classes/java/util/Collection.java
diffstat 1 files changed, 22 insertions(+), 20 deletions(-) [+]
line wrap: on
line diff
--- a/src/share/classes/java/util/Collection.java	Thu Apr 18 15:09:57 2013 -0400
+++ b/src/share/classes/java/util/Collection.java	Thu Apr 18 15:47:35 2013 -0400
@@ -499,26 +499,27 @@
     /**
      * Creates a {@link Spliterator} over the elements in this collection.
      *
-     * <p>The {@code Spliterator} reports {@link Spliterator#SIZED}.
-     * Implementations should document the reporting of additional
-     * characteristic values.
+     * <p>The returned {@code Spliterator} must report the characteristic
+     * {@link Spliterator#SIZED}; implementations should document any additional
+     * characteristic values reported by the returned Spliterator.
      *
-     * <p>The default implementation should be overridden by implementing
-     * Collections that can return a more efficient spliterator.  In order to
+     * <p>The default implementation should be overridden by subclasses that
+     * can return a more efficient spliterator.  In order to
      * preserve expected laziness behavior for the {@link #stream()} and
      * {@link #parallelStream()}} methods, spliterators should either have the
      * characteristic of {@code IMMUTABLE} or {@code CONCURRENT}, or be
-     * <em>late-binding</em>.   If none of these is practical, the overriding
-     * class should describe the spliterator's documented policy of binding and
-     * structural interference, and should override the {@link #stream()} and
-     * {@link #parallelStream()} methods to create streams using a
-     * {@code Supplier} of the spliterator, as in:
-     * <pre>
-     *     Stream&lt;E> s = Streams.stream(() -> spliterator(), spliteratorCharacteristics)
-     * </pre>
+     * <em><a href="Spliterator.html#binding">late-binding</a></em>.
+     * If none of these is practical, the overriding class should describe the
+     * spliterator's documented policy of binding and structural interference,
+     * and should override the {@link #stream()} and {@link #parallelStream()}
+     * methods to create streams using a {@code Supplier} of the spliterator,
+     * as in:
+     * <pre>{@code
+     *     Stream<E> s = Streams.stream(() -> spliterator(), spliteratorCharacteristics)
+     * }</pre>
      * These requirements ensure that streams produced by the {@link #stream()}
-     * and {@link #parallelStream()} methods will reflect the concepts of the
-     * collection as of the beginning of the terminal stream operation.
+     * and {@link #parallelStream()} methods will reflect the contents of the
+     * collection as of initiation of the terminal stream operation.
      *
      * @implSpec
      * The default implementation creates a
@@ -527,7 +528,7 @@
      * <em>fail-fast</em> properties of the collection's iterator.
      *
      * @implNote
-     * The created {@code Spliterator} additionally reports
+     * The returned {@code Spliterator} additionally reports
      * {@link Spliterator#SUBSIZED}.
      *
      * @return a {@code Spliterator} over the elements in this collection
@@ -538,7 +539,7 @@
     }
 
     /**
-     * Creates a sequential {@code Stream} with this collection as its source.
+     * Returns a sequential {@code Stream} with this collection as its source.
      *
      * <p>This method should be overridden when the {@link #spliterator()}
      * method cannot return a spliterator that is {@code IMMUTABLE},
@@ -557,8 +558,8 @@
     }
 
     /**
-     * Creates a parallel {@code Stream} with this collection as its source.
-     * It is allowable for this method to return a sequential stream.
+     * Returns a possibly parallel {@code Stream} with this collection as its
+     * source.  It is allowable for this method to return a sequential stream.
      *
      * <p>This method should be overridden when the {@link #spliterator()}
      * method cannot return a spliterator that is {@code IMMUTABLE},
@@ -569,7 +570,8 @@
      * The default implementation creates a parallel {@code Stream} from the
      * collection's {@code Spliterator}.
      *
-     * @return a parallel {@code Stream} over the elements in this collection
+     * @return a possibly parallel {@code Stream} over the elements in this
+     * collection
      * @since 1.8
      */
     default Stream<E> parallelStream() {