content: /*
   * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
   * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   *
   * This code is free software; you can redistribute it and/or modify it
   * under the terms of the GNU General Public License version 2 only, as
   * published by the Free Software Foundation.  Oracle designates this
   * particular file as subject to the "Classpath" exception as provided
   * by Oracle in the LICENSE file that accompanied this code.
   *
   * This code is distributed in the hope that it will be useful, but WITHOUT
   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
   * version 2 for more details (a copy is included in the LICENSE file that
   * accompanied this code).
   *
   * You should have received a copy of the GNU General Public License version
   * 2 along with this work; if not, write to the Free Software Foundation,
   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
   *
   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
   * or visit www.oracle.com if you need additional information or have any
   * questions.
   */
  package java.util.stream;
  
  import java.nio.charset.Charset;
  import java.nio.file.Files;
  import java.nio.file.Path;
  import java.util.Collection;
  import java.util.Iterator;
  import java.util.Spliterator;
  import java.util.concurrent.ConcurrentHashMap;
  import java.util.function.IntConsumer;
  import java.util.function.Predicate;
  
  /**
   * Base interface for streams, which are sequences of elements supporting
   * sequential and parallel aggregate operations.  The following example
   * illustrates an aggregate operation using the stream types {@link Stream}
   * and {@link IntStream}, computing the sum of the weights of the red widgets:
   *
   * <pre>{@code
   *     int sum = widgets.stream()
   *                      .filter(w -> w.getColor() == RED)
   *                      .mapToInt(w -> w.getWeight())
   *                      .sum();
   * }</pre>
   *
   * See the class documentation for {@link Stream} and the package documentation
   * for <a href="package-summary.html">java.util.stream</a> for additional
   * specification of streams, stream operations, stream pipelines, and
   * parallelism, which governs the behavior of all stream types.
   *
   * @param <T> the type of the stream elements
   * @param <S> the type of of the stream implementing {@code BaseStream}
   * @since 1.8
   * @see Stream
   * @see IntStream
   * @see LongStream
   * @see DoubleStream
   * @see <a href="package-summary.html">java.util.stream</a>
   */
  public interface BaseStream<T, S extends BaseStream<T, S>>
          extends AutoCloseable {
      /**
       * Returns an iterator for the elements of this stream.
       *
       * <p>This is a <a href="package-summary.html#StreamOps">terminal
       * operation</a>.
       *
       * @return the element iterator for this stream
       */
      Iterator<T> iterator();
  
      /**
       * Returns a spliterator for the elements of this stream.
       *
       * <p>This is a <a href="package-summary.html#StreamOps">terminal
       * operation</a>.
       *
       * @return the element spliterator for this stream
       */
      Spliterator<T> spliterator();
  
      /**
       * Returns whether this stream, if a terminal operation were to be executed,
       * would execute in parallel.  Calling this method after invoking an
       * terminal stream operation method may yield unpredictable results.
       *
       * @return {@code true} if this stream would execute in parallel if executed
       */
      boolean isParallel();
  
      /**
       * Returns an equivalent stream that is sequential.  May return
       * itself, either because the stream was already sequential, or because
       * the underlying stream state was modified to be sequential.
       *
       * <p>This is an <a href="package-summary.html#StreamOps">intermediate
       * operation</a>.
       *
       * @return a sequential stream
       */
      S sequential();
  
      /**
       * Returns an equivalent stream that is parallel.  May return
       * itself, either because the stream was already parallel, or because
       * the underlying stream state was modified to be parallel.
       *
       * <p>This is an <a href="package-summary.html#StreamOps">intermediate
       * operation</a>.
       *
       * @return a parallel stream
       */
      S parallel();
  
      /**
       * Returns an equivalent stream that is
       * <a href="package-summary.html#Ordering">unordered</a>.  May return
       * itself, either because the stream was already unordered, or because
       * the underlying stream state was modified to be unordered.
       *
       * <p>This is an <a href="package-summary.html#StreamOps">intermediate
       * operation</a>.
       *
       * @return an unordered stream
       */
      S unordered();
  
      /**
       * Returns an equivalent stream with an additional close handler.  Close
       * handlers are run when the {@link #close()} method
       * is called on the stream, and are executed in the order they were
       * added.  All close handlers are run, even if earlier close handlers throw
       * exceptions.  If any close handler throws an exception, the first
       * exception thrown will be relayed to the caller of {@code close()}, with
       * any remaining exceptions added to that exception as suppressed exceptions
       * (unless one of the remaining exceptions is the same exception as the
       * first exception, since an exception cannot suppress itself.)  May
       * return itself.
       *
       * <p>This is an <a href="package-summary.html#StreamOps">intermediate
       * operation</a>.
       *
       * @param closeHandler A task to execute when the stream is closed
       * @return a stream with a handler that is run if the stream is closed
       */
      S onClose(Runnable closeHandler);
  
      /**
       * Closes this stream, causing all close handlers for this stream pipeline
       * to be called.
       *
       * @see AutoCloseable#close()
       */
      @Override
      void close();
  }
  