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