OpenJDK / lambda / lambda / jdk

changeset 8088:5e7f8797b9c1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Spec pass on StreamBuilder
author briangoetz
date Thu, 11 Apr 2013 15:53:17 -0400
parents a3a9bb95a904
children 7d9995af08e1
files src/share/classes/java/util/stream/StreamBuilder.java src/share/classes/java/util/stream/Streams.java
diffstat 2 files changed, 53 insertions(+), 34 deletions(-) [+]
line wrap: on
line diff
--- a/src/share/classes/java/util/stream/StreamBuilder.java	Thu Apr 11 11:45:05 2013 -0400
+++ b/src/share/classes/java/util/stream/StreamBuilder.java	Thu Apr 11 15:53:17 2013 -0400
@@ -30,19 +30,23 @@
 import java.util.function.LongConsumer;
 
 /**
- * A builder of {@code Stream}.
+ * A mutable builder for a {@code Stream}.  This allows the creation of streams
+ * a {@code Stream} by generating elements individually and adding them to the
+ * {@code StreamBuilder}, and to do so more efficiently than using an
+ * {@code ArrayList} or other collection as a temporary buffer.
  *
- * <p>A stream is built from elements added to a builder.  The elements will be
- * encountered in the order they are added.
- *
- * <p>A builder can build only one stream.  An {@code IllegalStateException} is
- * thrown if the builder is operated on after it has built a stream.
+ * <p>A {@code StreamBuilder} has a lifecycle, where it starts in a building
+ * phase, during which elements can be added, and then transitions to a built
+ * phase, after which elements may not be added.  The built phase begins
+ * when the {@link #build()}} method is called, which creates an ordered
+ * {@code Stream} whose elements are the elements that were added to the stream
+ * builder, in the order they were added.
  *
  * <p>Primitive specializations of {@code StreamBuilder} are provided
  * for {@link OfInt int}, {@link OfLong long}, and {@link OfDouble double}
  * values.
  *
- * @param <T> Type of elements.
+ * @param <T> The type of stream elements
  * @see java.util.stream.Streams#builder()
  * @since 1.8
  */
@@ -50,15 +54,16 @@
 
     /**
      * {@inheritDoc}
-     * Adds an element to be encountered in the built stream.
+     * Adds an element to the stream being built.
      *
-     * @throws IllegalStateException if the builder has built a stream
+     * @throws IllegalStateException if the builder has already transitioned to
+     * the built state
      */
     @Override
     void accept(T t);
 
     /**
-     * Adds an element to be encountered in the built stream.
+     * Adds an element to the stream being built.
      *
      * @implSpec
      * The default implementation behaves as if:
@@ -69,7 +74,8 @@
      *
      * @param t the element to add
      * @return {@code this} builder
-     * @throws IllegalStateException if the builder has built a stream
+     * @throws IllegalStateException if the builder has already transitioned to
+     * the built state
      */
     default StreamBuilder<T> add(T t) {
         accept(t);
@@ -77,26 +83,29 @@
     }
 
     /**
-     * Builds the stream.  An {@code IllegalStateException} is thrown if the
-     * builder is operated on after it has built a stream.
+     * Builds the stream, transitioning this builder to the built state.
+     * An {@code IllegalStateException} is thrown if there are further attempts
+     * to operate on the builder after it has entered the built state.
      *
      * @return the built stream
-     * @throws IllegalStateException if the builder has built a stream
+     * @throws IllegalStateException if the builder has already transitioned to
+     * the built state
      */
     Stream<T> build();
 
     /**
-     * A builder specialized for {@code int} values.
+     * A mutable builder for an {@code IntStream}.
      *
      * @since 1.8
      */
