Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
8273513: Make java.io.FilterInputStream specification more precise ab… 
…out overrides

Reviewed-by: dfuchs, naoto
  • Loading branch information
Brian Burkhalter committed Sep 13, 2021
1 parent b4b1210 commit 6cf5079
Showing 1 changed file with 45 additions and 33 deletions.
78 changes: 45 additions & 33 deletions src/java.base/share/classes/java/io/FilterInputStream.java
View file
@@ -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
Expand All @@ -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
Expand Down Expand Up @@ -69,15 +65,16 @@ protected FilterInputStream(InputStream in) {
* {@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();
}
Expand All @@ -86,10 +83,11 @@ public int read() throws IOException {
* 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
Expand All @@ -102,6 +100,7 @@ public int read() throws IOException {
* @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);
}
Expand All @@ -111,7 +110,8 @@ public int read(byte[] b) throws IOException {
* 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.
*
Expand All @@ -128,6 +128,7 @@ public int read(byte[] b) throws IOException {
* @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);
}
Expand All @@ -138,13 +139,15 @@ public int read(byte[] b, int off, int len) throws IOException {
* 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);
}
Expand All @@ -155,26 +158,30 @@ public long skip(long n) throws IOException {
* 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();
}

/**
* 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();
}
Expand All @@ -187,14 +194,16 @@ public void close() throws IOException {
* 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
* the mark position becomes invalid.
* @see java.io.FilterInputStream#in
* @see java.io.FilterInputStream#reset()
*/
@Override
public synchronized void mark(int readlimit) {
in.mark(readlimit);
}
Expand All @@ -203,9 +212,6 @@ public synchronized void mark(int readlimit) {
* 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
Expand All @@ -215,20 +221,25 @@ public synchronized void mark(int readlimit) {
* 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();
}

/**
* 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;
Expand All @@ -237,6 +248,7 @@ public synchronized void reset() throws IOException {
* @see java.io.InputStream#mark(int)
* @see java.io.InputStream#reset()
*/
@Override
public boolean markSupported() {
return in.markSupported();
}
Expand Down

1 comment on commit 6cf5079

@openjdk-notifier
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review

Issues

Please sign in to comment.