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

[Chris Hegarty]

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 we are mostly in agreement on the latest patch Pavel sent out. 
Cut'n'past here, with some grammatical updates.

/**
  * Reads all remaining bytes from this input stream and writes them to
  * the given output stream.
  * <p>
  * There are no guarantees on the stream's state if an error occurs.
  * Even if this method returns normally you can't rely on previously
  * marked positions, or the contents of any internal buffers. That
  * said, this is a terminal operation. It is strongly recommended
  * that both streams are promptly closed after this method returns:
  * <pre>{@code
  *     try (InputStream is = ...; OutputStream os = ...;) {
  *         is.copyTo(os);
  *     } catch (IOException e) {
  *         ...
  *     }
  * }</pre>
  * <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.
  *
  * @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
  *
  * @since 1.9
  */
public long copyTo(OutputStream out) throws IOException { ... }


-Chris

[1] http://docs.oracle.com/javase/specs/jls/se8/html/jls-13.html


On 04/12/14 23:13, Pavel Rappo wrote:
> Patrick,
>
>> Should those methods also be on the FilterInput- and OutputStream?
>
> I'm not sure I'm following you. j.i.FilterInputStream will get the base version
> of InputStream.copyTo method for free as a child though it doesn't define it
> itself. Every class down the hierarchy starting from the j.i.InputStream will
> get InputStream.copyTo version unless it overrides it.
> To override it, it should of course have some rationale behind it. I believe we
> have found it for at least two widely used subclasses.
>
>> I'm not quit sure about the impact on may already existing customer code that had implemented such a method without declaring a IOException for example. In this case the existing code would may break? (as a comment of Alan Bateman earlier before)
>
> In the case you've mentioned everything should be just fine (technically) as
> overriding method has right to neither throw nor even declare any exceptions
> thrown by the parent method.
>
> I said *technically* because the sole fact of overriding doesn't guarantee the
> child's method has the same semantics as the parent's one.
>
> It seems to me that it’s not the only possible problematic thing here. We'll see.
>
> -Pavel
>