JDK-8067661: transferTo proposal for Appendable

[Brian Burkhalter]

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-

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