JDK-8067661: transferTo proposal for Appendable

[Patrick Reinhart]

Hi Pavel,

> 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);
>    }

You’re right. I also saw that neither Readable nor Appendable extend any of those *Closable interfaces.
I was not sure if that should belong to the Readable itself. To move those more specific parts down to
the Reader implementation is absolutely fine for me and seems to be a better fit.

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

I got your point here. I was not sure, what parts from the InputStream.transferTo() spec can be reused.

-Patrick

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