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 <[email protected]> wrote:
Hi Chris,
Am 05.12.2014 um 17:36 schrieb Chris Hegarty
<[email protected]>:
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
