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
