Clarify the behavior of a few inherited ZipInputStream methods

Summary

Clarify several of the ZipInputStream methods javadoc to indicate that the methods work against the current Zip Entry.

Problem

The current javadoc does not specify that the ZipInputStream methods work against the current ZIP Entry

Solution

Update the javadoc to clarify that the methods work against the current ZIP entry

Specification

The following are the changes to ZipInputStream javadoc:

diff --git a/src/java.base/share/classes/java/util/zip/ZipInputStream.java b/src/java.base/share/classes/java/util/zip/ZipInputStream.java
index 5121fc6e597..fdd57acc7be 100644
--- a/src/java.base/share/classes/java/util/zip/ZipInputStream.java
+++ b/src/java.base/share/classes/java/util/zip/ZipInputStream.java
@@ -25,9 +25,10 @@

 package java.util.zip;

-import java.io.InputStream;
-import java.io.IOException;
 import java.io.EOFException;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.OutputStream;
 import java.io.PushbackInputStream;
 import java.nio.charset.Charset;
 import java.util.Objects;
@@ -172,13 +173,15 @@ public class ZipInputStream extends InflaterInputStream implements ZipConstants
     }

     /**
-     * Returns 0 after EOF has reached for the current entry data,
-     * otherwise always return 1.
+     * Returns 0 when end of stream is detected for the current ZIP entry or
+     * {@link #closeEntry()} has been called on the current ZIP entry, otherwise
+     * returns 1.
      * <p>
      * Programs should not count on this method to return the actual number
      * of bytes that could be read without blocking.
      *
-     * @return     1 before EOF and 0 after EOF has reached for current entry.
+     * @return 0 when end of stream is detected for the current ZIP entry or
+     * {@link #closeEntry()} has been called on the current ZIP entry, otherwise 1.
      * @throws     IOException  if an I/O error occurs.
      *
      */
