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

[Chris Hegarty]

Again, just for completeness...

Some feedback from Paul Sandoz, to be explicit about the "openness" of 
the streams on return. "Does not close either stream."

  /**
      * 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. Does not close either 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 08/12/14 11:48, Chris Hegarty wrote:
> 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
>>>
>>