Hi, For the flatMap operations of streams we forgot to say what it does with the mapped streams after it has processed them i.e. closes them, which is important for I/O backed streams (e.g. map Path -> Stream<String> for lines of a file). The following patch fixes that omission in the docs:
https://bugs.openjdk.java.net/browse/JDK-8032190 I think this should be backported to 8. Paul. diff -r 9bf43f25eacd src/share/classes/java/util/stream/DoubleStream.java --- a/src/share/classes/java/util/stream/DoubleStream.java Sat Jan 18 10:57:41 2014 -0800 +++ b/src/share/classes/java/util/stream/DoubleStream.java Mon Jan 20 11:34:17 2014 +0100 @@ -150,10 +150,11 @@ /** * Returns a stream consisting of the results of replacing each element of - * this stream with the contents of the stream produced by applying the - * provided mapping function to each element. (If the result of the mapping - * function is {@code null}, this is treated as if the result was an empty - * stream.) + * this stream with the contents of a mapped stream produced by applying + * the provided mapping function to each element. Each mapped stream is + * closed (see {@link java.util.stream.BaseStream#close()}) after its + * contents have been placed into this stream. (If a mapped stream is + * {@code null} then it treated as if it was an empty stream.) * * <p>This is an <a href="package-summary.html#StreamOps">intermediate * operation</a>. diff -r 9bf43f25eacd src/share/classes/java/util/stream/IntStream.java --- a/src/share/classes/java/util/stream/IntStream.java Sat Jan 18 10:57:41 2014 -0800 +++ b/src/share/classes/java/util/stream/IntStream.java Mon Jan 20 11:34:17 2014 +0100 @@ -146,10 +146,11 @@ /** * Returns a stream consisting of the results of replacing each element of - * this stream with the contents of the stream produced by applying the - * provided mapping function to each element. (If the result of the mapping - * function is {@code null}, this is treated as if the result was an empty - * stream.) + * this stream with the contents of a mapped stream produced by applying + * the provided mapping function to each element. Each mapped stream is + * closed (see {@link java.util.stream.BaseStream#close()}) after its + * contents have been placed into this stream. (If a mapped stream is + * {@code null} then it treated as if it was an empty stream.) * * <p>This is an <a href="package-summary.html#StreamOps">intermediate * operation</a>. diff -r 9bf43f25eacd src/share/classes/java/util/stream/LongStream.java --- a/src/share/classes/java/util/stream/LongStream.java Sat Jan 18 10:57:41 2014 -0800 +++ b/src/share/classes/java/util/stream/LongStream.java Mon Jan 20 11:34:17 2014 +0100 @@ -151,10 +151,11 @@ /** * Returns a stream consisting of the results of replacing each element of - * this stream with the contents of the stream produced by applying the - * provided mapping function to each element. (If the result of the mapping - * function is {@code null}, this is treated as if the result was an empty - * stream.) + * this stream with the contents of a mapped stream produced by applying + * the provided mapping function to each element. Each mapped stream is + * closed (see {@link java.util.stream.BaseStream#close()}) after its + * contents have been placed into this stream. (If a mapped stream is + * {@code null} then it treated as if it was an empty stream.) * * <p>This is an <a href="package-summary.html#StreamOps">intermediate * operation</a>. diff -r 9bf43f25eacd src/share/classes/java/util/stream/Stream.java --- a/src/share/classes/java/util/stream/Stream.java Sat Jan 18 10:57:41 2014 -0800 +++ b/src/share/classes/java/util/stream/Stream.java Mon Jan 20 11:34:17 2014 +0100 @@ -227,10 +227,11 @@ /** * Returns a stream consisting of the results of replacing each element of - * this stream with the contents of the stream produced by applying the - * provided mapping function to each element. (If the result of the mapping - * function is {@code null}, this is treated as if the result was an empty - * stream.) + * this stream with the contents of a mapped stream produced by applying + * the provided mapping function to each element. Each mapped stream is + * closed (see {@link java.util.stream.BaseStream#close()}) after its + * contents have been placed into this stream. (If a mapped stream is + * {@code null} then it treated as if it was an empty stream.) * * <p>This is an <a href="package-summary.html#StreamOps">intermediate * operation</a>. @@ -270,10 +271,11 @@ /** * Returns an {@code IntStream} consisting of the results of replacing each - * element of this stream with the contents of the stream produced by - * applying the provided mapping function to each element. (If the result - * of the mapping function is {@code null}, this is treated as if the result - * was an empty stream.) + * element of this stream with the contents of a mapped stream produced by + * applying the provided mapping function to each element. Each mapped + * stream is closed (see {@link java.util.stream.BaseStream#close()}) after + * its contents have been placed into this stream. (If a mapped stream is + * {@code null} then it treated as if it was an empty stream.) * * <p>This is an <a href="package-summary.html#StreamOps">intermediate * operation</a>. @@ -288,11 +290,12 @@ IntStream flatMapToInt(Function<? super T, ? extends IntStream> mapper); /** - * Returns a {@code LongStream} consisting of the results of replacing each - * element of this stream with the contents of the stream produced - * by applying the provided mapping function to each element. (If the result - * of the mapping function is {@code null}, this is treated as if the result - * was an empty stream.) + * Returns an {@code LongStream} consisting of the results of replacing each + * element of this stream with the contents of a mapped stream produced by + * applying the provided mapping function to each element. Each mapped + * stream is closed (see {@link java.util.stream.BaseStream#close()}) after + * its contents have been placed into this stream. (If a mapped stream is + * {@code null} then it treated as if it was an empty stream.) * * <p>This is an <a href="package-summary.html#StreamOps">intermediate * operation</a>. @@ -307,11 +310,12 @@ LongStream flatMapToLong(Function<? super T, ? extends LongStream> mapper); /** - * Returns a {@code DoubleStream} consisting of the results of replacing each - * element of this stream with the contents of the stream produced - * by applying the provided mapping function to each element. (If the result - * of the mapping function is {@code null}, this is treated as if the result - * was an empty stream.) + * Returns an {@code DoubleStream} consisting of the results of replacing + * each element of this stream with the contents of a mapped stream produced + * by applying the provided mapping function to each element. Each mapped + * stream is closed (see {@link java.util.stream.BaseStream#close()}) after + * its contents have placed been into this stream. (If a mapped stream is + * {@code null} then it treated as if it was an empty stream.) * * <p>This is an <a href="package-summary.html#StreamOps">intermediate * operation</a>.
