909 

   910     /**

   911      * A mutable builder for a {@code Stream}.  This allows the creation of a

   912      * {@code Stream} by generating elements individually and adding them to the

   913      * {@code Builder} (without the copying overhead that comes from using

   914      * an {@code ArrayList} as a temporary buffer.)

   915      *

   916      * <p>A {@code Stream.Builder} has a lifecycle, where it starts in a building

   917      * phase, during which elements can be added, and then transitions to a built

   918      * phase, after which elements may not be added.  The built phase begins

   919      * when the {@link #build()} method is called, which creates an ordered

   920      * {@code Stream} whose elements are the elements that were added to the stream

   921      * builder, in the order they were added.

   922      *

   923      * @param <T> the type of stream elements

   924      * @see Stream#builder()

   925      * @since 1.8

   926      */

   927     public interface Builder<T> extends Consumer<T> {

   928 

   929         /**

   930          * Adds an element to the stream being built.

   931          *

   932          * @throws IllegalStateException if the builder has already transitioned to

   933          * the built state

   934          */

   935         @Override

   936         void accept(T t);

   937 

   938         /**

   939          * Adds an element to the stream being built.

   940          *

   941          * @implSpec

   942          * The default implementation behaves as if:

   943          * <pre>{@code

   944          *     accept(t)

   945          *     return this;

   946          * }</pre>

   947          *

   948          * @param t the element to add

   949          * @return {@code this} builder

   950          * @throws IllegalStateException if the builder has already transitioned to

   951          * the built state

   952          */

   953         default Builder<T> add(T t) {

   954             accept(t);

   955             return this;

   956         }

   957 

   958         /**

   959          * Builds the stream, transitioning this builder to the built state.

   960          * An {@code IllegalStateException} is thrown if there are further attempts

   961          * to operate on the builder after it has entered the built state.

   962          *

   963          * @return the built stream

   964          * @throws IllegalStateException if the builder has already transitioned to

   965          * the built state

   966          */

   967         Stream<T> build();

   968 

   969     }