Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8342937

Enhance java.io.IO with parameter-less println() and readln()

XMLWordPrintable

    • Icon: CSR CSR
    • Resolution: Approved
    • Icon: P4 P4
    • 24
    • core-libs
    • None
    • source
    • minimal
    • Java API
    • SE

      Summary

      Several new methods, namely println() and readln() are added to java.io.IO, and corresponding supporting classes.

      Problem

      Currently the java.io.IO class provides two output methods: print(Object) and println(Object). But, if the caller used the print(Object) method, and now needs to issue a newline, it is inconvenient to use println("").

      For input java.io.IO only provides readln(String), which emits a prompt. Sometimes, it may be desirable to read a line from the input without a prompt.

      Solution

      println() is added to java.io.IO, which emits the newline. A corresponding method is added to java.io.Console, to preserve the invariant that every method in java.io.IO only delegates to a same-named method in java.io.Console.

      readln() is added to java.io.IO, which reads a line, without printing a prompt. Corresponding method is added to java.io.Console and jdk.jshell.JShellConsole.

      All these newly added methods with be marked as preview API.

      Specification

      The exact proposal is this:

      diff --git a/src/java.base/share/classes/java/io/Console.java b/src/java.base/share/classes/java/io/Console.java
      index 0aa12bdf4c8b5..6d7e1694d1230 100644
      --- a/src/java.base/share/classes/java/io/Console.java
      +++ b/src/java.base/share/classes/java/io/Console.java
      @@ -172,6 +172,19 @@ public Console println(Object obj) {
               throw newUnsupportedOperationException();
           }
      
      +    /**
      +     * Terminates the current line in this console's output stream using
      +     * {@link System#lineSeparator()} and then flushes the console.
      +     *
      +     * @return  This console
      +     *
      +     * @since 24
      +     */
      +    @PreviewFeature(feature = PreviewFeature.Feature.IMPLICIT_CLASSES)
      +    public Console println() {
      +        return println("");
      +    }
      +
           /**
            * Writes a string representation of the specified object to this console's
            * output stream and then flushes the console.
      @@ -214,6 +227,24 @@ public String readln(String prompt) {
               throw newUnsupportedOperationException();
           }
      
      +    /**
      +     * Reads a single line of text from this console.
      +     *
      +     * @throws IOError
      +     *         If an I/O error occurs.
      +     *
      +     * @return  A string containing the line read from the console, not
      +     *          including any line-termination characters, or {@code null}
      +     *          if an end of stream has been reached without having read
      +     *          any characters.
      +     *
      +     * @since 24
      +     */
      +    @PreviewFeature(feature = PreviewFeature.Feature.IMPLICIT_CLASSES)
      +    public String readln() {
      +        throw newUnsupportedOperationException();
      +    }
      +
           /**
            * Writes a formatted string to this console's output stream using
            * the specified format string and arguments with the
      diff --git a/src/java.base/share/classes/java/io/IO.java b/src/java.base/share/classes/java/io/IO.java
      index 7485f87f03fda..a49a51041fc04 100644
      --- a/src/java.base/share/classes/java/io/IO.java
      +++ b/src/java.base/share/classes/java/io/IO.java
      @@ -63,6 +63,21 @@ public static void println(Object obj) {
               con().println(obj);
           }
      
      +    /**
      +     * Terminates the current line on the system console and then flushes
      +     * that console.
      +     *
      +     * <p> The effect is as if {@link Console#println() println()}
      +     * had been called on {@code System.console()}.
      +     *
      +     * @throws IOError if {@code System.console()} returns {@code null},
      +     *                 or if an I/O error occurs
      +     * @since 24
      +     */
      +    public static void println() {
      +        con().println();
      +    }
      +
           /**
            * Writes a string representation of the specified object to the system
            * console and then flushes that console.
      @@ -99,6 +114,24 @@ public static String readln(String prompt) {
               return con().readln(prompt);
           }
      
      +    /**
      +     * Reads a single line of text from the system console.
      +     *
      +     * <p> The effect is as if {@link Console#readln() readln()}
      +     * had been called on {@code System.console()}.
      +     *
      +     * @return a string containing the line read from the system console, not
      +     * including any line-termination characters. Returns {@code null} if an
      +     * end of stream has been reached without having read any characters.
      +     *
      +     * @throws IOError if {@code System.console()} returns {@code null},
      +     *                 or if an I/O error occurs
      +     * @since 24
      +     */
      +    public static String readln() {
      +        return con().readln();
      +    }
      +
           private static Console con() {
               var con = System.console();
               if (con != null) {
      diff --git a/src/jdk.jshell/share/classes/jdk/jshell/JShellConsole.java b/src/jdk.jshell/share/classes/jdk/jshell/JShellConsole.java
      index fe73d6965cb97..014766f9ff7c4 100644
      --- a/src/jdk.jshell/share/classes/jdk/jshell/JShellConsole.java
      +++ b/src/jdk.jshell/share/classes/jdk/jshell/JShellConsole.java
      @@ -28,6 +28,7 @@
       import java.io.PrintWriter;
       import java.io.Reader;
       import java.nio.charset.Charset;
      +import jdk.internal.javac.PreviewFeature;
      
       /**
        * An interface providing functionality for {@link java.io.Console} in the user's snippet.
      @@ -75,6 +76,21 @@ public interface JShellConsole {
            */
           public String readLine(String prompt) throws IOError;
      
      +    /**
      +     * Reads a single line of text from the console.
      +     *
      +     * @throws IOError
      +     *         If an I/O error occurs.
      +     *
      +     * @return  A string containing the line read from the console, not
      +     *          including any line-termination characters, or {@code null}
      +     *          if an end of stream has been reached.
      +     * @see java.io.Console#readLine()
      +     * @since 24
      +     */
      +    @PreviewFeature(feature=PreviewFeature.Feature.IMPLICIT_CLASSES)
      +    public String readLine() throws IOError;
      +
           /**
            * Provides a prompt, then reads a password or passphrase from
            * the console with echoing disabled.

            jlahoda Jan Lahoda
            jlahoda Jan Lahoda
            Adam Sotona, Naoto Sato
            Votes:
            0 Vote for this issue
            Watchers:
            5 Start watching this issue

              Created:
              Updated:
              Resolved: