< prev index next >

src/java.base/share/classes/java/util/stream/Stream.java

Print this page
rev 47861 : 8181175: Stream.concat behaves like terminal operation
Reviewed-by: smarks, briangoetz, dfuchs

*** 1,7 **** /* ! * Copyright (c) 2012, 2016, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this --- 1,7 ---- /* ! * Copyright (c) 2012, 2017, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this
*** 1339,1356 **** --- 1339,1372 ---- * second stream. The resulting stream is ordered if both * of the input streams are ordered, and parallel if either of the input * streams is parallel. When the resulting stream is closed, the close * handlers for both input streams are invoked. * + * <p>This method operates on the two input streams and binds each stream + * to its source. As a result subsequent modifications to an input stream + * source may not be reflected in the concatenated stream result. + * * @implNote * Use caution when constructing streams from repeated concatenation. * Accessing an element of a deeply concatenated stream can result in deep * call chains, or even {@code StackOverflowError}. * * <p>Subsequent changes to the sequential/parallel execution mode of the * returned stream are not guaranteed to be propagated to the input streams. * + * @apiNote + * To preserve optimization opportunities this method binds each stream to + * its source and accepts only two streams as parameters. For example, the + * exact size of the concatenated stream source can be computed if the exact + * size of each input stream source is known. + * To concatenate more streams without binding, or without nested calls to + * this method, try creating a stream of streams and flat-mapping with the + * identity function, for example: + * <pre>{@code + * Stream<T> concat = Stream.of(s1, s2, s3, s4).flatMap(s -> s); + * }</pre> + * * @param <T> The type of stream elements * @param a the first stream * @param b the second stream * @return the concatenation of the two input streams */
< prev index next >