stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

8262435: Clarify the behavior of a few inherited ZipInputStream methods

Browse Source 
Reviewed-by: alanb, bpb, jpai
This commit is contained in:
Lance Andersen 2022-11-15 16:44:14 +00:00
parent c042b8ede1
commit 6aef3a4a3d
1 changed files with 183 additions and 7 deletions

190
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