-    interface OfInt extends IntConsumer  {
+    interface OfInt extends IntConsumer {
 
         /**
          * {@inheritDoc}
          * Adds an element to be encountered in the built stream.
          *
-         * @throws IllegalStateException if the builder has built a stream
+         * @throws IllegalStateException if the builder has already transitioned
+         * to the built state
          */
         @Override
         void accept(int t);
@@ -113,7 +122,8 @@
          *
          * @param t the element to add
          * @return {@code this} builder
-         * @throws IllegalStateException if the builder has built a stream
+         * @throws IllegalStateException if the builder has already transitioned
+         * to the built state
          */
         default StreamBuilder.OfInt add(int t) {
             accept(t);
@@ -121,17 +131,19 @@
         }
 
         /**
-         * Builds the stream.  An {@code IllegalStateException} is thrown if the
-         * builder is operated on after it has built a stream.
+         * Builds the stream, transitioning this builder to the built state.
+         * An {@code IllegalStateException} is thrown if there are further attempts
+         * to operate on the builder after it has entered the built state.
          *
          * @return the built stream
-         * @throws IllegalStateException if the builder has built a stream
+         * @throws IllegalStateException if the builder has already transitioned
+         * to the built state
          */
         IntStream build();
     }
 
     /**
-     * A builder specialized for {@code long} values.
+     * A mutable builder for a {@code LongStream}.
      *
      * @since 1.8
      */
@@ -158,7 +170,8 @@
          *
          * @param t the element to add
          * @return {@code this} builder
-         * @throws IllegalStateException if the builder has built a stream
+         * @throws IllegalStateException if the builder has already transitioned
+         * to the built state
          */
         default StreamBuilder.OfLong add(long t) {
             accept(t);
@@ -166,17 +179,19 @@
         }
 
         /**
-         * Builds the stream.  An {@code IllegalStateException} is thrown if the
-         * builder is operated on after it has built a stream.
+         * Builds the stream, transitioning this builder to the built state.
+         * An {@code IllegalStateException} is thrown if there are further attempts
+         * to operate on the builder after it has entered the built state.
          *
          * @return the built stream
-         * @throws IllegalStateException if the builder has built a stream
+         * @throws IllegalStateException if the builder has already transitioned
+         * to the built state
          */
         LongStream build();
     }
 
     /**
-     * A builder specialized for {@code double} values.
+     * A mutable builder for a {@code DoubleStream}.
      *
      * @since 1.8
      */
@@ -186,7 +201,8 @@
          * {@inheritDoc}
          * Adds an element to be encountered in the built stream.
          *
-         * @throws IllegalStateException if the builder has built a stream
+         * @throws IllegalStateException if the builder has already transitioned
+         * to the built state
          */
         @Override
         void accept(double t);
@@ -203,7 +219,8 @@
          *
          * @param t the element to add
          * @return {@code this} builder
-         * @throws IllegalStateException if the builder has built a stream
+         * @throws IllegalStateException if the builder has already transitioned
+         * to the built state
          */
         default StreamBuilder.OfDouble add(double t) {
             accept(t);
@@ -211,11 +228,13 @@
         }
 
         /**
-         * Builds the stream.  An {@code IllegalStateException} is thrown if the
-         * builder is operated on after it has built a stream.
+         * Builds the stream, transitioning this builder to the built state.
+         * An {@code IllegalStateException} is thrown if there are further attempts
+         * to operate on the builder after it has entered the built state.
          *
          * @return the built stream
-         * @throws IllegalStateException if the builder has built a stream
+         * @throws IllegalStateException if the builder has already transitioned
+         * to the built state
          */
         DoubleStream build();
     }
--- a/src/share/classes/java/util/stream/Streams.java	Thu Apr 11 11:45:05 2013 -0400
+++ b/src/share/classes/java/util/stream/Streams.java	Thu Apr 11 15:53:17 2013 -0400
@@ -83,7 +83,7 @@
     /**
      * Creates an empty sequential {@code Stream}.
      *
-     * @param <T> Type of elements
+     * @param <T> The type of stream elements
      * @return An empty sequential {@code Stream}
      */
     public static<T> Stream<T> emptyStream() {
@@ -94,7 +94,7 @@
      * Creates a sequential {@code Stream} containing a single element.
      *
      * @param t The single element
-     * @param <T> Type of elements
+     * @param <T> The type of stream elements
      * @return A singleton sequential {@code Stream}
      */
     public static<T> Stream<T> singletonStream(T t) {
© 2007, Oracle and/or its affiliates
Terms of Use · Privacy · Trademarks