@@ -192,7 +195,179 @@ public class ZipInputStream extends InflaterInputStream implements ZipConstants
     }

     /**
-     * Reads from the current ZIP entry into an array of bytes, returning the number of
+     * Reads the next byte of data from the input stream for the current
+     * ZIP entry. This method will block until enough input is available for
+     * decompression.
+     * @return the byte read, or -1 if the end of the stream is reached
+     * @throws    IOException if an I/O error has occurred
+     */
+    @Override
+    public int read() throws IOException {
+        return super.read();
+    }
+
+    /**
+     * Reads all remaining bytes from the input stream for the current ZIP entry.
+     * This method blocks until all remaining bytes have been read and end of
+     * stream is detected, or an exception is thrown. This method does not close
+     * the input stream.
+     *
+     * <p> When this stream reaches end of stream, further invocations of this
+     * method will return an empty byte array.
+     *
+     * <p> Note that this method is intended for simple cases where it is
+     * convenient to read all bytes into a byte array. It is not intended for
+     * reading input streams with large amounts of data.
+     *
+     * <p> If an I/O error occurs reading from the input stream, then it may do
+     * so after some, but not all, bytes have been read. Consequently, the input
+     * stream may not be at end of stream and may be in an inconsistent state.
+     * It is strongly recommended that the stream be promptly closed if an I/O
+     * error occurs.
+     *
+     * @throws OutOfMemoryError {@inheritDoc}
+     *
+     * @since 9
+     */
+    @Override
+    public byte[] readAllBytes() throws IOException {
+        return super.readAllBytes();
+    }
+
+    /**
+     * Reads up to a specified number of bytes from the input stream
+     * for the current ZIP entry. This method blocks until the requested number
+     * of bytes has been read, end of stream is detected, or an exception
+     * is thrown. This method does not close the input stream.
+     *
+     * <p> The length of the returned array equals the number of bytes read
+     * from the stream. If {@code len} is zero, then no bytes are read and
+     * an empty byte array is returned. Otherwise, up to {@code len} bytes
+     * are read from the stream. Fewer than {@code len} bytes may be read if
+     * end of stream is encountered.
+     *
+     * <p> When this stream reaches end of stream, further invocations of this
+     * method will return an empty byte array.
+     *
+     * <p> Note that this method is intended for simple cases where it is
+     * convenient to read the specified number of bytes into a byte array. The
+     * total amount of memory allocated by this method is proportional to the
+     * number of bytes read from the stream which is bounded by {@code len}.
+     * Therefore, the method may be safely called with very large values of
+     * {@code len} provided sufficient memory is available.
+     *
+     * <p> If an I/O error occurs reading from the input stream, then it may do
+     * so after some, but not all, bytes have been read. Consequently, the input
+     * stream may not be at end of stream and may be in an inconsistent state.
+     * It is strongly recommended that the stream be promptly closed if an I/O
+     * error occurs.
+     *
+     * @implNote
+     * This method calls {@code super.readNBytes(int len)}.
+     *
+     *  @throws OutOfMemoryError {@inheritDoc}
+     *
+     * @since 11
+     */
+    @Override
+    public byte[] readNBytes(int len) throws IOException {
+        return super.readNBytes(len);
+    }
+
+    /**
+     * Reads the requested number of bytes from the input stream into the given
+     * byte array for the current ZIP entry returning the number of
+     * inflated bytes.
+     * This method blocks until {@code len} bytes of input data have
+     * been read, end of stream is detected, or an exception is thrown. The
+     * number of bytes actually read, possibly zero, is returned. This method
+     * does not close the input stream.
+     *
+     * <p> In the case where end of stream is reached before {@code len} bytes
+     * have been read, then the actual number of bytes read will be returned.
+     * When this stream reaches end of stream, further invocations of this
+     * method will return zero.
+     *
+     * <p> If {@code len} is zero, then no bytes are read and {@code 0} is
+     * returned; otherwise, there is an attempt to read up to {@code len} bytes.
+     *
+     * <p> The first byte read is stored into element {@code b[off]}, the next
+     * one in to {@code b[off+1]}, and so on. The number of bytes read is, at
+     * most, equal to {@code len}. Let <i>k</i> be the number of bytes actually
+     * read; these bytes will be stored in elements {@code b[off]} through
+     * {@code b[off+}<i>k</i>{@code -1]}, leaving elements {@code b[off+}<i>k</i>

+     * {@code ]} through {@code b[off+len-1]} unaffected.
+     *
+     * <p> If an I/O error occurs reading from the input stream, then it may do
+     * so after some, but not all, bytes of {@code b} have been updated with
+     * data from the input stream. Consequently, the input stream and {@code b}
+     * may be in an inconsistent state. It is strongly recommended that the
+     * stream be promptly closed if an I/O error occurs.
+     *
+     * @throws NullPointerException {@inheritDoc}
+     * @throws IndexOutOfBoundsException {@inheritDoc}
+     *
+     * @since 9
+     */
+    @Override
+    public int readNBytes(byte[] b, int off, int len) throws IOException {
+        return super.readNBytes(b, off, len);
+    }
+
+    /**
+     * Skips over and discards exactly {@code n} bytes of data from this input
+     * stream for the current ZIP entry.
+     * If {@code n} is zero, then no bytes are skipped.
+     * If {@code n} is negative, then no bytes are skipped.
+     * Subclasses may handle the negative value differently.
+     *
+     * <p> This method blocks until the requested number of bytes has been
+     * skipped, end of file is reached, or an exception is thrown.
+     *
+     * <p> If end of stream is reached before the stream is at the desired
+     * position, then an {@code EOFException} is thrown.
+     *
+     * <p> If an I/O error occurs, then the input stream may be
+     * in an inconsistent state. It is strongly recommended that the
+     * stream be promptly closed if an I/O error occurs.
+     *
+     * @since 12
+     */
+    @Override
+    public void skipNBytes(long n) throws IOException {
+        super.skipNBytes(n);
+    }
+
+    /**
+     * Reads all bytes from this input stream for the current ZIP entry
+     * and writes the bytes to the given output stream in the order that they
+     * are read. On return, this input stream will be at end of stream.
+     * This method does not close either stream.
+     * <p>
+     * This method may block indefinitely reading from the input stream, or
+     * writing to the output stream. The behavior for the case where the input
+     * and/or output stream is <i>asynchronously closed</i>, or the thread
+     * interrupted during the transfer, 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
+     * one, or both, streams may be in an inconsistent state. It is strongly
+     * recommended that both streams be promptly closed if an I/O error occurs.
+     *
+     * @throws NullPointerException {@inheritDoc}
+     *
+     * @since 9
+     */
+    @Override
+    public long transferTo(OutputStream out) throws IOException {
+        return super.transferTo(out);
+    }
+
+    /**
+     * Reads the requested number of bytes from the input stream into the given
+     * byte array for the current ZIP entry returning the number of
      * inflated bytes. If {@code len} is not zero, the method blocks until some input is
      * available; otherwise, no bytes are read and {@code 0} is returned.
      * <p>
@@ -267,7 +442,8 @@ public class ZipInputStream extends InflaterInputStream implements ZipConstants
     }

     /**
-     * Skips specified number of bytes in the current ZIP entry.
+     * Skips over and discards {@code n} bytes of data from this input stream
+     * for the current ZIP entry.
      * @param n the number of bytes to skip
      * @return the actual number of bytes skipped
      * @throws    ZipException if a ZIP file error has occurred
 %