Summary

Provide a means to specify encoding to be used in java.io.IO printing methods.

Problem

Unlike System.out.print* methods which utilize the user-overridable stdout.encoding system property, there is no way to specify encoding for java.io.IO printing methods, which uses java.io.Console printing methods underneath.

Solution

Change the implementation of java.io.Console, specifically the way to determine the default charset for the class. The logic is currently to use platform-specific terminal encoding, or else use "native.encoding" property which is not overridable, or finally use Charset.defaultCharset().

It is desirable to align this logic to the one used for System.out, which is to use "stdout.encoding" that is overridable, or else UTF-8. Note that "stdout.encoding" is equivalent to the platform-specific terminal encoding by default. The differences between these two logic are substitutions with "native.encoding" and Charset.defaultChaset(), but for the console encoding, both seem to be questionable in the first place (e.g on Windows, console encoding and native/default charset differ, such as cp437 vs cp1252).

Specification

Change the method description for java.io.Console.charset() as:

--- a/src/java.base/share/classes/java/io/Console.java
+++ b/src/java.base/share/classes/java/io/Console.java
@@ -580,7 +580,8 @@
      * the {@code Console}.
      * <p>
      * The returned charset corresponds to the input and output source
-     * (e.g., keyboard and/or display) specified by the host environment or user.
+     * (e.g., keyboard and/or display) specified by the host environment or user,
+     * which defaults to the one based on {@link System##stdout.encoding stdout.encoding}.
      * It may not necessarily be the same as the default charset returned from
      * {@link java.nio.charset.Charset#defaultCharset() Charset.defaultCharset()}.
      *

Modify the definition of stdout.encoding system property as:

@@ -788,7 +786,8 @@
      *     <td>Character encoding name derived from the host environment and/or
      *     the user's settings. Setting this system property has no effect.</td></tr>
      * <tr><th scope="row">{@systemProperty stdout.encoding}</th>
-     *     <td>Character encoding name for {@link System#out System.out}.
+     *     <td>Character encoding name for {@link System#out System.out} and
+     *     {@link System#console() System.console()}.
      *     The Java runtime can be started with the system property set to {@code UTF-8},
      *     starting it with the property set to another value leads to undefined behavior.
      * <tr><th scope="row">{@systemProperty stderr.encoding}</th>

Change the field description of java.lang.System.out as:

@@ -147,8 +147,7 @@
      * corresponds to display output or another output destination
      * specified by the host environment or user. The encoding used
      * in the conversion from characters to bytes is equivalent to
-     * {@link Console#charset()} if the {@code Console} exists,
-     * <a href="#stdout.encoding">stdout.encoding</a> otherwise.
+     * {@link ##stdout.encoding stdout.encoding}.
      * <p>
      * For simple stand-alone Java applications, a typical way to write
      * a line of output data is:
@@ -168,7 +167,6 @@
      * @see     java.io.PrintStream#println(long)
      * @see     java.io.PrintStream#println(java.lang.Object)
      * @see     java.io.PrintStream#println(java.lang.String)
-     * @see     Console#charset()
-     * @see     <a href="#stdout.encoding">stdout.encoding</a>
+     * @see     ##stdout.encoding stdout.encoding

      */

Change the field description of java.lang.System.err as:

@@ -183,11 +183,9 @@
      * variable {@code out}, has been redirected to a file or other
      * destination that is typically not continuously monitored.
      * The encoding used in the conversion from characters to bytes is
-     * equivalent to {@link Console#charset()} if the {@code Console}
-     * exists, <a href="#stderr.encoding">stderr.encoding</a> otherwise.
+     * equivalent to {@link ##stderr.encoding stderr.encoding}.
      *
-     * @see     Console#charset()
-     * @see     <a href="#stderr.encoding">stderr.encoding</a>
+     * @see     ##stderr.encoding stderr.encoding
      */