Summary

Change the specification of java.io.PrintStream to clarify that the flush() method of the underlying OutputStream is called during automatic flushing as opposed to the flush() method of PrintStream itself.

Problem

The specification of PrintStream states that the method PrintStream.flush() is called during automatic flushing when it is in fact out.flush() which is invoked.

Solution

Change the specification to refer to the flush method of the underlying output stream. The class specification and those of the various write*() methods are affected.

Specification

Class

--- a/src/java.base/share/classes/java/io/PrintStream.java
+++ b/src/java.base/share/classes/java/io/PrintStream.java
@@ -39,9 +39,9 @@ import java.nio.charset.UnsupportedCharsetException;
  * {@code IOException}; instead, exceptional situations merely set an
  * internal flag that can be tested via the {@code checkError} method.
  * Optionally, a {@code PrintStream} can be created so as to flush
- * automatically; this means that the {@code flush} method is
- * automatically invoked after a byte array is written, one of the
- * {@code println} methods is invoked, or a newline character or byte
+ * automatically; this means that the {@code flush} method of the underlying
+ * output stream is automatically invoked after a byte array is written, one
+ * of the {@code println} methods is invoked, or a newline character or byte
  * ({@code '\n'}) is written.
  *
  * <p> All characters printed by a {@code PrintStream} are converted into
@@ -50,8 +50,8 @@ import java.nio.charset.UnsupportedCharsetException;
  * The {@link PrintWriter} class should be used in situations that require
  * writing characters rather than bytes.
  *
- * <p> This class always replaces malformed and unmappable character sequences with
- * the charset's default replacement string.
+ * <p> This class always replaces malformed and unmappable character sequences
+ * with the charset's default replacement string.
  * The {@linkplain java.nio.charset.CharsetEncoder} class should be used when more
  * control over the encoding process is required.
  *

write(int)

@@ -516,7 +516,7 @@ public class PrintStream extends FilterOutputStream
     /**
      * Writes the specified byte to this stream.  If the byte is a newline and
      * automatic flushing is enabled then the {@code flush} method will be
-     * invoked.
+     * invoked on the underlying output stream.
      *
      * <p> Note that the byte is written as given; to write a character that
      * will be translated according to the platform's default character

### write(byte[],int,int)

@@ -548,7 +548,8 @@ public class PrintStream extends FilterOutputStream
     /**
      * Writes {@code len} bytes from the specified byte array starting at
      * offset {@code off} to this stream.  If automatic flushing is
-     * enabled then the {@code flush} method will be invoked.
+     * enabled then the {@code flush} method will be invoked on the underlying
+     * output stream.
      *
      * <p> Note that the bytes will be written as given; to write characters
      * that will be translated according to the platform's default character

write(byte[])

@@ -580,7 +581,7 @@ public class PrintStream extends FilterOutputStream
     /**
      * Writes all bytes from the specified byte array to this stream. If
      * automatic flushing is enabled then the {@code flush} method will be
-     * invoked.
+     * invoked on the underlying output stream.
      *
      * <p> Note that the bytes will be written as given; to write characters
      * that will be translated according to the platform's default character

writeBytes(byte[])

@@ -617,8 +618,8 @@ public class PrintStream extends FilterOutputStream

     /**
      * Writes all bytes from the specified byte array to this stream.
-     * If automatic flushing is enabled then the {@code flush} method
-     * will be invoked.
+     * If automatic flushing is enabled then the {@code flush} method will be
+     * invoked on the underlying output stream.
      *
      * <p> Note that the bytes will be written as given; to write characters
      * that will be translated according to the platform's default character