JDK-8067661: transferTo proposal for Appendable

[Patrick Reinhart]

Hi Brian,

I integrated your changes into my current version which I will look into tomorrow with Alan at Devoxx. I think adding some implementation note on the default method implementation will be needed to review later on…

I also made an override on the CharBuffer, where we need to add a enhanced documentation for the specialties around the CharBuffer implementations (BufferOverflowException/ReadOnlyBufferException), where a review of some native english speakers would help :-)

-Patrick


> Am 07.11.2017 um 23:38 schrieb Brian Burkhalter <brian.burkhalter at oracle.com>:
> 
> I am a little late to this thread, but some alternative verbiage to consider is included below. This wording however diverges from that of [1] so if we want them to remain similar then it’s probably not worth it to change from what has been agreed upon already.
> 
> Thanks,
> 
> Brian
> 
> [1] https://docs.oracle.com/javase/9/docs/api/java/io/InputStream.html#transferTo-java.io.OutputStream- <https://docs.oracle.com/javase/9/docs/api/java/io/InputStream.html#transferTo-java.io.OutputStream->
> 
>   57      * Reads all characters from this source and writes the characters to
>   58      * the given appendable in the order that they are read. On return, the
>   59      * source of characters will be at its end.
> 
> Reads all characters from this source and appends them to a destination in
> the order in which they are read. On return, ...
> 
>   60      * <p>
>   61      * This method may block indefinitely reading from the readable, or
>   62      * writing to the appendable. Where this source or the appendable is
>   63      * {@link AutoCloseable closeable}, then the behavior when either are
>   64      * <i>asynchronously closed</i>, or the thread interrupted during the transfer,
>   65      * is highly readable and appendable specific, and therefore not specified.
> 
> This method may block indefinitely while reading from the source or writing to the destination.
> If the source or destination is {@link AutoCloseable closeable}, then the behavior when either
> is <i>asynchronously closed</i>, or the thread is interrupted during the transfer, is highly
> implementation-dependent and hence unspecified.
> 
>   66      * <p>
>   67      * If an I/O error occurs reading from the readable or writing to the
>   68      * appendable, then it may do so after some characters have been read or
>   69      * written. Consequently the readable may not be at end of its data and
>   70      * one, or both participants may be in an inconsistent state. That in mind
>   71      * all additional measures required by one or both participants in order to
>   72      * eventually free their internal resources have to be taken by the caller
>   73      * of this method.
> 
> If an I/O error occurs during the operation, then not all characters might have been transferred
> and the source or destination could be left in an inconsistent state. The caller of this method
> should therefore ensure in such a case that measures are taken to release any resources held
> by the source and destination.
> 
> On Nov 3, 2017, at 5:49 AM, Alan Bateman <Alan.Bateman at oracle.com <mailto:Alan.Bateman at oracle.com>> wrote:
> 
>> On 02/11/2017 19:55, Patrick Reinhart wrote:
>>> :
>>> If we are all happy with the API so far, I could start adding an initial implementation and test…
>>> 
>> I think the API looks fine so go ahead.
>