1 package java.util.stream;
   2 
   3 /**
   4  * A stateful intermediate stream operation ({@link IntermediateOp}).  <em>Stateful</em> means that state
   5  * is accumulated as elements are processed.  Examples of stateful operations are sorting, extracting a subsequence
   6  * of the input, or removing duplicates.  Statefulness has an effect on how the operation can be parallelized.
   7  * Stateless operations parallelize trivially because they are homomorphisms under concatenation:
   8  *
   9  * <pre>
  10  *     statelessOp(a || b) = statelessOp(a) || statelessOp(b)
  11  * </pre>
  12  *
  13  * where {@code ||} denotes concatenation.  Stateful operations may still be parallelizable, but are not amenable to
  14  * the automatic parallelization of stateless operations.  Accordingly, a stateful operation must provide its
  15  * own parallel execution implementation ({@link #evaluateParallel(PipelineHelper)}).
  16  *
  17  * @param <E> Type of input and output elements.
  18  *
  19  * @see IntermediateOp
  20  * @see TerminalOp
  21  * @since 1.8
  22  */
  23 interface StatefulOp<E> extends IntermediateOp<E, E> {
  24 
  25     /**
  26      * @{inheritDoc}
  27      * This method must return {@code true}
  28      * @implSpec The default implementations returns {@code true}
  29      * @return {@code true}
  30      */
  31     @Override
  32     public default boolean isStateful() {
  33         return true;
  34     }
  35 
  36     /**
  37      * {@inheritDoc}
  38      *
  39      * An implementation of this method must be provided, but it is acceptable if the implementation is sequential.
  40      * A generic sequential implementation is available as
  41      * {@link OpUtils#evaluateSequential(IntermediateOp, PipelineHelper)}.
  42      */
  43     <P_IN> Node<E> evaluateParallel(PipelineHelper<P_IN, E> helper);
  44 }