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 >
