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

[Chris Hegarty]

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.