Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Closed
wants to merge 3 commits into from
Closed

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

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
07dbe2f
8273513: Make java.io.FilterInputStream specification more precise ab…
bplb Sep 8, 2021
96f5ffc
8273513: Change key to select as suggested in CSR comment
bplb Sep 9, 2021
bf2896a
8273513: Remove an extra space
bplb Sep 10, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
76 changes: 44 additions & 32 deletions src/java.base/share/classes/java/io/FilterInputStream.java
View file
Open in desktop
@@ -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,7 +83,8 @@ 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
Copy link
Member

Choose a reason for hiding this comment

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

Preexisting: an extra space before "result."

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