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.nio.charset.Charset;
28 import java.nio.file.Files;
29 import java.nio.file.Path;
30 import java.util.Collection;
31 import java.util.Iterator;
32 import java.util.Spliterator;
33 import java.util.concurrent.ConcurrentHashMap;
34 import java.util.function.IntConsumer;
35 import java.util.function.Predicate;
36 
37 /**
38  * Base interface for streams, which are sequences of elements supporting
39  * sequential and parallel aggregate operations.  The following example
40  * illustrates an aggregate operation using the stream types {@link Stream}
41  * and {@link IntStream}, computing the sum of the weights of the red widgets:
42  *
43  * <pre>{@code
44  *     int sum = widgets.stream()
45  *                      .filter(w -> w.getColor() == RED)
46  *                      .mapToInt(w -> w.getWeight())
47  *                      .sum();
48  * }</pre>
49  *
50  * See the class documentation for {@link Stream} and the package documentation
51  * for <a href="package-summary.html">java.util.stream</a> for additional
52  * specification of streams, stream operations, stream pipelines, and
53  * parallelism, which governs the behavior of all stream types.
54  *
55  * @param <T> the type of the stream elements
56  * @param <S> the type of the stream implementing {@code BaseStream}
57  * @since 1.8
58  * @see Stream
59  * @see IntStream
60  * @see LongStream
61  * @see DoubleStream
62  * @see <a href="package-summary.html">java.util.stream</a>
63  */
64 public interface BaseStream<T, S extends BaseStream<T, S>>
65         extends AutoCloseable {
66     /**
67      * Returns an iterator for the elements of this stream.
68      *
69      * <p>This is a <a href="package-summary.html#StreamOps">terminal
70      * operation</a>.
71      *
72      * @return the element iterator for this stream
73      */
iterator()74     Iterator<T> iterator();
75 
76     /**
77      * Returns a spliterator for the elements of this stream.
78      *
79      * <p>This is a <a href="package-summary.html#StreamOps">terminal
80      * operation</a>.
81      *
82      * <p>
83      * The returned spliterator should report the set of characteristics derived
84      * from the stream pipeline (namely the characteristics derived from the
85      * stream source spliterator and the intermediate operations).
86      * Implementations may report a sub-set of those characteristics.  For
87      * example, it may be too expensive to compute the entire set for some or
88      * all possible stream pipelines.
89      *
90      * @return the element spliterator for this stream
91      */
spliterator()92     Spliterator<T> spliterator();
93 
94     /**
95      * Returns whether this stream, if a terminal operation were to be executed,
96      * would execute in parallel.  Calling this method after invoking an
97      * terminal stream operation method may yield unpredictable results.
98      *
99      * @return {@code true} if this stream would execute in parallel if executed
100      */
isParallel()101     boolean isParallel();
102 
103     /**
104      * Returns an equivalent stream that is sequential.  May return
105      * itself, either because the stream was already sequential, or because
106      * the underlying stream state was modified to be sequential.
107      *
108      * <p>This is an <a href="package-summary.html#StreamOps">intermediate
109      * operation</a>.
110      *
111      * @return a sequential stream
112      */
sequential()113     S sequential();
114 
115     /**
116      * Returns an equivalent stream that is parallel.  May return
117      * itself, either because the stream was already parallel, or because
118      * the underlying stream state was modified to be parallel.
119      *
120      * <p>This is an <a href="package-summary.html#StreamOps">intermediate
121      * operation</a>.
122      *
123      * @return a parallel stream
124      */
parallel()125     S parallel();
126 
127     /**
128      * Returns an equivalent stream that is
129      * <a href="package-summary.html#Ordering">unordered</a>.  May return
130      * itself, either because the stream was already unordered, or because
131      * the underlying stream state was modified to be unordered.
132      *
133      * <p>This is an <a href="package-summary.html#StreamOps">intermediate
134      * operation</a>.
135      *
136      * @return an unordered stream
137      */
unordered()138     S unordered();
139 
140     /**
141      * Returns an equivalent stream with an additional close handler.  Close
142      * handlers are run when the {@link #close()} method
143      * is called on the stream, and are executed in the order they were
144      * added.  All close handlers are run, even if earlier close handlers throw
145      * exceptions.  If any close handler throws an exception, the first
146      * exception thrown will be relayed to the caller of {@code close()}, with
147      * any remaining exceptions added to that exception as suppressed exceptions
148      * (unless one of the remaining exceptions is the same exception as the
149      * first exception, since an exception cannot suppress itself.)  May
150      * return itself.
151      *
152      * <p>This is an <a href="package-summary.html#StreamOps">intermediate
153      * operation</a>.
154      *
155      * @param closeHandler A task to execute when the stream is closed
156      * @return a stream with a handler that is run if the stream is closed
157      */
onClose(Runnable closeHandler)158     S onClose(Runnable closeHandler);
159 
160     /**
161      * Closes this stream, causing all close handlers for this stream pipeline
162      * to be called.
163      *
164      * @see AutoCloseable#close()
165      */
166     @Override
close()167     void close();
168 }
169