8356420: Provide examples on wrapping System.in

Reviewed-by: liach, smarks, alanb, bpb, iris

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2025, 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
@@ -50,9 +50,17 @@ import sun.nio.cs.StreamDecoder;
  *     BufferedReader in = new BufferedReader(new InputStreamReader(anInputStream));
  * }
  *
+ * <P>To read from {@link System#in}, use the system property value
+ * {@link System##stdin.encoding stdin.encoding} as the {@code Charset}:
+ *
+ * {@snippet lang=java :
+ *     new InputStreamReader(System.in, System.getProperty("stdin.encoding"));
+ * }
+ *
  * @see BufferedReader
  * @see InputStream
  * @see Charset
+ * @see System##stdin.encoding stdin.encoding
  *
  * @author      Mark Reinhold
  * @since       1.1

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

@@ -124,10 +124,19 @@ public final class System {
      *
      * @apiNote
      * The typical approach to read character data is to wrap {@code System.in}
-     * within an {@link java.io.InputStreamReader InputStreamReader} or other object
-     * that handles character encoding. After this is done, subsequent reading should
-     * use only the wrapper object; operating directly on {@code System.in} results
-     * in unspecified behavior.
+     * within the object that handles character encoding. After this is done,
+     * subsequent reading should use only the wrapper object; continuing to
+     * operate directly on {@code System.in} results in unspecified behavior.
+     * <p>
+     * Here are two common examples. Using an {@link java.io.InputStreamReader
+     * InputStreamReader}:
+     * {@snippet lang=java :
+     *     new InputStreamReader(System.in, System.getProperty("stdin.encoding"));
+     * }
+     * Or using a {@link java.util.Scanner Scanner}:
+     * {@snippet lang=java :
+     *     new Scanner(System.in, System.getProperty("stdin.encoding"));
+     * }
      * <p>
      * For handling interactive input, consider using {@link Console}.
      *

src/java.base/share/classes/java/util/Scanner.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2023, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2025, 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
@@ -78,7 +78,7 @@ import sun.util.locale.provider.ResourceBundleBasedAdapter;
  *     }
  * }
  *
- * <p>As another example, this code allows {@code long} types to be
+ * <p>This code allows {@code long} types to be
  * assigned from entries in a file {@code myNumbers}:
  * {@snippet :
  *      Scanner sc = new Scanner(new File("myNumbers"));
@@ -87,6 +87,19 @@ import sun.util.locale.provider.ResourceBundleBasedAdapter;
  *      }
  * }
  *
+ * <p>This code uses a {@code Scanner} to read lines from {@link System#in}. The
+ * {@code Scanner} uses the system property value of
+ * {@link System##stdin.encoding stdin.encoding} as the {@code Charset}. Specifying
+ * the charset explicitly is important when reading from {@code System.in}, as it
+ * may differ from the {@link Charset#defaultCharset() default charset} depending
+ * on the host environment or user configuration:
+ * {@snippet :
+ *      Scanner sc = new Scanner(System.in, System.getProperty("stdin.encoding"));
+ *      while (sc.hasNextLine()) {
+ *          String aLine = sc.nextLine();
+ *      }
+ * }
+ *
  * <p>The scanner can also use delimiters other than whitespace. This
  * example reads several items in from a string:
  * {@snippet :

src/java.base/share/classes/javax/security/auth/callback/CallbackHandler.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2025, 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
@@ -113,7 +113,9 @@ public interface CallbackHandler {
      *          System.err.print(nc.getPrompt());
      *          System.err.flush();
      *          nc.setName((new BufferedReader
-     *                  (new InputStreamReader(System.in))).readLine());
+     *                  (new InputStreamReader(
+     *                          System.in,
+     *                          System.getProperty("stdin.encoding")))).readLine());
      *
      *      } else if (callbacks[i] instanceof PasswordCallback) {
      *