Details
Description
Summary
When expanding use of inheritDoc in InputStream and OutputSteam subclasses, also add implNote and implSpec tags where appropriate.
Problem
The InputStream and OutputSteam subclasses would benefit from better use of javadoc.
Solution
Improve the javadoc usage.
Specification
Proposed diff; includings non-specification updates.
diff --git a/src/java.base/share/classes/java/io/ByteArrayInputStream.java b/src/java.base/share/classes/java/io/ByteArrayInputStream.java
index a81d54a3b405..221e7666e48c 100644
--- a/src/java.base/share/classes/java/io/ByteArrayInputStream.java
+++ b/src/java.base/share/classes/java/io/ByteArrayInputStream.java
@@ -139,9 +139,9 @@ public ByteArrayInputStream(byte[] buf, int offset, int length) {
* This {@code read} method
* cannot block.
*
- * @return the next byte of data, or {@code -1} if the end of the
- * stream has been reached.
+ * @return {@inheritDoc}
*/
+ @Override
public synchronized int read() {
return (pos < count) ? (buf[pos++] & 0xff) : -1;
}
@@ -162,17 +162,14 @@ public synchronized int read() {
* <p>
* This {@code read} method cannot block.
*
- * @param b the buffer into which the data is read.
- * @param off the start offset in the destination array {@code b}
- * @param len the maximum number of bytes read.
- * @return the total number of bytes read into the buffer, or
- * {@code -1} if there is no more data because the end of
- * the stream has been reached.
- * @throws NullPointerException If {@code b} is {@code null}.
- * @throws IndexOutOfBoundsException If {@code off} is negative,
- * {@code len} is negative, or {@code len} is greater than
- * {@code b.length - off}
+ * @param b {@inheritDoc}
+ * @param off {@inheritDoc}
+ * @param len {@inheritDoc}
+ * @return {@inheritDoc}
+ * @throws NullPointerException {@inheritDoc}
+ * @throws IndexOutOfBoundsException {@inheritDoc}
*/
+ @Override
public synchronized int read(byte[] b, int off, int len) {
Objects.checkFromIndexSize(off, len, b.length);
@@ -192,17 +189,20 @@ public synchronized int read(byte[] b, int off, int len) {
return len;
}
+ @Override
public synchronized byte[] readAllBytes() {
byte[] result = Arrays.copyOfRange(buf, pos, count);
pos = count;
return result;
}
+ @Override
public int readNBytes(byte[] b, int off, int len) {
int n = read(b, off, len);
return n == -1 ? 0 : n;
}
+ @Override
public synchronized long transferTo(OutputStream out) throws IOException {
int len = count - pos;
out.write(buf, pos, len);
@@ -219,9 +219,10 @@ public synchronized long transferTo(OutputStream out) throws IOException {
* The value {@code k} is added into {@code pos}
* and {@code k} is returned.
*
- * @param n the number of bytes to be skipped.
+ * @param n {@inheritDoc}
* @return the actual number of bytes skipped.
*/
+ @Override
public synchronized long skip(long n) {
long k = count - pos;
if (n < k) {
@@ -242,17 +243,20 @@ public synchronized long skip(long n) {
* @return the number of remaining bytes that can be read (or skipped
* over) from this input stream without blocking.
*/
+ @Override
public synchronized int available() {
return count - pos;
}
/**
- * Tests if this {@code InputStream} supports mark/reset. The
- * {@code markSupported} method of {@code ByteArrayInputStream}
+ * Tests if this {@code InputStream} supports mark/reset.
+ * @implSpec
+ * The {@code markSupported} method of {@code ByteArrayInputStream}
* always returns {@code true}.
- *
+ * @return true
* @since 1.1
*/
+ @Override
public boolean markSupported() {
return true;
}
@@ -272,6 +276,7 @@ public boolean markSupported() {
*
* @since 1.1
*/
+ @Override
public void mark(int readAheadLimit) {
mark = pos;
}
@@ -281,6 +286,7 @@ public void mark(int readAheadLimit) {
* is 0 unless another position was marked or an offset was specified
* in the constructor.
*/
+ @Override
public synchronized void reset() {
pos = mark;
}
@@ -290,7 +296,7 @@ public synchronized void reset() {
* this class can be called after the stream has been closed without
* generating an {@code IOException}.
*/
+ @Override
public void close() throws IOException {
}
-
}
diff --git a/src/java.base/share/classes/java/io/ByteArrayOutputStream.java b/src/java.base/share/classes/java/io/ByteArrayOutputStream.java
index 09e79934bfa9..f4660cb59e14 100644
--- a/src/java.base/share/classes/java/io/ByteArrayOutputStream.java
+++ b/src/java.base/share/classes/java/io/ByteArrayOutputStream.java
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1994, 2021, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1994, 2022, 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
@@ -107,6 +107,7 @@ private void ensureCapacity(int minCapacity) {
*
* @param b the byte to be written.
*/
+ @Override
public synchronized void write(int b) {
ensureCapacity(count + 1);
buf[count] = (byte) b;
@@ -117,14 +118,15 @@ public synchronized void write(int b) {
* Writes {@code len} bytes from the specified byte array
* starting at offset {@code off} to this {@code ByteArrayOutputStream}.
*
- * @param b the data.
- * @param off the start offset in the data.
- * @param len the number of bytes to write.
+ * @param b {@inheritDoc}
+ * @param off {@inheritDoc}
+ * @param len {@inheritDoc}
* @throws NullPointerException if {@code b} is {@code null}.
* @throws IndexOutOfBoundsException if {@code off} is negative,
* {@code len} is negative, or {@code len} is greater than
* {@code b.length - off}
*/
+ @Override
public synchronized void write(byte[] b, int off, int len) {
Objects.checkFromIndexSize(off, len, b.length);
ensureCapacity(count + len);
@@ -212,6 +214,7 @@ public synchronized int size() {
* @return String decoded from the buffer's contents.
* @since 1.1
*/
+ @Override
public synchronized String toString() {
return new String(buf, 0, count);
}
@@ -306,6 +309,7 @@ public synchronized String toString(int hibyte) {
* this class can be called after the stream has been closed without
* generating an {@code IOException}.
*/
+ @Override
public void close() throws IOException {
}
diff --git a/src/java.base/share/classes/java/io/FileInputStream.java b/src/java.base/share/classes/java/io/FileInputStream.java
index 40cc83a09f52..ba1d06a1f1bf 100644
--- a/src/java.base/share/classes/java/io/FileInputStream.java
+++ b/src/java.base/share/classes/java/io/FileInputStream.java
@@ -228,8 +228,9 @@ private void open(String name) throws FileNotFoundException {
*
* @return the next byte of data, or {@code -1} if the end of the
* file is reached.
- * @throws IOException if an I/O error occurs.
+ * @throws IOException {@inheritDoc}
*/
+ @Override
public int read() throws IOException {
long comp = Blocker.begin();
try {
@@ -255,12 +256,13 @@ public int read() throws IOException {
* stream into an array of bytes. This method blocks until some input
* is available.
*
- * @param b the buffer into which the data is read.
+ * @param b {@inheritDoc}
* @return the total number of bytes read into the buffer, or
* {@code -1} if there is no more data because the end of
* the file has been reached.
* @throws IOException if an I/O error occurs.
*/
+ @Override
public int read(byte[] b) throws IOException {
long comp = Blocker.begin();
try {
@@ -276,18 +278,15 @@ public int read(byte[] b) throws IOException {
* blocks until some input is available; otherwise, no
* bytes are read and {@code 0} is returned.
*
- * @param b the buffer into which the data is read.
- * @param off the start offset in the destination array {@code b}
- * @param len the maximum number of bytes read.
- * @return the total number of bytes read into the buffer, or
- * {@code -1} if there is no more data because the end of
- * the file has been reached.
- * @throws NullPointerException If {@code b} is {@code null}.
- * @throws IndexOutOfBoundsException If {@code off} is negative,
- * {@code len} is negative, or {@code len} is greater than
- * {@code b.length - off}
+ * @param b {@inheritDoc}
+ * @param off {@inheritDoc}
+ * @param len {@inheritDoc}
+ * @return {@inheritDoc}
+ * @throws NullPointerException {@inheritDoc}
+ * @throws IndexOutOfBoundsException {@inheritDoc}
* @throws IOException if an I/O error occurs.
*/
+ @Override
public int read(byte[] b, int off, int len) throws IOException {
long comp = Blocker.begin();
try {
@@ -297,6 +296,7 @@ public int read(byte[] b, int off, int len) throws IOException {
}
}
+ @Override
public byte[] readAllBytes() throws IOException {
long length = length();
long position = position();
@@ -339,6 +339,7 @@ public byte[] readAllBytes() throws IOException {
return (capacity == nread) ? buf : Arrays.copyOf(buf, nread);
}
+ @Override
public byte[] readNBytes(int len) throws IOException {
if (len < 0)
throw new IllegalArgumentException("len < 0");
@@ -378,6 +379,7 @@ public byte[] readNBytes(int len) throws IOException {
/**
* {@inheritDoc}
*/
+ @Override
public long transferTo(OutputStream out) throws IOException {
long transferred = 0L;
if (out instanceof FileOutputStream fos) {
@@ -432,11 +434,12 @@ private long position() throws IOException {
* backing file. Attempting to read from the stream after skipping past
* the end will result in -1 indicating the end of the file.
*
- * @param n the number of bytes to be skipped.
+ * @param n {@inheritDoc}
* @return the actual number of bytes skipped.
* @throws IOException if n is negative, if the stream does not
* support seek, or if an I/O error occurs.
*/
+ @Override
public long skip(long n) throws IOException {
long comp = Blocker.begin();
try {
@@ -465,6 +468,7 @@ public long skip(long n) throws IOException {
* @throws IOException if this file input stream has been closed by calling
* {@code close} or an I/O error occurs.
*/
+ @Override
public int available() throws IOException {
long comp = Blocker.begin();
try {
@@ -491,10 +495,11 @@ public int available() throws IOException {
* If cleanup of native resources is needed, other mechanisms such as
* {@linkplain java.lang.ref.Cleaner} should be used.
*
- * @throws IOException if an I/O error occurs.
+ * @throws IOException {@inheritDoc}
*
* @revised 1.4
*/
+ @Override
public void close() throws IOException {
if (closed) {
return;
diff --git a/src/java.base/share/classes/java/io/FileOutputStream.java b/src/java.base/share/classes/java/io/FileOutputStream.java
index 04bccfbb2b6d..29665e570689 100644
--- a/src/java.base/share/classes/java/io/FileOutputStream.java
+++ b/src/java.base/share/classes/java/io/FileOutputStream.java
@@ -314,6 +314,7 @@ private void open(String name, boolean append) throws FileNotFoundException {
* @param b the byte to be written.
* @throws IOException if an I/O error occurs.
*/
+ @Override
public void write(int b) throws IOException {
boolean append = fdAccess.getAppend(fd);
long comp = Blocker.begin();
@@ -340,9 +341,10 @@ private native void writeBytes(byte[] b, int off, int len, boolean append)
* Writes {@code b.length} bytes from the specified byte array
* to this file output stream.
*
- * @param b the data.
- * @throws IOException if an I/O error occurs.
+ * @param b {@inheritDoc}
+ * @throws IOException {@inheritDoc}
*/
+ @Override
public void write(byte[] b) throws IOException {
boolean append = fdAccess.getAppend(fd);
long comp = Blocker.begin();
@@ -357,11 +359,12 @@ public void write(byte[] b) throws IOException {
- Writes
{@code len}
bytes from the specified byte array
- starting at offset
{@code off}
to this file output stream.
*
- * @param b the data.
- * @param off the start offset in the data.
- * @param len the number of bytes to write.
+ * @param b
{@inheritDoc}
+ * @param off {@inheritDoc}
+ * @param len
{@inheritDoc}
- @throws IOException if an I/O error occurs.
*/
+ @Override
public void write(byte[]
b, int off, int len) throws IOException {
boolean append = fdAccess.getAppend(fd);
long comp = Blocker.begin();
@@ -392,6 +395,7 @@ public void write(byte[] b, int off, int len) throws IOException {
*
* @revised 1.4
*/
+ @Override
public void close() throws IOException {
if (closed) {
return;
diff --git a/src/java.base/share/classes/java/io/FilterInputStream.java b/src/java.base/share/classes/java/io/FilterInputStream.java
index c6840c907e32..083dab333598 100644
--- a/src/java.base/share/classes/java/io/FilterInputStream.java
+++ b/src/java.base/share/classes/java/io/FilterInputStream.java
@@ -58,20 +58,12 @@ protected FilterInputStream(InputStream in) {
}
/**
- * Reads the next byte of data from this input stream. The value
- * byte is returned as an {@code int} in the range
- * {@code 0} to {@code 255}. If no byte is available
- * because the end of the stream has been reached, the value
- * {@code -1} is returned. This method blocks until input data
- * is available, the end of the stream is detected, or an exception
- * is thrown.
- *
+ * {@inheritDoc}
* @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.
+ * @return {@inheritDoc}
+ * @throws IOException {@inheritDoc}
* @see java.io.FilterInputStream#in
*/
@Override
@@ -93,10 +85,8 @@ public int read() throws IOException {
* depend on the implementation strategy actually
* used.
*
- * @param b the buffer into which the data is read.
- * @return the total number of bytes read into the buffer, or
- * {@code -1} if there is no more data because the end of
- * the stream has been reached.
+ * @param b {@inheritDoc}
+ * @return {@inheritDoc}
* @throws IOException if an I/O error occurs.
* @see java.io.FilterInputStream#read(byte[], int, int)
*/
@@ -115,16 +105,12 @@ public int read(byte[] b) throws IOException {
* This method simply performs {@code in.read(b, off, len)}
* and returns the result.
*
- * @param b the buffer into which the data is read.
- * @param off the start offset in the destination array {@code b}
- * @param len the maximum number of bytes read.
- * @return the total number of bytes read into the buffer, or
- * {@code -1} if there is no more data because the end of
- * the stream has been reached.
- * @throws NullPointerException If {@code b} is {@code null}.
- * @throws IndexOutOfBoundsException If {@code off} is negative,
- * {@code len} is negative, or {@code len} is greater than
- * {@code b.length - off}
+ * @param b {@inheritDoc}
+ * @param off {@inheritDoc}
+ * @param len {@inheritDoc}
+ * @return {@inheritDoc}
+ * @throws NullPointerException {@inheritDoc}
+ * @throws IndexOutOfBoundsException {@inheritDoc}
* @throws IOException if an I/O error occurs.
* @see java.io.FilterInputStream#in
*/
@@ -143,7 +129,7 @@ public int read(byte[] b, int off, int len) throws IOException {
* @implSpec
* This method simply performs {@code in.skip(n)} and returns the result.
*
- * @param n the number of bytes to be skipped.
+ * @param n {@inheritDoc}
* @return the actual number of bytes skipped.
* @throws IOException if {@code in.skip(n)} throws an IOException.
*/
@@ -164,7 +150,7 @@ public long skip(long n) throws IOException {
*
* @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.
+ * @throws IOException {@inheritDoc}
*/
@Override
public int available() throws IOException {
@@ -172,13 +158,11 @@ public int available() throws IOException {
}
/**
- * Closes this input stream and releases any system resources
- * associated with the stream.
- *
+ * {@inheritDoc}
* @implSpec
* This method simply performs {@code in.close()}.
*
- * @throws IOException if an I/O error occurs.
+ * @throws IOException {@inheritDoc}
* @see java.io.FilterInputStream#in
*/
@Override
@@ -198,8 +182,7 @@ public void close() throws IOException {
* @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.
+ * @param readlimit {@inheritDoc}
* @see java.io.FilterInputStream#in
* @see java.io.FilterInputStream#reset()
*/
@@ -224,8 +207,7 @@ public void mark(int readlimit) {
* @implSpec
* This method simply performs {@code in.reset()}.
*
- * @throws IOException if the stream has not been marked or if the
- * mark has been invalidated.
+ * @throws IOException {@inheritDoc}
* @see java.io.FilterInputStream#in
* @see java.io.FilterInputStream#mark(int)
*/
diff --git a/src/java.base/share/classes/java/io/FilterOutputStream.java b/src/java.base/share/classes/java/io/FilterOutputStream.java
index 93d76d39483e..ca8604936c5e 100644
--- a/src/java.base/share/classes/java/io/FilterOutputStream.java
+++ b/src/java.base/share/classes/java/io/FilterOutputStream.java
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1994, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1994, 2022, 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
@@ -79,7 +79,7 @@ public FilterOutputStream(OutputStream out) {
* <p>
* Implements the abstract {@code write} method of {@code OutputStream}.
*
- * @param b the {@code byte}.
+ * @param b {@inheritDoc}
* @throws IOException if an I/O error occurs.
*/
@Override
@@ -89,18 +89,18 @@ public void write(int b) throws IOException {
/**
* Writes {@code b.length} bytes to this output stream.
- * <p>
+ * @implSpec
* The {@code write} method of {@code FilterOutputStream}
* calls its {@code write} method of three arguments with the
* arguments {@code b}, {@code 0}, and
* {@code b.length}.
- * <p>
- * Note that this method does not call the one-argument
+ * @implNote
+ * Note that this method does <em>not</em> call the one-argument
* {@code write} method of its underlying output stream with
* the single argument {@code b}.
*
* @param b the data to be written.
- * @throws IOException if an I/O error occurs.
+ * @throws IOException {@inheritDoc}
* @see java.io.FilterOutputStream#write(byte[], int, int)
*/
@Override
@@ -112,19 +112,19 @@ public void write(byte[] b) throws IOException {
* Writes {@code len} bytes from the specified
* {@code byte} array starting at offset {@code off} to
* this output stream.
- * <p>
+ * @implSpec
* The {@code write} method of {@code FilterOutputStream}
* calls the {@code write} method of one argument on each
* {@code byte} to output.
- * <p>
+ * @implNote
* Note that this method does not call the {@code write} method
* of its underlying output stream with the same arguments. Subclasses
* of {@code FilterOutputStream} should provide a more efficient
* implementation of this method.
*
- * @param b the data.
- * @param off the start offset in the data.
- * @param len the number of bytes to write.
+ * @param b {@inheritDoc}
+ * @param off {@inheritDoc}
+ * @param len {@inheritDoc}
* @throws IOException if an I/O error occurs.
* @see java.io.FilterOutputStream#write(int)
*/
@@ -141,11 +141,11 @@ public void write(byte[] b, int off, int len) throws IOException {
/**
* Flushes this output stream and forces any buffered output bytes
* to be written out to the stream.
- * <p>
+ * @implSpec
* The {@code flush} method of {@code FilterOutputStream}
* calls the {@code flush} method of its underlying output stream.
*
- * @throws IOException if an I/O error occurs.
+ * @throws IOException {@inheritDoc}
* @see java.io.FilterOutputStream#out
*/
@Override
@@ -156,7 +156,7 @@ public void flush() throws IOException {
/**
* Closes this output stream and releases any system resources
* associated with the stream.
- * <p>
+ * @implSpec
* When not already closed, the {@code close} method of {@code
* FilterOutputStream} calls its {@code flush} method, and then
* calls the {@code close} method of its underlying output stream.
diff --git a/src/java.base/share/classes/java/io/InputStream.java b/src/java.base/share/classes/java/io/InputStream.java
index 97e76b27878d..5848c51127fd 100644
--- a/src/java.base/share/classes/java/io/InputStream.java
+++ b/src/java.base/share/classes/java/io/InputStream.java
@@ -742,7 +742,10 @@ public void reset() throws IOException {
* Tests if this input stream supports the {@code mark} and
* {@code reset} methods. Whether or not {@code mark} and
* {@code reset} are supported is an invariant property of a
- * particular input stream instance. The {@code markSupported} method
+ * particular input stream instance.
+ *
+ * @implSpec
+ * The {@code markSupported} method
* of {@code InputStream} returns {@code false}.
*
* @return {@code true} if this stream instance supports the mark
diff --git a/src/java.base/share/classes/java/io/ObjectInputStream.java b/src/java.base/share/classes/java/io/ObjectInputStream.java
index 319981e864b0..6b1f8bddbd73 100644
--- a/src/java.base/share/classes/java/io/ObjectInputStream.java
+++ b/src/java.base/share/classes/java/io/ObjectInputStream.java
@@ -1017,8 +1017,9 @@ protected ObjectStreamClass readClassDescriptor()
* Reads a byte of data. This method will block if no input is available.
*
* @return the byte read, or -1 if the end of the stream is reached.
- * @throws IOException If an I/O error has occurred.
+ * @throws IOException {@inheritDoc}
*/
+ @Override
public int read() throws IOException {
return bin.read();
}
@@ -1041,6 +1042,7 @@ public int read() throws IOException {
* @throws IOException If an I/O error has occurred.
* @see java.io.DataInputStream#readFully(byte[],int,int)
*/
+ @Override
public int read(byte[] buf, int off, int len) throws IOException {
if (buf == null) {
throw new NullPointerException();
@@ -1056,16 +1058,17 @@ public int read(byte[] buf, int off, int len) throws IOException {
* @throws IOException if there are I/O errors while reading from the
* underlying {@code InputStream}
*/
+ @Override
public int available() throws IOException {
return bin.available();
}
/**
- * Closes the input stream. Must be called to release any resources
- * associated with the stream.
+ * {@inheritDoc}
*
- * @throws IOException If an I/O error has occurred.
+ * @throws IOException {@inheritDoc}
*/
+ @Override
public void close() throws IOException {
/*
* Even if stream already closed, propagate redundant close to
@@ -1225,6 +1228,7 @@ public void readFully(byte[] buf, int off, int len) throws IOException {
* @return the actual number of bytes skipped.
* @throws IOException If an I/O error has occurred.
*/
+ @Override
public int skipBytes(int len) throws IOException {
return bin.skipBytes(len);
}
diff --git a/src/java.base/share/classes/java/io/ObjectOutputStream.java b/src/java.base/share/classes/java/io/ObjectOutputStream.java
index 1ac6f60614f1..7997dfc3afa4 100644
--- a/src/java.base/share/classes/java/io/ObjectOutputStream.java
+++ b/src/java.base/share/classes/java/io/ObjectOutputStream.java
@@ -689,6 +689,7 @@ protected void writeClassDescriptor(ObjectStreamClass desc)
* @param val the byte to be written to the stream
* @throws IOException If an I/O error has occurred.
*/
+ @Override
public void write(int val) throws IOException {
bout.write(val);
}
@@ -700,6 +701,7 @@ public void write(int val) throws IOException {
* @param buf the data to be written
* @throws IOException If an I/O error has occurred.
*/
+ @Override
public void write(byte[] buf) throws IOException {
bout.write(buf, 0, buf.length, false);
}
@@ -710,8 +712,9 @@ public void write(byte[] buf) throws IOException {
- @param buf the data to be written
- @param off the start offset in the data
- @param len the number of bytes that are written
- * @throws IOException If an I/O error has occurred.
+ * @throws IOException
{@inheritDoc}
*/
+ @Override
public void write(byte[]
buf, int off, int len) throws IOException {
if (buf == null) {
throw new NullPointerException();
@@ -724,8 +727,9 @@ public void write(byte[] buf, int off, int len) throws IOException {
* Flushes the stream. This will write any buffered output bytes and flush
* through to the underlying stream.
*
- * @throws IOException If an I/O error has occurred.
+ * @throws IOException {@inheritDoc}
*/
+ @Override
public void flush() throws IOException {
bout.flush();
}
@@ -747,6 +751,7 @@ protected void drain() throws IOException {
*
* @throws IOException If an I/O error has occurred.
*/
+ @Override
public void close() throws IOException {
flush();
clear();
diff --git a/src/java.base/share/classes/java/io/PipedInputStream.java b/src/java.base/share/classes/java/io/PipedInputStream.java
index 0d733fa4c748..68b5b586d882 100644
--- a/src/java.base/share/classes/java/io/PipedInputStream.java
+++ b/src/java.base/share/classes/java/io/PipedInputStream.java
@@ -295,13 +295,13 @@ synchronized void receivedLast() {
* This method blocks until input data is available, the end of the
* stream is detected, or an exception is thrown.
*
- * @return the next byte of data, or {@code -1} if the end of the
- * stream is reached.
+ * @return {@inheritDoc}
* @throws IOException if the pipe is
* {@link #connect(java.io.PipedOutputStream) unconnected},
* <a href="#BROKEN"> {@code broken}</a>, closed,
* or if an I/O error occurs.
*/
+ @Override
public synchronized int read() throws IOException {
if (!connected) {
throw new IOException("Pipe not connected");
@@ -352,20 +352,17 @@ public synchronized int read() throws IOException {
* available, end of the stream has been detected, or an exception is
* thrown.
*
- * @param b the buffer into which the data is read.
- * @param off the start offset in the destination array {@code b}
- * @param len the maximum number of bytes read.
- * @return the total number of bytes read into the buffer, or
- * {@code -1} if there is no more data because the end of
- * the stream has been reached.
- * @throws NullPointerException If {@code b} is {@code null}.
- * @throws IndexOutOfBoundsException If {@code off} is negative,
- * {@code len} is negative, or {@code len} is greater than
- * {@code b.length - off}
+ * @param b {@inheritDoc}
+ * @param off {@inheritDoc}
+ * @param len {@inheritDoc}
+ * @return {@inheritDoc}
+ * @throws NullPointerException {@inheritDoc}
+ * @throws IndexOutOfBoundsException {@inheritDoc}
* @throws IOException if the pipe is <a href="#BROKEN"> {@code broken}</a>,
* {@link #connect(java.io.PipedOutputStream) unconnected},
* closed, or if an I/O error occurs.
*/
+ @Override
public synchronized int read(byte[] b, int off, int len) throws IOException {
if (b == null) {
throw new NullPointerException();
@@ -422,9 +419,10 @@ public synchronized int read(byte[] b, int off, int len) throws IOException {
* is {@link #connect(java.io.PipedOutputStream) unconnected}, or
* <a href="#BROKEN"> {@code broken}</a>.
*
- * @throws IOException if an I/O error occurs.
+ * @throws IOException {@inheritDoc}
* @since 1.0.2
*/
+ @Override
public synchronized int available() throws IOException {
if(in < 0)
return 0;
@@ -437,11 +435,11 @@ else if (in > out)
}
/**
- * Closes this piped input stream and releases any system resources
- * associated with the stream.
+ * {@inheritDoc}
*
- * @throws IOException if an I/O error occurs.
+ * @throws IOException {@inheritDoc}
*/
+ @Override
public void close() throws IOException {
closedByReader = true;
synchronized (this) {
diff --git a/src/java.base/share/classes/java/io/PipedOutputStream.java b/src/java.base/share/classes/java/io/PipedOutputStream.java
index 67c3610a5331..3e80a42477f2 100644
--- a/src/java.base/share/classes/java/io/PipedOutputStream.java
+++ b/src/java.base/share/classes/java/io/PipedOutputStream.java
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1995, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1995, 2022, 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
@@ -114,6 +114,7 @@ public synchronized void connect(PipedInputStream snk) throws IOException {
* {@link #connect(java.io.PipedInputStream) unconnected},
* closed, or if an I/O error occurs.
*/
+ @Override
public void write(int b) throws IOException {
var sink = this.sink;
if (sink == null) {
@@ -128,13 +129,14 @@ public void write(int b) throws IOException {
* This method blocks until all the bytes are written to the output
* stream.
*
- * @param b the data.
- * @param off the start offset in the data.
- * @param len the number of bytes to write.
+ * @param b {@inheritDoc}
+ * @param off {@inheritDoc}
+ * @param len {@inheritDoc}
* @throws IOException if the pipe is <a href=#BROKEN> broken</a>,
* {@link #connect(java.io.PipedInputStream) unconnected},
* closed, or if an I/O error occurs.
*/
+ @Override
public void write(byte[] b, int off, int len) throws IOException {
var sink = this.sink;
if (sink == null) {
@@ -155,8 +157,9 @@ public void write(byte[] b, int off, int len) throws IOException {
* to be written out.
* This will notify any readers that bytes are waiting in the pipe.
*
- * @throws IOException if an I/O error occurs.
+ * @throws IOException {@inheritDoc}
*/
+ @Override
public synchronized void flush() throws IOException {
if (sink != null) {
synchronized (sink) {
@@ -170,8 +173,9 @@ public synchronized void flush() throws IOException {
* associated with this stream. This stream may no longer be used for
* writing bytes.
*
- * @throws IOException if an I/O error occurs.
+ * @throws IOException {@inheritDoc}
*/
+ @Override
public void close() throws IOException {
var sink = this.sink;
if (sink != null) {
diff --git a/src/java.base/share/classes/java/io/SequenceInputStream.java b/src/java.base/share/classes/java/io/SequenceInputStream.java
index a656618b088c..e1b7f616188d 100644
--- a/src/java.base/share/classes/java/io/SequenceInputStream.java
+++ b/src/java.base/share/classes/java/io/SequenceInputStream.java
@@ -121,10 +121,11 @@ private void peekNextStream() {
* skipped over) from the current underlying input stream
* without blocking or {@code 0} if this input stream
* has been closed by invoking its {@link #close()} method
- * @throws IOException if an I/O error occurs.
+ * @throws IOException {@inheritDoc}
*
* @since 1.1
*/
+ @Override
public int available() throws IOException {
if (in == null) {
return 0; // no way to signal EOF from available()
@@ -133,12 +134,7 @@ public int available() throws IOException {
}
/**
- * Reads the next byte of data from this input stream. The byte is
- * returned as an {@code int} in the range {@code 0} to
- * {@code 255}. If no byte is available because the end of the
- * stream has been reached, the value {@code -1} is returned.
- * This method blocks until input data is available, the end of the
- * stream is detected, or an exception is thrown.
+ * {@inheritDoc}
* <p>
* This method
* tries to read one character from the current substream. If it
@@ -146,10 +142,10 @@ public int available() throws IOException {
* method of the current substream and begins reading from the next
* substream.
*
- * @return the next byte of data, or {@code -1} if the end of the
- * stream is reached.
+ * @return {@inheritDoc}
* @throws IOException if an I/O error occurs.
*/
+ @Override
public int read() throws IOException {
while (in != null) {
int c = in.read();
@@ -189,6 +185,7 @@ public int read() throws IOException {
* greater than {@code b.length - off}
* @throws IOException if an I/O error occurs.
*/
+ @Override
public int read(byte[] b, int off, int len) throws IOException {
if (in == null) {
return -1;
@@ -210,8 +207,7 @@ public int read(byte[] b, int off, int len) throws IOException {
}
/**
- * Closes this input stream and releases any system resources
- * associated with the stream.
+ * {@inheritDoc}
* A closed {@code SequenceInputStream}
* cannot perform input operations and cannot
* be reopened.
@@ -221,8 +217,9 @@ public int read(byte[] b, int off, int len) throws IOException {
* are requested from the enumeration and closed
* before the {@code close} method returns.
*
- * @throws IOException if an I/O error occurs.
+ * @throws IOException {@inheritDoc}
*/
+ @Override
public void close() throws IOException {
IOException ioe = null;
while (in != null) {
diff --git a/src/java.base/share/classes/java/io/StringBufferInputStream.java b/src/java.base/share/classes/java/io/StringBufferInputStream.java
index 99bacae0729e..f885636215cc 100644
--- a/src/java.base/share/classes/java/io/StringBufferInputStream.java
+++ b/src/java.base/share/classes/java/io/StringBufferInputStream.java
@@ -79,14 +79,15 @@ public StringBufferInputStream(String s) {
* {@code 0} to {@code 255}. If no byte is available
* because the end of the stream has been reached, the value
* {@code -1} is returned.
- * <p>
+ *
+ * @implSpec
* The {@code read} method of
* {@code StringBufferInputStream} cannot block. It returns the
* low eight bits of the next character in this input stream's buffer.
*
- * @return the next byte of data, or {@code -1} if the end of the
- * stream is reached.
+ * @return {@inheritDoc}
*/
+ @Override
public synchronized int read() {
return (pos < count) ? (buffer.charAt(pos++) & 0xFF) : -1;
}
@@ -94,19 +95,18 @@ public synchronized int read() {
/**
* Reads up to {@code len} bytes of data from this input stream
* into an array of bytes.
- * <p>
+ * @implSpec
* The {@code read} method of
* {@code StringBufferInputStream} cannot block. It copies the
* low eight bits from the characters in this input stream's buffer into
* the byte array argument.
*
- * @param b the buffer into which the data is read.
- * @param off the start offset of the data.
- * @param len the maximum number of bytes read.
- * @return the total number of bytes read into the buffer, or
- * {@code -1} if there is no more data because the end of
- * the stream has been reached.
+ * @param b {@inheritDoc}
+ * @param off {@inheritDoc}
+ * @param len {@inheritDoc}
+ * @return {@inheritDoc}
*/
+ @Override
@SuppressWarnings("deprecation")
public synchronized int read(byte[] b, int off, int len) {
if (b == null) {
@@ -135,9 +135,10 @@ public synchronized int read(byte[] b, int off, int len) {
* Skips {@code n} bytes of input from this input stream. Fewer
* bytes might be skipped if the end of the input stream is reached.
*
- * @param n the number of bytes to be skipped.
+ * @param n {@inheritDoc}
* @return the actual number of bytes skipped.
*/
+ @Override
public synchronized long skip(long n) {
if (n < 0) {
return 0;
@@ -156,6 +157,7 @@ public synchronized long skip(long n) {
* @return the value of {@code count - pos}, which is the
* number of bytes remaining to be read from the input buffer.
*/
+ @Override
public synchronized int available() {
return count - pos;
}
@@ -164,6 +166,7 @@ public synchronized int available() {
* Resets the input stream to begin reading from the first character
* of this input stream's underlying buffer.
*/
+ @Override
public synchronized void reset() {
pos = 0;
}Attachments
Issue Links
- csr of
-
JDK-8286783 Expand use of @inheritDoc in InputStream and OutputStream subclasses
-
- Resolved
-