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. -Patrick
