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

[Jaikiran Pai]

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 210:

> 208:      * Reads all remaining bytes from the input stream for the current ZIP entry.
> 209:      * This method blocks until all remaining bytes have been read and end of
> 210:      * stream is detected, or an exception is thrown. This method does not close

Hello Lance, the part where it says that it reads the current ZIP entry sounds fine. However, this also states that it will wait until the end of stream is detected. Should we make it clearer by changing this to say `This method blocks until all remaining bytes of the entry have been read or an exception is thrown`?

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

> 229:      *
> 230:      * @throws OutOfMemoryError {@inheritDoc}
> 231:      *

I suspect we will also need to explicitly have a `@throws IOException` here.

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

> 240:      * Reads up to a specified number of bytes from the input stream
> 241:      * for the current ZIP entry. This
> 242:      * method blocks until the requested number of bytes has been read, end

Nit - some of these words could be moved to the previous line to make the line length consistent with other lines.

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

> 274:      * the result is bounded by {@code 2*(long)len}, inclusive.
> 275:      *
> 276:      *  @throws OutOfMemoryError {@inheritDoc}

There are a couple of other `@throws` in the `super` that I think we should inherit here.

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

> 317:      *
> 318:      * @throws NullPointerException {@inheritDoc}
> 319:      * @throws IndexOutOfBoundsException {@inheritDoc}

Missing `@throws` for `IOException`.

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

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