jdk/src/share/classes/java/util/Collection.java
changeset 17182 b786c0de868c
parent 17166 c83a0fa44906
child 18822 4b6be7c19547
--- a/jdk/src/share/classes/java/util/Collection.java	Tue Apr 02 18:41:04 2013 -0400
+++ b/jdk/src/share/classes/java/util/Collection.java	Wed Apr 24 16:15:47 2013 -0700
@@ -26,6 +26,8 @@
 package java.util;
 
 import java.util.function.Predicate;
+import java.util.stream.Stream;
+import java.util.stream.StreamSupport;
 
 /**
  * The root interface in the <i>collection hierarchy</i>.  A collection
@@ -499,9 +501,28 @@
     /**
      * 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 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><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 = StreamSupport.stream(() -> spliterator(), spliteratorCharacteristics)
+     * }</pre>
+     * <p>These requirements ensure that streams produced by the
+     * {@link #stream()} 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
@@ -510,7 +531,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
@@ -519,4 +540,44 @@
     default Spliterator<E> spliterator() {
         return Spliterators.spliterator(this, 0);
     }
+
+    /**
+     * 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},
+     * {@code CONCURRENT}, or <em>late-binding</em>. (See {@link #spliterator()}
+     * for details.)
+     *
+     * @implSpec
+     * The default implementation creates a sequential {@code Stream} from the
+     * collection's {@code Spliterator}.
+     *
+     * @return a sequential {@code Stream} over the elements in this collection
+     * @since 1.8
+     */
+    default Stream<E> stream() {
+        return StreamSupport.stream(spliterator());
+    }
+
+    /**
+     * 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},
+     * {@code CONCURRENT}, or <em>late-binding</em>. (See {@link #spliterator()}
+     * for details.)
+     *
+     * @implSpec
+     * The default implementation creates a parallel {@code Stream} from the
+     * collection's {@code Spliterator}.
+     *
+     * @return a possibly parallel {@code Stream} over the elements in this
+     * collection
+     * @since 1.8
+     */
+    default Stream<E> parallelStream() {
+        return StreamSupport.parallelStream(spliterator());
+    }
 }