8181175 Stream.concat behaves like terminal operation

[Stuart Marks]

Hi Paul,

The normative text about binding to the source and subsequent modifications to 
the source possibly not being reflected in the stream makes sense.

I'm having trouble understanding the API note though. What does "optimal" mean? 
What about concatenating multiple streams would not be optimal?

s'marks

On 11/17/17 12:02 PM, Paul Sandoz wrote:
> Hi,
> 
> Please review this small specification classification for Stream.concat:
> 
> http://cr.openjdk.java.net/~psandoz/jdk10/JDK-8181175-concat-eager-binding/webrev/src/java.base/share/classes/java/util/stream/Stream.java.sdiff.html
> 
> A CSR will be created.
> 
> I decided to call out that Stream.concat binds to its input stream sources rather than hedging bets and being ambiguous.
> 
> If we choose to add a var args concat method then it is highly unlikely we will be able to optimize for three or more streams in the same manner as we do for two streams  and it would in effect be (as in the api note i added) implemented using a flat map. In that case such a method can be called out as not binding and concatenating two streams can be performed by passing an empty stream as the third argument.
> 
> Thanks,
> Paul.
> 
> diff -r 52bcd99c60f8 src/java.base/share/classes/java/util/stream/Stream.java
> --- a/src/java.base/share/classes/java/util/stream/Stream.java	Fri Nov 17 11:56:48 2017 -0800
> +++ b/src/java.base/share/classes/java/util/stream/Stream.java	Fri Nov 17 12:02:13 2017 -0800
> @@ -1,5 +1,5 @@
>   /*
> - * Copyright (c) 2012, 2016, Oracle and/or its affiliates. All rights reserved.
> + * 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
> @@ -1341,6 +1341,10 @@
>        * 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
> +     * 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
> @@ -1349,6 +1353,15 @@
>        * <p>Subsequent changes to the sequential/parallel execution mode of the
>        * returned stream are not guaranteed to be propagated to the input streams.
>        *
> +     * @apiNote
> +     * This method will produce an optimal concatenated stream.  To achieve this
> +     * only two input streams are accepted and each is bound to its source.
> +     * If such restrictions are an issue then consider the alternative: create a
> +     * stream of streams and flat-map 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
>