7093322: (fs spec) Files.newBufferedWriter should be clear when coding errors are detected

Brian Burkhalter · Brian Burkhalter · commit 831b35fad352 · 2022-12-15T17:27:39.000Z
Reviewed-by: alanb
diff --git a/src/java.base/share/classes/java/nio/file/Files.java b/src/java.base/share/classes/java/nio/file/Files.java
@@ -2938,7 +2938,12 @@ public static BufferedReader newBufferedReader(Path path) throws IOException {
      * a size of {@code 0} if it exists.
      *
      * <p> The {@code Writer} methods to write text throw {@code IOException}
-     * if the text cannot be encoded using the specified charset.
+     * if the text cannot be encoded using the specified charset. Due to
+     * buffering, an {@code IOException} caused by an encoding error
+     * (unmappable-character or malformed-input) may be thrown when {@linkplain
+     * BufferedWriter#write(char[],int,int) writing}, {@linkplain
+     * BufferedWriter#flush flushing}, or {@linkplain BufferedWriter#close
+     * closing} the buffered writer.
      *
      * @param   path
      *          the path to the file

Original file line number	Diff line number	Diff line change
`@@ -2938,7 +2938,12 @@ public static BufferedReader newBufferedReader(Path path) throws IOException {`
`2938`	`2938`	`* a size of {@code 0} if it exists.`
`2939`	`2939`	`*`
`2940`	`2940`	`* <p> The {@code Writer} methods to write text throw {@code IOException}`
`2941`		`- * if the text cannot be encoded using the specified charset.`
	`2941`	`+ * if the text cannot be encoded using the specified charset. Due to`
	`2942`	`+ * buffering, an {@code IOException} caused by an encoding error`
	`2943`	`+ * (unmappable-character or malformed-input) may be thrown when {@linkplain`
	`2944`	`+ * BufferedWriter#write(char[],int,int) writing}, {@linkplain`
	`2945`	`+ * BufferedWriter#flush flushing}, or {@linkplain BufferedWriter#close`
	`2946`	`+ * closing} the buffered writer.`
`2942`	`2947`	`*`
`2943`	`2948`	`* @param path`
`2944`	`2949`	`* the path to the file`