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

8286604: Update InputStream and OutputStream to use @implSpec

Browse Source 
Reviewed-by: bpb, lancea, iris, alanb
This commit is contained in:
Joe Darcy 2022-05-13 16:57:11 +00:00
parent 78ffefb849
commit 1e843c3d4f
2 changed files with 31 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
src/java.base/share/classes/java/io/InputStream.java
View File

@ -173,8 +173,6 @@ public abstract class InputStream implements Closeable {
* blocks until input data is available, the end of the stream is detected, * blocks until input data is available, the end of the stream is detected,
* or an exception is thrown. * or an exception is thrown.
* *
* <p> A subclass must provide an implementation of this method.
*
* @return the next byte of data, or {@code -1} if the end of the * @return the next byte of data, or {@code -1} if the end of the
* stream is reached. * stream is reached.
* @throws IOException if an I/O error occurs. * @throws IOException if an I/O error occurs.
@ -201,7 +199,8 @@ public abstract class InputStream implements Closeable {
* leaving elements {@code b[}<i>k</i>{@code ]} through * leaving elements {@code b[}<i>k</i>{@code ]} through
* {@code b[b.length-1]} unaffected. * {@code b[b.length-1]} unaffected.
* *
* <p> The {@code read(b)} method for class {@code InputStream} * @implSpec
* The {@code read(b)} method for class {@code InputStream}
* has the same effect as: <pre>{@code read(b, 0, b.length) }</pre> * has the same effect as: <pre>{@code read(b, 0, b.length) }</pre>
* *
* @param b the buffer into which the data is read. * @param b the buffer into which the data is read.
@ -245,7 +244,8 @@ public abstract class InputStream implements Closeable {
* {@code b[off-1]} and elements {@code b[off+len]} through * {@code b[off-1]} and elements {@code b[off+len]} through
* {@code b[b.length-1]} are unaffected. * {@code b[b.length-1]} are unaffected.
* *
* <p> The {@code read(b, off, len)} method * @implSpec
* The {@code read(b, off, len)} method
* for class {@code InputStream} simply calls the method * for class {@code InputStream} simply calls the method
* {@code read()} repeatedly. If the first such call results in an * {@code read()} repeatedly. If the first such call results in an
* {@code IOException}, that exception is returned from the call to * {@code IOException}, that exception is returned from the call to
@ -522,7 +522,8 @@ public abstract class InputStream implements Closeable {
* returns 0, and no bytes are skipped. Subclasses may handle the negative * returns 0, and no bytes are skipped. Subclasses may handle the negative
* value differently. * value differently.
* *
* <p> The {@code skip} method implementation of this class creates a * @implSpec
* The {@code skip} method implementation of this class creates a
* byte array and then repeatedly reads into it until {@code n} bytes * byte array and then repeatedly reads into it until {@code n} bytes
* have been read or the end of the stream has been reached. Subclasses are * have been read or the end of the stream has been reached. Subclasses are
* encouraged to provide a more efficient implementation of this method. * encouraged to provide a more efficient implementation of this method.
@ -632,10 +633,12 @@ public abstract class InputStream implements Closeable {
* {@link IOException} if this input stream has been closed by invoking the * {@link IOException} if this input stream has been closed by invoking the
* {@link #close()} method. * {@link #close()} method.
* *
* <p> The {@code available} method of {@code InputStream} always returns * @implSpec
* The {@code available} method of {@code InputStream} always returns
* {@code 0}. * {@code 0}.
* *
* <p> This method should be overridden by subclasses. * @apiNote
* This method should be overridden by subclasses.
* *
* @return an estimate of the number of bytes that can be read (or * @return an estimate of the number of bytes that can be read (or
* skipped over) from this input stream without blocking or * skipped over) from this input stream without blocking or
@ -650,7 +653,8 @@ public abstract class InputStream implements Closeable {
* Closes this input stream and releases any system resources associated * Closes this input stream and releases any system resources associated
* with the stream. * with the stream.
* *
* <p> The {@code close} method of {@code InputStream} does * @implSpec
* The {@code close} method of {@code InputStream} does
* nothing. * nothing.
* *
* @throws IOException if an I/O error occurs. * @throws IOException if an I/O error occurs.
@ -676,8 +680,8 @@ public abstract class InputStream implements Closeable {
* *
* <p> Marking a closed stream should not have any effect on the stream. * <p> Marking a closed stream should not have any effect on the stream.
* *
* <p> The {@code mark} method of {@code InputStream} does * @implSpec
* nothing. * The {@code mark} method of {@code InputStream} does nothing.
* *
* @param readlimit the maximum limit of bytes that can be read before * @param readlimit the maximum limit of bytes that can be read before
* the mark position becomes invalid. * the mark position becomes invalid.
@ -721,7 +725,8 @@ public abstract class InputStream implements Closeable {
* to subsequent callers of the {@code read} method depend on the * to subsequent callers of the {@code read} method depend on the
* particular type of the input stream. </ul></ul> * particular type of the input stream. </ul></ul>
* *
* <p>The method {@code reset} for class {@code InputStream} * @implSpec
* The method {@code reset} for class {@code InputStream}
* does nothing except throw an {@code IOException}. * does nothing except throw an {@code IOException}.
* *
* @throws IOException if this stream has not been marked or if the * @throws IOException if this stream has not been marked or if the

26
src/java.base/share/classes/java/io/OutputStream.java
View File

@ -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. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -102,9 +102,6 @@ public abstract class OutputStream implements Closeable, Flushable {
* to the output stream. The byte to be written is the eight * to the output stream. The byte to be written is the eight
* low-order bits of the argument {@code b}. The 24 * low-order bits of the argument {@code b}. The 24
* high-order bits of {@code b} are ignored. * high-order bits of {@code b} are ignored.
* <p>
* Subclasses of {@code OutputStream} must provide an
* implementation for this method.
* *
* @param b the {@code byte}. * @param b the {@code byte}.
* @throws IOException if an I/O error occurs. In particular, * @throws IOException if an I/O error occurs. In particular,
@ -135,11 +132,7 @@ public abstract class OutputStream implements Closeable, Flushable {
* output stream in order; element {@code b[off]} is the first * output stream in order; element {@code b[off]} is the first
* byte written and {@code b[off+len-1]} is the last byte written * byte written and {@code b[off+len-1]} is the last byte written
* by this operation. * by this operation.
* <p> *
* The {@code write} method of {@code OutputStream} calls
* the write method of one argument on each of the bytes to be
* written out. Subclasses are encouraged to override this method and
* provide a more efficient implementation.
* <p> * <p>
* If {@code b} is {@code null}, a * If {@code b} is {@code null}, a
* {@code NullPointerException} is thrown. * {@code NullPointerException} is thrown.
@ -148,6 +141,15 @@ public abstract class OutputStream implements Closeable, Flushable {
* {@code off+len} is greater than the length of the array * {@code off+len} is greater than the length of the array
* {@code b}, then an {@code IndexOutOfBoundsException} is thrown. * {@code b}, then an {@code IndexOutOfBoundsException} is thrown.
* *
* @implSpec
* The {@code write} method of {@code OutputStream} calls
* the write method of one argument on each of the bytes to be
* written out.
*
* @apiNote
* Subclasses are encouraged to override this method and
* provide a more efficient implementation.
*
* @param b the data. * @param b the data.
* @param off the start offset in the data. * @param off the start offset in the data.
* @param len the number of bytes to write. * @param len the number of bytes to write.
@ -176,7 +178,8 @@ public abstract class OutputStream implements Closeable, Flushable {
* stream guarantees only that bytes previously written to the stream are * stream guarantees only that bytes previously written to the stream are
* passed to the operating system for writing; it does not guarantee that * passed to the operating system for writing; it does not guarantee that
* they are actually written to a physical device such as a disk drive. * they are actually written to a physical device such as a disk drive.
* <p> *
* @implSpec
* The {@code flush} method of {@code OutputStream} does nothing. * The {@code flush} method of {@code OutputStream} does nothing.
* *
* @throws IOException if an I/O error occurs. * @throws IOException if an I/O error occurs.
@ -189,7 +192,8 @@ public abstract class OutputStream implements Closeable, Flushable {
* associated with this stream. The general contract of {@code close} * associated with this stream. The general contract of {@code close}
* is that it closes the output stream. A closed stream cannot perform * is that it closes the output stream. A closed stream cannot perform
* output operations and cannot be reopened. * output operations and cannot be reopened.
* <p> *
* @implSpec
* The {@code close} method of {@code OutputStream} does nothing. * The {@code close} method of {@code OutputStream} does nothing.
* *
* @throws IOException if an I/O error occurs. * @throws IOException if an I/O error occurs.