JDK-8067661: transferTo proposal for Appendable

[Patrick Reinhart]

Hi Alan,

The latest version is here:

http://cr.openjdk.java.net/~reinhapa/reviews/8067661/signature


> Am 02.11.2017 um 14:52 schrieb Alan Bateman <Alan.Bateman at oracle.com>:
> 
> On 01/11/2017 14:57, Patrick Reinhart wrote:
>> I tried to put that in my latest proposal:
>> 
>> /**
>>  * 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.
> You might want to try using  "this source" in the wording, as in "On return, the source of characters will be at its end". I think this will make it a bit more consistent with the existing wording in the read method.

That would read then something like this:

 * Reads all characters from this readable and writes the characters to
 * the given appendable in the order that they are read. On return, the
 * source of characters will be at its end.


> 
>>  * <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.
> I think this needs more setup to allow for close, maybe „Where this source or the appendable is {@link AutoCloseable closeable} then the behavior when either are asynchronously closed …“.

The second part:

 * This method may block indefinitely reading from the readable, or
 * writing to the appendable. Where this source or the appendable is
 * {@link java.io.AutoCloseable closeable}, then the behavior when either are
 * <i>asynchronously closed</i>, or the thread interrupted during the transfer,
 * is highly readable and appendable specific, and therefore not specified.

The only thing that worries me is that the @link is pointing form java.lang to java.io stuff, which I tried to prevent.

> 
>>  *
>>  * @since 18.3
>> 
> We're using "@since 10" for now, pending an outcome of the version string discussion.
> 
> -Alan