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

8273513: Make java.io.FilterInputStream specification more precise about overrides

Browse Source 
Reviewed-by: dfuchs, naoto
This commit is contained in:
Brian Burkhalter 2021-09-13 17:50:10 +00:00
parent b4b121018d
commit 6cf5079d8e
1 changed files with 45 additions and 33 deletions

78
src/java.base/share/classes/java/io/FilterInputStream.java

@ -1,5 +1,5 @@
/*
* Copyright (c) 1994, 2019, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1994, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -26,18 +26,14 @@
package java.io;
/**
* A {@code FilterInputStream} contains
* some other input stream, which it uses as
* its basic source of data, possibly transforming
* the data along the way or providing additional
* functionality. The class {@code FilterInputStream}
* itself simply overrides all methods of
* {@code InputStream} with versions that
* pass all requests to the contained input
* stream. Subclasses of {@code FilterInputStream}
* may further override some of these methods
* and may also provide additional methods
* and fields.
* A {@code FilterInputStream} wraps some other input stream, which it uses as
* its basic source of data, possibly transforming the data along the way or
* providing additional functionality. The class {@code FilterInputStream}
* itself simply overrides select methods of {@code InputStream} with versions
* that pass all requests to the wrapped input stream. Subclasses of
* {@code FilterInputStream} may of course override any methods declared or
* inherited by {@code FilterInputStream}, and may also provide additional
* fields and methods.
*
* @author Jonathan Payne
* @since 1.0
@ -69,15 +65,16 @@ public class FilterInputStream extends InputStream {
* {@code -1} is returned. This method blocks until input data
* is available, the end of the stream is detected, or an exception
* is thrown.
* <p>
* This method
* simply performs {@code in.read()} and returns the result.
*
* @implSpec
* This method simply performs {@code in.read()} and returns the result.
*
* @return the next byte of data, or {@code -1} if the end of the
* stream is reached.
* @throws IOException if an I/O error occurs.
* @see java.io.FilterInputStream#in
*/
@Override
public int read() throws IOException {
return in.read();
}
@ -86,10 +83,11 @@ public class FilterInputStream extends InputStream {
* Reads up to {@code b.length} bytes of data from this
* input stream into an array of bytes. This method blocks until some
* input is available.
* <p>
*
* @implSpec
* This method simply performs the call
* {@code read(b, 0, b.length)} and returns
* the result. It is important that it does
* the result. It is important that it does
* <i>not</i> do {@code in.read(b)} instead;
* certain subclasses of {@code FilterInputStream}
* depend on the implementation strategy actually
@ -102,6 +100,7 @@ public class FilterInputStream extends InputStream {
* @throws IOException if an I/O error occurs.
* @see java.io.FilterInputStream#read(byte[], int, int)
*/
@Override
public int read(byte[] b) throws IOException {
return read(b, 0, b.length);
}
@ -111,7 +110,8 @@ public class FilterInputStream extends InputStream {
* into an array of 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>
*
* @implSpec
* This method simply performs {@code in.read(b, off, len)}
* and returns the result.
*
@ -128,6 +128,7 @@ public class FilterInputStream extends InputStream {
* @throws IOException if an I/O error occurs.
* @see java.io.FilterInputStream#in
*/
@Override
public int read(byte[] b, int off, int len) throws IOException {
return in.read(b, off, len);
}
@ -138,13 +139,15 @@ public class FilterInputStream extends InputStream {
* reasons, end up skipping over some smaller number of bytes,
* possibly {@code 0}. The actual number of bytes skipped is
* returned.
* <p>
* This method simply performs {@code in.skip(n)}.
*
* @implSpec
* This method simply performs {@code in.skip(n)} and returns the result.
*
* @param n the number of bytes to be skipped.
* @return the actual number of bytes skipped.
* @throws IOException if {@code in.skip(n)} throws an IOException.
*/
@Override
public long skip(long n) throws IOException {
return in.skip(n);
}
@ -155,13 +158,15 @@ public class FilterInputStream extends InputStream {
* caller of a method for this input stream. The next caller might be
* the same thread or another thread. A single read or skip of this
* many bytes will not block, but may read or skip fewer bytes.
* <p>
* This method returns the result of {@link #in in}.available().
*
* @return an estimate of the number of bytes that can be read (or skipped
* over) from this input stream without blocking.
* @implSpec
* This method returns the result of {@code in.available()}.
*
* @return an estimate of the number of bytes that can be read (or
* skipped over) from this input stream without blocking.
* @throws IOException if an I/O error occurs.
*/
@Override
public int available() throws IOException {
return in.available();
}
@ -169,12 +174,14 @@ public class FilterInputStream extends InputStream {
/**
* Closes this input stream and releases any system resources
* associated with the stream.
* This
* method simply performs {@code in.close()}.
*
* @implSpec
* This method simply performs {@code in.close()}.
*
* @throws IOException if an I/O error occurs.
* @see java.io.FilterInputStream#in
*/
@Override
public void close() throws IOException {
in.close();
}
@ -187,7 +194,8 @@ public class FilterInputStream extends InputStream {
* The {@code readlimit} argument tells this input stream to
* allow that many bytes to be read before the mark position gets
* invalidated.
* <p>
*
* @implSpec
* This method simply performs {@code in.mark(readlimit)}.
*
* @param readlimit the maximum limit of bytes that can be read before
@ -195,6 +203,7 @@ public class FilterInputStream extends InputStream {
* @see java.io.FilterInputStream#in
* @see java.io.FilterInputStream#reset()
*/
@Override
public synchronized void mark(int readlimit) {
in.mark(readlimit);
}
@ -203,9 +212,6 @@ public class FilterInputStream extends InputStream {
* Repositions this stream to the position at the time the
* {@code mark} method was last called on this input stream.
* <p>
* This method
* simply performs {@code in.reset()}.
* <p>
* Stream marks are intended to be used in
* situations where you need to read ahead a little to see what's in
* the stream. Often this is most easily done by invoking some
@ -215,11 +221,15 @@ public class FilterInputStream extends InputStream {
* If this happens within readlimit bytes, it allows the outer
* code to reset the stream and try another parser.
*
* @implSpec
* This method simply performs {@code in.reset()}.
*
* @throws IOException if the stream has not been marked or if the
* mark has been invalidated.
* @see java.io.FilterInputStream#in
* @see java.io.FilterInputStream#mark(int)
*/
@Override
public synchronized void reset() throws IOException {
in.reset();
}
@ -227,8 +237,9 @@ public class FilterInputStream extends InputStream {
/**
* Tests if this input stream supports the {@code mark}
* and {@code reset} methods.
* This method
* simply performs {@code in.markSupported()}.
*
* @implSpec
* This method simply performs {@code in.markSupported()}.
*
* @return {@code true} if this stream type supports the
* {@code mark} and {@code reset} method;
@ -237,6 +248,7 @@ public class FilterInputStream extends InputStream {
* @see java.io.InputStream#mark(int)
* @see java.io.InputStream#reset()
*/
@Override
public boolean markSupported() {
return in.markSupported();
}