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

Console methods with explicit Locale

    XMLWordPrintable

Details

    • CSR
    • Resolution: Approved
    • P4
    • 23
    • core-libs
    • None
    • source
    • minimal
    • These are new additional methods on a sealed class, thus no backward incompatibility is expected.
    • Java API
    • SE

    Description

      Summary

      Provide overload methods that take Locale argument in java.io.Console class

      Problem

      java.io.Console class offers methods to interact with the terminal. Both input and output methods have formatted strings for its prompt or output respectively. However, the current methods rely only on the default locale to produce localized formatted strings. Thus users would have to set the default locale in order to interact with the terminal in their preferred locale-sensitive format, such as date/time.

      Solution

      Introduce new overloaded methods to the existing methods that perform formatting operations. For example, add the following overloaded method to the existing printf() method.

      public Console printf(Locale locale, String format, Object... args);

      Specification

      Insert the following sentence in java.io.Console class description:

        * on the objects returned by {@link #reader()} and {@link #writer()} may
        * block in multithreaded scenarios.
        * <p>
      + * Operations that format strings are locale sensitive, using either the
      + * specified {@code Locale}, or the
      + * {@link Locale##default_locale default format Locale} to produce localized
      + * formatted strings.
      + * <p>
        * Invoking {@code close()} on the objects returned by the {@link #reader()}
        * and the {@link #writer()} will not close the underlying stream of those
        * objects.

      Add these new methods on java.io.Console class:

      /**
       * Writes a formatted string to this console's output stream using
       * the specified format string and arguments with the specified
       * {@code locale}.
       *
       * @param  locale The {@linkplain Locale locale} to apply during
       *         formatting.  If {@code locale} is {@code null} then no localization
       *         is applied.
       *
       * @param  format
       *         A format string as described in {@link
       *         Formatter##syntax Format string syntax}.
       *
       * @param  args
       *         Arguments referenced by the format specifiers in the format
       *         string.  If there are more arguments than format specifiers, the
       *         extra arguments are ignored.  The number of arguments is
       *         variable and may be zero.  The maximum number of arguments is
       *         limited by the maximum dimension of a Java array as defined by
       *         <cite>The Java Virtual Machine Specification</cite>.
       *         The behavior on a
       *         {@code null} argument depends on the {@link
       *         Formatter##syntax conversion}.
       *
       * @throws  IllegalFormatException
       *          If a format string contains an illegal syntax, a format
       *          specifier that is incompatible with the given arguments,
       *          insufficient arguments given the format string, or other
       *          illegal conditions.  For specification of all possible
       *          formatting errors, see the {@link
       *          Formatter##detail Details} section
       *          of the formatter class specification.
       *
       * @return  This console
       * @since   23
       */
      public Console format(Locale locale, String format, Object ... args)
      
      /**
       * A convenience method to write a formatted string to this console's
       * output stream using the specified format string and arguments with
       * the specified {@code locale}.
       *
       * @implSpec This is the same as calling
       *         {@code format(locale, format, args)}.
       *
       * @param  locale The {@linkplain Locale locale} to apply during
       *         formatting.  If {@code locale} is {@code null} then no localization
       *         is applied.
       *
       * @param  format
       *         A format string as described in {@link
       *         Formatter##syntax Format string syntax}.
       *
       * @param  args
       *         Arguments referenced by the format specifiers in the format
       *         string.  If there are more arguments than format specifiers, the
       *         extra arguments are ignored.  The number of arguments is
       *         variable and may be zero.  The maximum number of arguments is
       *         limited by the maximum dimension of a Java array as defined by
       *         <cite>The Java Virtual Machine Specification</cite>.
       *         The behavior on a
       *         {@code null} argument depends on the {@link
       *         Formatter##syntax conversion}.
       *
       * @throws  IllegalFormatException
       *          If a format string contains an illegal syntax, a format
       *          specifier that is incompatible with the given arguments,
       *          insufficient arguments given the format string, or other
       *          illegal conditions.  For specification of all possible
       *          formatting errors, see the {@link
       *          Formatter##detail Details} section of the
       *          formatter class specification.
       *
       * @return  This console
       * @since   23
       */
      public Console printf(Locale locale, String format, Object ... args)
      
      /**
       * Provides a formatted prompt using the specified {@code locale}, then
       * reads a single line of text from the console.
       *
       * @param  locale The {@linkplain Locale locale} to apply during
       *         formatting.  If {@code locale} is {@code null} then no localization
       *         is applied.
       *
       * @param  format
       *         A format string as described in {@link
       *         Formatter##syntax Format string syntax}.
       *
       * @param  args
       *         Arguments referenced by the format specifiers in the format
       *         string.  If there are more arguments than format specifiers, the
       *         extra arguments are ignored.  The number of arguments is
       *         variable and may be zero.  The maximum number of arguments is
       *         limited by the maximum dimension of a Java array as defined by
       *         <cite>The Java Virtual Machine Specification</cite>.
       *         The behavior on a
       *         {@code null} argument depends on the {@link
       *         Formatter##syntax conversion}.
       *
       * @throws  IllegalFormatException
       *          If a format string contains an illegal syntax, a format
       *          specifier that is incompatible with the given arguments,
       *          insufficient arguments given the format string, or other
       *          illegal conditions.  For specification of all possible
       *          formatting errors, see the {@link
       *          Formatter##detail Details} section of the
       *          of the formatter class specification.
       *
       * @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.
       * @since   23
       */
      public String readLine(Locale locale, String format, Object ... args)
      
      /**
       * Provides a formatted prompt using the specified {@code locale}, then
       * reads a password or passphrase from the console with echoing disabled.
       *
       * @param  locale The {@linkplain Locale locale} to apply during
       *         formatting.  If {@code locale} is {@code null} then no localization
       *         is applied.
       *
       * @param  format
       *         A format string as described in {@link
       *         Formatter##syntax Format string syntax}
       *         for the prompt text.
       *
       * @param  args
       *         Arguments referenced by the format specifiers in the format
       *         string.  If there are more arguments than format specifiers, the
       *         extra arguments are ignored.  The number of arguments is
       *         variable and may be zero.  The maximum number of arguments is
       *         limited by the maximum dimension of a Java array as defined by
       *         <cite>The Java Virtual Machine Specification</cite>.
       *         The behavior on a
       *         {@code null} argument depends on the {@link
       *         Formatter##syntax conversion}.
       *
       * @throws  IllegalFormatException
       *          If a format string contains an illegal syntax, a format
       *          specifier that is incompatible with the given arguments,
       *          insufficient arguments given the format string, or other
       *          illegal conditions.  For specification of all possible
       *          formatting errors, see the {@link
       *          Formatter##detail Details} section of the
       *          section of the formatter class specification.
       *
       * @throws IOError
       *         If an I/O error occurs.
       *
       * @return  A character array containing the password or passphrase read
       *          from the console, not including any line-termination characters,
       *          or {@code null} if an end of stream has been reached.
       * @since   23
       */
      public char[] readPassword(Locale locale, String format, Object ... args)

      Modify the existing method descriptions as follows:

      public Console format(String format, Object ... args):

            /**
             * Writes a formatted string to this console's output stream using
      -      * the specified format string and arguments.
      +      * the specified format string and arguments with the
      +      * {@link Locale##default_locale default format locale}.
      +      *

      public Console printf(String format, Object ... args):

            /**
             * A convenience method to write a formatted string to this console's
      -      * output stream using the specified format string and arguments.
      +      * output stream using the specified format string and arguments with
      +      * the {@link Locale##default_locale default format locale}.
             *
      -      * <p> An invocation of this method of the form
      -      * {@code con.printf(format, args)} behaves in exactly the same way
      -      * as the invocation of
      -      * {@snippet lang=java :
      -      *     con.format(format, args)
      -      * }
      +      * @implSpec This is the same as calling {@code format(format, args)}.
             *

      public String readLine(String format, Object ... args):

            /**
      -      * Provides a formatted prompt, then reads a single line of text from the
      -      * console.
      +      * Provides a formatted prompt using the
      +      * {@link Locale##default_locale default format locale}, then reads a
      +      * single line of text from the console.

      public char[] readPassword(String format, Object ... args):

            /**
      -      * Provides a formatted prompt, then reads a password or passphrase from
      -      * the console with echoing disabled.
      +      * Provides a formatted prompt using the
      +      * {@link Locale##default_locale default format locale}, then reads a
      +      * password or passphrase from the console with echoing disabled.

      For those existing methods that take args argument, replace the @param description with:

       * @param  args
       *         Arguments referenced by the format specifiers in the format
       *         string.  If there are more arguments than format specifiers, the
       *         extra arguments are ignored.  The number of arguments is
       *         variable and may be zero.  The maximum number of arguments is
       *         limited by the maximum dimension of a Java array as defined by
       *         <cite>The Java Virtual Machine Specification</cite>.
       *         The behavior on a
       *         {@code null} argument depends on the {@link
       *         Formatter##syntax conversion}.

      Attachments

        Issue Links

          Activity

            People

              naoto Naoto Sato
              naoto Naoto Sato
              Alan Bateman, Joe Wang
              Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved: