1 /*
   2  * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 package java.util.stream;
  26 
  27 import java.util.Iterator;
  28 import java.util.Spliterator;
  29 
  30 /**
  31  * Base interface for stream types such as {@link Stream}, {@link IntStream},
  32  * etc.  Contains methods common to all stream types.
  33  *
  34  * @param <T> type of stream elements
  35  * @param <S> type of stream implementing {@code BaseStream}
  36  * @since 1.8
  37  */
  38 public interface BaseStream<T, S extends BaseStream<T, S>>
  39         extends AutoCloseable {
  40     /**
  41      * Returns an iterator for the elements of this stream.
  42      *
  43      * <p>This is a <a href="package-summary.html#StreamOps">terminal
  44      * operation</a>.
  45      *
  46      * @return the element iterator for this stream
  47      */
  48     Iterator<T> iterator();
  49 
  50     /**
  51      * Returns a spliterator for the elements of this stream.
  52      *
  53      * <p>This is a <a href="package-summary.html#StreamOps">terminal
  54      * operation</a>.
  55      *
  56      * @return the element spliterator for this stream
  57      */
  58     Spliterator<T> spliterator();
  59 
  60     /**
  61      * Returns whether this stream, when executed, would execute in parallel
  62      * (assuming no further modification of the stream, such as appending
  63      * further intermediate operations or changing its parallelism).  Calling
  64      * this method after invoking an intermediate or terminal stream operation
  65      * method may yield unpredictable results.
  66      *
  67      * @return {@code true} if this stream would execute in parallel if executed
  68      * without further modification otherwise {@code false}
  69      */
  70     boolean isParallel();
  71 
  72     /**
  73      * Returns an equivalent stream that is sequential.  May return
  74      * itself, either because the stream was already sequential, or because
  75      * the underlying stream state was modified to be sequential.
  76      *
  77      * <p>This is an <a href="package-summary.html#StreamOps">intermediate
  78      * operation</a>.
  79      *
  80      * @return a sequential stream
  81      */
  82     S sequential();
  83 
  84     /**
  85      * Returns an equivalent stream that is parallel.  May return
  86      * itself, either because the stream was already parallel, or because
  87      * the underlying stream state was modified to be parallel.
  88      *
  89      * <p>This is an <a href="package-summary.html#StreamOps">intermediate
  90      * operation</a>.
  91      *
  92      * @return a parallel stream
  93      */
  94     S parallel();
  95 
  96     /**
  97      * Returns an equivalent stream that is
  98      * <a href="package-summary.html#Ordering">unordered</a>.  May return
  99      * itself if the stream was already unordered.
 100      *
 101      * <p>This is an <a href="package-summary.html#StreamOps">intermediate
 102      * operation</a>.
 103      *
 104      * @return an unordered stream
 105      */
 106     S unordered();
 107 
 108     /**
 109      * Returns an equivalent stream with an additional close handler.  Close
 110      * handlers are run when the {@link #close()} method
 111      * is called on the stream, and are executed in the order they were
 112      * added.  All close handlers are run, even if earlier close handlers throw
 113      * exceptions.  If any close handler throws an exception, the first
 114      * exception thrown will be relayed to the caller of {@code close()}, with
 115      * any remaining exceptions added to that exception as suppressed exceptions
 116      * (unless one of the remaining exceptions is the same exception as the
 117      * first exception, since an exception cannot suppress itself.)  May
 118      * return itself.
 119      *
 120      * <p>This is an <a href="package-summary.html#StreamOps">intermediate
 121      * operation</a>.
 122      *
 123      * @param closeHandler A task to execute when the stream is closed
 124      * @return a stream with a handler that is run if the stream is closed
 125      */
 126     S onClose(Runnable closeHandler);
 127 
 128     /**
 129      * Closes this stream, causing all close handlers for this stream pipeline
 130      * to be called.
 131      *
 132      * @see AutoCloseable#close()
 133      */
 134     @Override
 135     void close();
 136 }