diff -r 9fa4af2af63d -r 06636235cd12 jdk/src/share/classes/java/util/stream/Stream.java --- 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 type of elements * @return a stream builder */ - public static StreamBuilder builder() { + public static Builder builder() { return new Streams.StreamBuilderImpl<>(); } @@ -906,4 +906,65 @@ (Spliterator) a.spliterator(), (Spliterator) 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.) + * + *

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 the type of stream elements + * @see Stream#builder() + * @since 1.8 + */ + public interface Builder extends Consumer { + + /** + * 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: + *

{@code
+         *     accept(t)
+         *     return this;
+         * }
+ * + * @param t the element to add + * @return {@code this} builder + * @throws IllegalStateException if the builder has already transitioned to + * the built state + */ + default Builder 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 build(); + + } }