Summary

Clarify that exceptions due to encoding are not thrown by java.nio.file.Files.newBufferedWriter itself but rather by invoking certain methods on the returned java.io.BufferedWriter.

Problem

The specification currently states

The Writer methods to write text throw IOException if the text cannot be encoded using the specified charset.

which implies that only the write methods throw such exceptions. Due to buffering, encoding errors may be detected when writing, flushing, or closing the buffered writer.

Solution

Add some verbiage to make explicit that buffering might cause an IOException when the java.io.BufferedWriter is closed, flushed, or written to.

Specification

--- a/src/java.base/share/classes/java/nio/file/Files.java
+++ b/src/java.base/share/classes/java/nio/file/Files.java
@@ -2936,11 +2936,16 @@
      * opens the file for writing, creating the file if it doesn't exist, or
      * initially truncating an existing {@link #isRegularFile regular-file} to
      * 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
      * @param   cs
      *          the charset to use for encoding