Library enhancement proposal for copying data from/to Reader/Writer InputStream/OutputStream

[Chris Hegarty]

For completeness, here is the finalized spec that we intend to submit 
for approval. Just some minor rewording and grammaticality amendments 
over the previous.

    /**
      * Reads all bytes from this input stream and writes the bytes to 
the given
      * output stream in the order that they are read.  On return, this 
input
      * stream will be at end of stream.
      * <p>
      * This method may block indefinitely reading from the input stream,
      * or writing to the output stream. The behavior for the case that the
      * input and/or output stream is <i>asynchronously closed</i>, or the
      * thread interrupted during the transfer, is highly input and 
output stream
      * specific, and therefore not specified.
      * <p>
      * If an I/O error occurs reading from the input stream or writing to
      * the output stream, then it may do so after some bytes have been 
read or
      * written. Consequently the input stream may not be at end of 
stream and
      * one, or both, streams may be in an inconsistent state. It is 
strongly
      * recommended that both streams be promptly closed if an I/O error 
occurs.
      *
      * @param  out the output stream, non-null
      * @return the number of bytes transferred
      * @throws IOException if an I/O error occurs when reading or writing
      * @throws NullPointerException  if {@code out} is {@code null}
      *
      * @since 1.9
      */
     public long transferTo(OutputStream out) throws IOException { ... }

-Chris.


On 05/12/14 18:29, Chris Hegarty wrote:
>
> On 5 Dec 2014, at 17:28, Patrick Reinhart <patrick at reini.net> wrote:
>
>> Hi Chris,
>>
>>> Am 05.12.2014 um 17:36 schrieb Chris Hegarty <chris.hegarty at oracle.com>:
>>>
>>> On 05/12/14 15:59, Alan Bateman wrote:
>>>> On 05/12/2014 15:38, Chris Hegarty wrote:
>>>>> The addition of a copyTo method to java.io.InputStream is binary
>>>>> compatible [1], but it may, in some cases, be source incompatible. I
>>>>> believe the benefits of this approach out weigh the potential source
>>>>> incompatibility, but it will be for the spec gods, the CCC, to have
>>>>> final say.
>>>>>
>>>>> Here is what I propose. Let's take just InputStream.copyTo and bring
>>>>> it, by itself, to a conclusion. And then revisit each of the
>>>>> additional useful/convenience methods on their own merit.
>>>> I think the approach is good. An alternative name to consider is
>>>> transferTo. For the javadoc then you can make it clear that the
>>>> InputStream is at EOF when the method completes. I don't think the
>>>> javadoc needs to say that the OutputStream should be closed promptly
>>>> (think "cat a b c > d").
>>>
>>> Right. Updated spec:
>>>
>>>     /**
>>>      * Reads all remaining bytes from this input stream and writes them to
>>>      * the given output stream.  On return, this input stream will be at end of
>>>      * stream.
>>>      * <p>
>>>      * This method may block indefinitely reading from the input stream,
>>>      * or writing to the output stream. The behavior for the case that the
>>>      * input and/or output stream is <i>asynchronously closed</i>, or the
>>>      * thread interrupted during the copy, is highly input and output stream
>>>      * specific, and therefore not specified.
>>>      * <p>
>>>      * If an I/O error occurs reading from the input stream or writing to
>>>      * the output stream, then it may do so after some bytes have been read or
>>>      * written. Consequently the input stream may not be at end of stream and
>>>      * may be in an inconsistent state. It is strongly recommended that the
>>>      * input stream be promptly closed if an I/O error occurs.
>>>      *
>>>      * @param  out         the output stream to write to, non-null
>>>      * @return             the number of bytes copied
>>>      * @throws IOException if an I/O error occurs when reading or writing
>>>      * @throws NullPointerException  if {@code out} is {@code null}
>>>      *
>>>      * @since 1.9
>>>      */
>>>     public long transferTo(OutputStream out) throws IOException { ... }
>>>
>>> -Chris.
>>
>> Looks good to me. The only thing I would change is the @return documentation to „the number of bytes transferred“ to be in sync with the method name.
>
> Agreed. Consider it changed.
>
> -Chris.
>
>> -Patrick
>>
>