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 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 * @return the element spliterator for this stream 83 */ spliterator()84 Spliterator<T> spliterator(); 85 86 /** 87 * Returns whether this stream, if a terminal operation were to be executed, 88 * would execute in parallel. Calling this method after invoking an 89 * terminal stream operation method may yield unpredictable results. 90 * 91 * @return {@code true} if this stream would execute in parallel if executed 92 */ isParallel()93 boolean isParallel(); 94 95 /** 96 * Returns an equivalent stream that is sequential. May return 97 * itself, either because the stream was already sequential, or because 98 * the underlying stream state was modified to be sequential. 99 * 100 * <p>This is an <a href="package-summary.html#StreamOps">intermediate 101 * operation</a>. 102 * 103 * @return a sequential stream 104 */ sequential()105 S sequential(); 106 107 /** 108 * Returns an equivalent stream that is parallel. May return 109 * itself, either because the stream was already parallel, or because 110 * the underlying stream state was modified to be parallel. 111 * 112 * <p>This is an <a href="package-summary.html#StreamOps">intermediate 113 * operation</a>. 114 * 115 * @return a parallel stream 116 */ parallel()117 S parallel(); 118 119 /** 120 * Returns an equivalent stream that is 121 * <a href="package-summary.html#Ordering">unordered</a>. May return 122 * itself, either because the stream was already unordered, or because 123 * the underlying stream state was modified to be unordered. 124 * 125 * <p>This is an <a href="package-summary.html#StreamOps">intermediate 126 * operation</a>. 127 * 128 * @return an unordered stream 129 */ unordered()130 S unordered(); 131 132 /** 133 * Returns an equivalent stream with an additional close handler. Close 134 * handlers are run when the {@link #close()} method 135 * is called on the stream, and are executed in the order they were 136 * added. All close handlers are run, even if earlier close handlers throw 137 * exceptions. If any close handler throws an exception, the first 138 * exception thrown will be relayed to the caller of {@code close()}, with 139 * any remaining exceptions added to that exception as suppressed exceptions 140 * (unless one of the remaining exceptions is the same exception as the 141 * first exception, since an exception cannot suppress itself.) May 142 * return itself. 143 * 144 * <p>This is an <a href="package-summary.html#StreamOps">intermediate 145 * operation</a>. 146 * 147 * @param closeHandler A task to execute when the stream is closed 148 * @return a stream with a handler that is run if the stream is closed 149 */ onClose(Runnable closeHandler)150 S onClose(Runnable closeHandler); 151 152 /** 153 * Closes this stream, causing all close handlers for this stream pipeline 154 * to be called. 155 * 156 * @see AutoCloseable#close() 157 */ 158 @Override close()159 void close(); 160 } 161