8187898: PrintStream should override FilterOutputStream#write(byte[]) with a method that has no throws clause

Reviewed-by: alanb, rriggs, lancea, darcy

src/java.base/share/classes/java/io/PrintStream.java

@@ -415,6 +415,7 @@ public class PrintStream extends FilterOutputStream
      *
      * @see        java.io.OutputStream#flush()
      */
+    @Override
     public void flush() {
         synchronized (this) {
             try {
@@ -435,6 +436,7 @@ public class PrintStream extends FilterOutputStream
      *
      * @see        java.io.OutputStream#close()
      */
+    @Override
     public void close() {
         synchronized (this) {
             if (! closing) {
@@ -526,6 +528,7 @@ public class PrintStream extends FilterOutputStream
      * @see #print(char)
      * @see #println(char)
      */
+    @Override
     public void write(int b) {
         try {
             synchronized (this) {
@@ -557,6 +560,7 @@ public class PrintStream extends FilterOutputStream
      * @param  off   Offset from which to start taking bytes
      * @param  len   Number of bytes to write
      */
+    @Override
     public void write(byte buf[], int off, int len) {
         try {
             synchronized (this) {
@@ -574,6 +578,66 @@ 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.
+     *
+     * <p> Note that the bytes will be written as given; to write characters
+     * that will be translated according to the platform's default character
+     * encoding, use the {@code print(char[])} or {@code println(char[])}
+     * methods.
+     *
+     * @apiNote
+     * Although declared to throw {@code IOException}, this method never
+     * actually does so. Instead, like other methods that this class
+     * overrides, it sets an internal flag which may be tested via the
+     * {@link #checkError()} method. To write an array of bytes without having
+     * to write a {@code catch} block for the {@code IOException}, use either
+     * {@link #writeBytes(byte[] buf) writeBytes(buf)} or
+     * {@link #write(byte[], int, int) write(buf, 0, buf.length)}.
+     *
+     * @implSpec
+     * This method is equivalent to
+     * {@link java.io.PrintStream#write(byte[],int,int)
+     * this.write(buf, 0, buf.length)}.
+     *
+     * @param  buf   A byte array
+     *
+     * @throws IOException If an I/O error occurs.
+     *
+     * @see #writeBytes(byte[])
+     * @see #write(byte[],int,int)
+     *
+     * @since 14
+     */
+    @Override
+    public void write(byte buf[]) throws IOException {
+        this.write(buf, 0, buf.length);
+    }
+
+    /**
+     * Writes all bytes from the specified byte array to this stream.
+     * If automatic flushing is enabled then the {@code flush} method
+     * will be invoked.
+     *
+     * <p> Note that the bytes will be written as given; to write characters
+     * that will be translated according to the platform's default character
+     * encoding, use the {@code print(char[])} or {@code println(char[])}
+     * methods.
+     *
+     * @implSpec
+     * This method is equivalent to
+     * {@link #write(byte[], int, int) this.write(buf, 0, buf.length)}.
+     *
+     * @param  buf   A byte array
+     *
+     * @since 14
+     */
+    public void writeBytes(byte buf[]) {
+        this.write(buf, 0, buf.length);
+    }
+
     /*
      * The following private methods on the text- and character-output streams
      * always flush the stream buffers, so that writes to the underlying byte

test/jdk/java/io/PrintStream/WriteBytes.java

@@ -0,0 +1,76 @@
+/*
+ * Copyright (c) 2019, 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
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+/**
+ * @test
+ * @bug 8187898
+ * @summary Test of writeBytes(byte[])
+ */
+
+import java.io.BufferedOutputStream;
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.io.OutputStream;
+import java.io.PrintStream;
+import java.util.Arrays;
+
+public class WriteBytes {
+    public static void main(String[] args) throws Exception {
+        ByteArrayOutputStream baos = new ByteArrayOutputStream();
+        OutputStream out = new BufferedOutputStream(baos, 512);
+        PrintStream ps = new PrintStream(out, false);
+
+        byte[] buf = new byte[128];
+        for (int i = 0; i < buf.length; i++) {
+            buf[i] = (byte)i;
+        }
+
+        ps.writeBytes(buf);
+        assertTrue(baos.size() == 0, "Buffer should not have been flushed");
+        ps.close();
+        assertTrue(baos.size() == buf.length, "Stream size " + baos.size() +
+            " but expected " + buf.length);
+
+        ps = new PrintStream(out, true);
+        ps.writeBytes(buf);
+        assertTrue(baos.size() == 2*buf.length, "Stream size " + baos.size() +
+            " but expected " + 2*buf.length);
+
+        byte[] arr = baos.toByteArray();
+        assertTrue(arr.length == 2*buf.length, "Array length " + arr.length +
+            " but expected " + 2*buf.length);
+        assertTrue(Arrays.equals(buf, 0, buf.length, arr, 0, buf.length),
+            "First write not equal");
+        assertTrue(Arrays.equals(buf, 0, buf.length, arr, buf.length,
+            2*buf.length), "Second write not equal");
+
+        ps.close();
+        ps.writeBytes(buf);
+        assertTrue(ps.checkError(), "Error condition should be true");
+    }
+
+    private static void assertTrue(boolean condition, String msg) {
+        if (!condition)
+            throw new RuntimeException(msg);
+    }
+}