It is good to clarify that the streams are closed.
I find the following updated wording a little odd, "If a mapped stream
is {@code null} then it treated as if it was an empty stream." I thought
the previous wording was better, but that could be just me.
-Chris.
On 20/01/14 10:38, Paul Sandoz wrote:
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>.
