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

[Patrick Reinhart]

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.

-Patrick