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.
