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

[Chris Hegarty]

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
>