RFR: 8032190 It's unclear that flatMap will ensure each stream will be closed.

[Chris Hegarty]

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>.
>