RFR: JDK-8262435: Clarify the behavior of a few inherited ZipInputStream methods

[Alan Bateman]

On Fri, 4 Nov 2022 18:13:23 GMT, Lance Andersen <lancea at openjdk.org> wrote:

> Please review the following PR which updates several of the ZipInputStream methods whose javadoc is inherited to clarify the methods  are acting on  the current ZIP Entry.
> 
> There are no changes in behavior.  The main description for the method's javadoc that has been copied has been clarified and the remaining doc is the same.

src/java.base/share/classes/java/util/zip/ZipInputStream.java line 222:

> 220:      * <p> The behavior for the case where the input stream is <i>asynchronously
> 221:      * closed</i>, or the thread interrupted during the read, is highly input
> 222:      * stream specific, and therefore not specified.

I'm not 100% sure about copying this paragraph from InputStream.readAllBytes because ZipInputStream is a specific InputStream implementation. I would be tempted to just drop it.

src/java.base/share/classes/java/util/zip/ZipInputStream.java line 263:

> 261:      * <p> The behavior for the case where the input stream is <i>asynchronously
> 262:      * closed</i>, or the thread interrupted during the read, is highly input
> 263:      * stream specific, and therefore not specified.

This is another case where we might drop a paragraph because it's there to allow for a wide range of input stream implementations.

src/java.base/share/classes/java/util/zip/ZipInputStream.java line 273:

> 271:      * @implNote
> 272:      * The number of bytes allocated to read data from this stream and return
> 273:      * the result is bounded by {@code 2*(long)len}, inclusive.

Maybe the implNote should just say that it calls super.readNBytes ?

src/java.base/share/classes/java/util/zip/ZipInputStream.java line 309:

> 307:      * <p> The behavior for the case where the input stream is <i>asynchronously
> 308:      * closed</i>, or the thread interrupted during the read, is highly input
> 309:      * stream specific, and therefore not specified.

Another paragraph that probably shouldn't be copied from InputStream.

src/java.base/share/classes/java/util/zip/ZipInputStream.java line 355:

> 353:      * invoked to read a single byte, and if it returns {@code -1}, then an
> 354:      * {@code EOFException} is thrown.  Any exception thrown by {@code skip()}
> 355:      * or {@code read()} will be propagated.

implSpec is usually for methods with a default or overrideable implementation. Yes, it's possible to extend ZipInputStream and override the skipNBytes method but it feels a bit too deep in the hierarchy to have this in the javadoc.

-------------

PR: https://git.openjdk.org/jdk/pull/10995