1 /* 2 * Copyright (c) 2012, 2023, 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 * @apiNote 73 * This operation is provided as an "escape hatch" to enable 74 * arbitrary client-controlled pipeline traversals in the event that the 75 * existing operations are not sufficient to the task. 76 * 77 * @return the element iterator for this stream 78 */ iterator()79 Iterator<T> iterator(); 80 81 /** 82 * Returns a spliterator for the elements of this stream. 83 * 84 * <p>This is a <a href="package-summary.html#StreamOps">terminal 85 * operation</a>. 86 * 87 * @apiNote 88 * This operation is provided as an "escape hatch" to enable 89 * arbitrary client-controlled pipeline traversals in the event that the 90 * existing operations are not sufficient to the task. 91 * 92 * <p> 93 * The returned spliterator should report the set of characteristics derived 94 * from the stream pipeline (namely the characteristics derived from the 95 * stream source spliterator and the intermediate operations). 96 * Implementations may report a sub-set of those characteristics. For 97 * example, it may be too expensive to compute the entire set for some or 98 * all possible stream pipelines. 99 * 100 * @return the element spliterator for this stream 101 */ spliterator()102 Spliterator<T> spliterator(); 103 104 /** 105 * Returns whether this stream, if a terminal operation were to be executed, 106 * would execute in parallel. Calling this method after invoking an 107 * terminal stream operation method may yield unpredictable results. 108 * 109 * @return {@code true} if this stream would execute in parallel if executed 110 */ isParallel()111 boolean isParallel(); 112 113 /** 114 * Returns an equivalent stream that is sequential. May return 115 * itself, either because the stream was already sequential, or because 116 * the underlying stream state was modified to be sequential. 117 * 118 * <p>This is an <a href="package-summary.html#StreamOps">intermediate 119 * operation</a>. 120 * 121 * @return a sequential stream 122 */ sequential()123 S sequential(); 124 125 /** 126 * Returns an equivalent stream that is parallel. May return 127 * itself, either because the stream was already parallel, or because 128 * the underlying stream state was modified to be parallel. 129 * 130 * <p>This is an <a href="package-summary.html#StreamOps">intermediate 131 * operation</a>. 132 * 133 * @return a parallel stream 134 */ parallel()135 S parallel(); 136 137 /** 138 * Returns an equivalent stream that is 139 * <a href="package-summary.html#Ordering">unordered</a>. May return 140 * itself, either because the stream was already unordered, or because 141 * the underlying stream state was modified to be unordered. 142 * 143 * <p>This is an <a href="package-summary.html#StreamOps">intermediate 144 * operation</a>. 145 * 146 * @return an unordered stream 147 */ unordered()148 S unordered(); 149 150 /** 151 * Returns an equivalent stream with an additional close handler. Close 152 * handlers are run when the {@link #close()} method 153 * is called on the stream, and are executed in the order they were 154 * added. All close handlers are run, even if earlier close handlers throw 155 * exceptions. If any close handler throws an exception, the first 156 * exception thrown will be relayed to the caller of {@code close()}, with 157 * any remaining exceptions added to that exception as suppressed exceptions 158 * (unless one of the remaining exceptions is the same exception as the 159 * first exception, since an exception cannot suppress itself.) May 160 * return itself. 161 * 162 * <p>This is an <a href="package-summary.html#StreamOps">intermediate 163 * operation</a>. 164 * 165 * @param closeHandler A task to execute when the stream is closed 166 * @return a stream with a handler that is run if the stream is closed 167 */ onClose(Runnable closeHandler)168 S onClose(Runnable closeHandler); 169 170 /** 171 * Closes this stream, causing all close handlers for this stream pipeline 172 * to be called. 173 * 174 * @see AutoCloseable#close() 175 */ 176 @Override close()177 void close(); 178 } 179