Summary

Provide an API that returns the Charset used in the Console.

Problem

There's no way for an application to get which charset is used in the console, which may differ from the one from Charset.defaultCharset() method.

Solution

Create a new public method that returns the Charset used in the Console. The returned Charset may be different from the one returned from Charset.defaultCharset() method.

Specification

Add the following method in java.io.Console class:

/**
 * Returns the {@link java.nio.charset.Charset Charset} object used for
 * 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.
 * It may not necessarily be the same as the default charset returned from
 * {@link java.nio.charset.Charset#defaultCharset() Charset.defaultCharset()}.
 *
 * @return a {@link java.nio.charset.Charset Charset} object used for the
 *          {@code Console}
 * @since 17
 */
public Charset charset();

Add a sentence that explains wrapping with java.io.InputStreamReader to the description of java.lang.System#in field:

/**
 * The "standard" input stream. This stream is already
 * open and ready to supply input data. Typically this stream
 * corresponds to keyboard input or another input source specified by
 * the host environment or user. In case this stream is wrapped
 * in a {@link java.io.InputStreamReader}, {@link Console#charset()}
 * should be used for the charset, or consider using
 * {@link Console#reader()}.
 *
 * @see Console#charset()
 * @see Console#reader()
 */

Add a sentence about the encoding to the description of java.lang.System#out/err fields:

/**
 * The "standard" output stream. This stream is already
 * open and ready to accept output data. Typically this stream
 * 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,
 * {@link Charset#defaultCharset()} otherwise.
 * <p>
 * For simple stand-alone Java applications, a typical way to write
 * a line of output data is:
 * <blockquote><pre>
 *     System.out.println(data)
 * </pre></blockquote>
 * <p>
 * See the {@code println} methods in class {@code PrintStream}.
 *
 * @see     java.io.PrintStream#println()
 * @see     java.io.PrintStream#println(boolean)
 * @see     java.io.PrintStream#println(char)
 * @see     java.io.PrintStream#println(char[])
 * @see     java.io.PrintStream#println(double)
 * @see     java.io.PrintStream#println(float)
 * @see     java.io.PrintStream#println(int)
 * @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     Charset#defaultCharset()
 */

and

/**
 * The "standard" error output stream. This stream is already
 * open and ready to accept output data.
 * <p>
 * Typically this stream corresponds to display output or another
 * output destination specified by the host environment or user. By
 * convention, this output stream is used to display error messages
 * or other information that should come to the immediate attention
 * of a user even if the principal output stream, the value of the
 * 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, {@link Charset#defaultCharset()} otherwise.
 *
 * @see     Console#charset()
 * @see     Charset#defaultCharset()
 */

respectively.

Modify the example in java.io.InputStreamReader class description by replacing System.in with anInputStream so that readers would not use the example which is reading System.in without specifying the encoding.

 * <pre>
 * BufferedReader in
 *   = new BufferedReader(new InputStreamReader(anInputStream));
 * </pre>

Also, replace the "default charset" text to a link to Charset#defaultCharset() in the class description:

- * default charset may be accepted.
+ * {@link Charset#defaultCharset() default charset} may be accepted.
  *

and replace it and add @see link in 1-arg constructor:

     /**
-     * Creates an InputStreamReader that uses the default charset.
+     * Creates an InputStreamReader that uses the
+     * {@link Charset#defaultCharset() default charset}.
      *
      * @param  in   An InputStream
+     *
+     * @see Charset#defaultCharset()
      */