JDK-8067661: transferTo proposal for Appendable

[Pavel Rappo]

Hi Patrick, nice to hear from you again! I agree we should consider adding this
method. Unfortunately, from the spec point of view I suppose this one will
require a lot more chewing. For instance there's nothing that can be closed
either in Readable or Appendable (in general case), since neither of them is
java.io.Closeable or even java.lang.AutoCloseable. In my opinion, all mentions
of 'close' operations should go. You're fine to elaborate spec down the
hierarchy though:

    /**
     *
     ... some specifics for Readers ...
     *
     */
    @Override
    public long transferTo(Appendable out) throws IOException {
        return Readable.super.transferTo(out);
    }

But at the same time this one, you added, is crucial:

    * one, or both participants may be in an inconsistent state
    
So you give implementors the freedom to use "if anything bad happens all bets
are off".
It's also not fully clear what it means for an instance of Readable to be
"at end of its data". This have a well-defined meaning for java.io.Reader though.

-Pavel

> On 16 Dec 2014, at 22:13, Patrick Reinhart <patrick at reini.net> wrote:
> 
> Hi Chris & Pavel,
> 
> 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. It is strongly
>     * recommended that both readable and appendable be promptly closed 
>     * if needed and an I/O error occurs.
>     *
>     * @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 1.9
>     */
>    default long transferTo(Appendable out) throws IOException {
>    ....
>    }
> 
> 
> -Patrick
> 
>