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.util.Iterator; 28 import java.util.Spliterator; 29 30 /** 31 * Base interface for stream types such as {@link Stream}, {@link IntStream}, 32 * etc. Contains methods common to all stream types. 33 * 34 * @param <T> type of stream elements 35 * @param <S> type of stream implementing {@code BaseStream} 36 * @since 1.8 37 */ 38 public interface BaseStream<T, S extends BaseStream<T, S>> 39 extends AutoCloseable { 40 /** 41 * Returns an iterator for the elements of this stream. 42 * 43 * <p>This is a <a href="package-summary.html#StreamOps">terminal 44 * operation</a>. 45 * 46 * @return the element iterator for this stream 47 */ 48 Iterator<T> iterator(); 49 50 /** 51 * Returns a spliterator for the elements of this stream. 52 * 53 * <p>This is a <a href="package-summary.html#StreamOps">terminal 54 * operation</a>. 55 * 56 * @return the element spliterator for this stream 57 */ 58 Spliterator<T> spliterator(); 59 60 /** 61 * Returns whether this stream, when executed, would execute in parallel 62 * (assuming no further modification of the stream, such as appending 63 * further intermediate operations or changing its parallelism). Calling 64 * this method after invoking an intermediate or terminal stream operation 65 * method may yield unpredictable results. 66 * 67 * @return {@code true} if this stream would execute in parallel if executed 68 * without further modification otherwise {@code false} 69 */ 70 boolean isParallel(); 71 72 /** 73 * Returns an equivalent stream that is sequential. May return 74 * itself, either because the stream was already sequential, or because 75 * the underlying stream state was modified to be sequential. 76 * 77 * <p>This is an <a href="package-summary.html#StreamOps">intermediate 78 * operation</a>. 79 * 80 * @return a sequential stream 81 */ 82 S sequential(); 83 84 /** 85 * Returns an equivalent stream that is parallel. May return 86 * itself, either because the stream was already parallel, or because 87 * the underlying stream state was modified to be parallel. 88 * 89 * <p>This is an <a href="package-summary.html#StreamOps">intermediate 90 * operation</a>. 91 * 92 * @return a parallel stream 93 */ 94 S parallel(); 95 96 /** 97 * Returns an equivalent stream that is 98 * <a href="package-summary.html#Ordering">unordered</a>. May return 99 * itself if the stream was already unordered. 100 * 101 * <p>This is an <a href="package-summary.html#StreamOps">intermediate 102 * operation</a>. 103 * 104 * @return an unordered stream 105 */ 106 S unordered(); 107 108 /** 109 * Returns an equivalent stream with an additional close handler. Close 110 * handlers are run when the {@link #close()} method 111 * is called on the stream, and are executed in the order they were 112 * added. All close handlers are run, even if earlier close handlers throw 113 * exceptions. If any close handler throws an exception, the first 114 * exception thrown will be relayed to the caller of {@code close()}, with 115 * any remaining exceptions added to that exception as suppressed exceptions 116 * (unless one of the remaining exceptions is the same exception as the 117 * first exception, since an exception cannot suppress itself.) May 118 * return itself. 119 * 120 * <p>This is an <a href="package-summary.html#StreamOps">intermediate 121 * operation</a>. 122 * 123 * @param closeHandler A task to execute when the stream is closed 124 * @return a stream with a handler that is run if the stream is closed 125 */ 126 S onClose(Runnable closeHandler); 127 128 /** 129 * Closes this stream, causing all close handlers for this stream pipeline 130 * to be called. 131 * 132 * @see AutoCloseable#close() 133 */ 134 @Override 135 void close(); 136 }