jdk/src/share/classes/java/util/stream/Stream.java
changeset 18825 06636235cd12
parent 18822 4b6be7c19547
child 19199 4dfcc94aa1f2
--- a/jdk/src/share/classes/java/util/stream/Stream.java	Fri Jul 12 15:01:08 2013 -0700
+++ b/jdk/src/share/classes/java/util/stream/Stream.java	Mon Jul 08 15:46:26 2013 -0400
@@ -794,7 +794,7 @@
      * @param <T> type of elements
      * @return a stream builder
      */
-    public static<T> StreamBuilder<T> builder() {
+    public static<T> Builder<T> builder() {
         return new Streams.StreamBuilderImpl<>();
     }
 
@@ -906,4 +906,65 @@
                 (Spliterator<T>) a.spliterator(), (Spliterator<T>) b.spliterator());
         return StreamSupport.stream(split, a.isParallel() || b.isParallel());
     }
+
+    /**
+     * A mutable builder for a {@code Stream}.  This allows the creation of a
+     * {@code Stream} by generating elements individually and adding them to the
+     * {@code Builder} (without the copying overhead that comes from using
+     * an {@code ArrayList} as a temporary buffer.)
+     *
+     * <p>A {@code Stream.Builder} 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.
+     *
+     * @param <T> the type of stream elements
+     * @see Stream#builder()
+     * @since 1.8
+     */
+    public interface Builder<T> extends Consumer<T> {
+
+        /**
+         * Adds an element to the stream being built.
+         *
+         * @throws IllegalStateException if the builder has already transitioned to
+         * the built state
+         */
+        @Override
+        void accept(T t);
+
+        /**
+         * Adds an element to the stream being built.
+         *
+         * @implSpec
+         * The default implementation behaves as if:
+         * <pre>{@code
+         *     accept(t)
+         *     return this;
+         * }</pre>
+         *
+         * @param t the element to add
+         * @return {@code this} builder
+         * @throws IllegalStateException if the builder has already transitioned to
+         * the built state
+         */
+        default Builder<T> add(T t) {
+            accept(t);
+            return this;
+        }
+
+        /**
+         * 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 already transitioned to
+         * the built state
+         */
+        Stream<T> build();
+
+    }
 }