8264208: Console charset API

Reviewed-by: joehw, rriggs, alanb

src/java.base/share/classes/java/io/Console.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2018, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2021, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -31,6 +31,7 @@ import jdk.internal.access.JavaIOAccess;
 import jdk.internal.access.SharedSecrets;
 import sun.nio.cs.StreamDecoder;
 import sun.nio.cs.StreamEncoder;
+import sun.security.action.GetPropertyAction;
 
 /**
  * Methods to access the character-based console device, if any, associated
@@ -390,13 +391,31 @@ public final class Console implements Flushable
         pw.flush();
     }
 
+
+    /**
+     * 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() {
+        assert CHARSET != null : "charset() should not return null";
+        return CHARSET;
+    }
+
     private Object readLock;
     private Object writeLock;
     private Reader reader;
     private Writer out;
     private PrintWriter pw;
     private Formatter formatter;
-    private Charset cs;
     private char[] rcb;
     private boolean restoreEcho;
     private boolean shutdownHookInstalled;
@@ -551,8 +570,21 @@ public final class Console implements Flushable
         }
     }
 
-    // Set up JavaIOAccess in SharedSecrets
+    private static final Charset CHARSET;
     static {
+        String csname = encoding();
+        Charset cs = null;
+        if (csname == null) {
+            csname = GetPropertyAction.privilegedGetProperty("sun.stdout.encoding");
+        }
+        if (csname != null) {
+            try {
+                cs = Charset.forName(csname);
+            } catch (Exception ignored) { }
+        }
+        CHARSET = cs == null ? Charset.defaultCharset() : cs;
+
+        // Set up JavaIOAccess in SharedSecrets
         SharedSecrets.setJavaIOAccess(new JavaIOAccess() {
             public Console console() {
                 if (istty()) {
@@ -564,9 +596,7 @@ public final class Console implements Flushable
             }
 
             public Charset charset() {
-                // This method is called in sun.security.util.Password,
-                // cons already exists when this method is called
-                return cons.cs;
+                return CHARSET;
             }
         });
     }
@@ -575,24 +605,16 @@ public final class Console implements Flushable
     private Console() {
         readLock = new Object();
         writeLock = new Object();
-        String csname = encoding();
-        if (csname != null) {
-            try {
-                cs = Charset.forName(csname);
-            } catch (Exception x) {}
-        }
-        if (cs == null)
-            cs = Charset.defaultCharset();
         out = StreamEncoder.forOutputStreamWriter(
                   new FileOutputStream(FileDescriptor.out),
                   writeLock,
-                  cs);
+                  CHARSET);
         pw = new PrintWriter(out, true) { public void close() {} };
         formatter = new Formatter(out);
         reader = new LineReader(StreamDecoder.forInputStreamReader(
                      new FileInputStream(FileDescriptor.in),
                      readLock,
-                     cs));
+                     CHARSET));
         rcb = new char[1024];
     }
 }

src/java.base/share/classes/java/io/InputStreamReader.java

@@ -35,7 +35,7 @@ import sun.nio.cs.StreamDecoder;
  * reads bytes and decodes them into characters using a specified {@link
  * java.nio.charset.Charset charset}.  The charset that it uses
  * may be specified by name or may be given explicitly, or the platform's
- * default charset may be accepted.
+ * {@link Charset#defaultCharset() default charset} may be accepted.
  *
  * <p> Each invocation of one of an InputStreamReader's read() methods may
  * cause one or more bytes to be read from the underlying byte-input stream.
@@ -48,7 +48,7 @@ import sun.nio.cs.StreamDecoder;
  *
  * <pre>
  * BufferedReader in
- *   = new BufferedReader(new InputStreamReader(System.in));
+ *   = new BufferedReader(new InputStreamReader(anInputStream));
  * </pre>
  *
  * @see BufferedReader
@@ -64,9 +64,12 @@ public class InputStreamReader extends Reader {
     private final StreamDecoder sd;
 
     /**
-     * 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()
      */
     public InputStreamReader(InputStream in) {
         super(in);

src/java.base/share/classes/java/lang/System.java

@@ -114,7 +114,13 @@ public final class System {
      * 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.
+     * 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()
      */
     public static final InputStream in = null;
 
@@ -122,7 +128,10 @@ public final class System {
      * 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.
+     * 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:
@@ -142,6 +151,8 @@ public final class System {
      * @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()
      */
     public static final PrintStream out = null;
 
@@ -156,6 +167,12 @@ public final class System {
      * 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()
      */
     public static final PrintStream err = null;
 
@@ -2014,6 +2031,9 @@ public final class System {
         FileOutputStream fdOut = new FileOutputStream(FileDescriptor.out);
         FileOutputStream fdErr = new FileOutputStream(FileDescriptor.err);
         setIn0(new BufferedInputStream(fdIn));
+        // sun.stdout/err.encoding are set when the VM is associated with the terminal,
+        // thus they are equivalent to Console.charset(), otherwise the encoding
+        // defaults to Charset.defaultCharset()
         setOut0(newPrintStream(fdOut, props.getProperty("sun.stdout.encoding")));
         setErr0(newPrintStream(fdErr, props.getProperty("sun.stderr.encoding")));