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.util.Collection; 29 import java.util.Iterator; 30 import java.util.Spliterator; 31 import java.util.concurrent.ConcurrentHashMap; 32 import java.util.function.IntConsumer; 33 import 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 */ 62 public 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 */ iterator()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 */ spliterator()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 */ isParallel()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 */ sequential()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 */ parallel()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 */ unordered()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 */ onClose(Runnable closeHandler)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 close()157 void close(); 158 } 159