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()
          */