JDK-8067661: transferTo proposal for Appendable

[Roger Riggs]

Hi Patrick,

Sounds like a good idea to me.

Do you have any suggestions for concrete implementations that may 
benefit from specialized
implementations?

As a 'push' API, an implementation will necessarily have to allocate a 
buffer and read
characters and then append them to the appendable.  I don't remember if 
a 'pull' API was
considered for streams in which the dest could provide its own buffer to 
the reader
and benefit from one less copy of the bytes.

Thanks, Roger


On 10/28/2017 10:05 AM, Patrick Reinhart wrote:
> Hi There,
>
> Based on the *transferTo* Method on the InputStream I would propose to
> introduce a
> default method on the Readable interface. In that way the method can be
> used for
> all existing implementations of Readable and still be implemented in a
> special
> way by a individual implementer.
>
>
>     /**
>
>      * Reads all characters from this readable and writes the characters to
>      * the given appendable in the order that they are read. On return, this
>      * readable will be at end its data.
>      * <p>
>      * This method may block indefinitely reading from the readable, or
>      * writing to the appendable. The behavior for the case where the
> readable
>      * and/or appendable is <i>asynchronously closed</i>, or the thread
>      * interrupted during the transfer, is highly readable and appendable
>      * specific, and therefore not specified.
>      * <p>
>      * If an I/O error occurs reading from the readable or writing to the
>      * appendable, then it may do so after some characters have been read or
>      * written. Consequently the readable may not be at end of its data and
>      * one, or both participants may be in an inconsistent state. That in
> mind
>      * all additional measures required by one or both participants in
> order to
>      * eventually free their internal resources have to be taken by the
> caller
>      * of this method.
>      *
>      * @param  out the appendable, non-null
>      * @return the number of characters transferred
>      * @throws IOException if an I/O error occurs when reading or writing
>      * @throws NullPointerException if {@code out} is {@code null}
>      *
>      * @since 18.3
>      */
>     default long transferTo(Appendable out) throws IOException {
>     ....
>     }
>
>
> Cheers Patrick