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

Add Reader and Writer access to java.lang.Process

    Details

    • Type: CSR
    • Status: Draft
    • Priority: P3
    • Resolution: Unresolved
    • Fix Version/s: tbd
    • Component/s: core-libs
    • Labels:
      None
    • Subcomponent:
    • Compatibility Kind:
      source
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      The new methods build on existing APIs and have minimal compatibility risk except the possibility that some existing subclass may have defined method with the same names and there is a conflict in the signatures
    • Interface Kind:
      Java API
    • Scope:
      SE

      Description

      Summary

      Process standard input, standard output, and standard error streams should be accessible as character streams using java.io.Reader and java.io.Writer.

      Problem

      The current access to the standard streams of processes use java.io.InputStream and java.io.OutputStream. Typically, applications wrap the streams using InputStreamReader and OutputStreamWriter to convert the bytes using the system default Charset. The lack of direct access to character streams and/or lines of process input and output requires each developer to reimplement the same code needed to conveniently access the streams.

      Solution

      Add methods to Process that return BufferedReader for the process output and error streams and a method to return a PrintWriter for the standard input to the process using the system default for Charset.

      BufferedReader provides convenient access to individual lines of output from the process and a fluent interface to utilize java.util.Stream functions to process process output as streams of strings.

      PrintWriter provides convenient methods for formatting objects and values to be sent to the process in addition to handling individual chars and arrays of chars.

      Specification

      New methods in java.lang.Process:

      +    /**
      +     * Returns a BufferedReader connected to the standard output of the process.
      +     * The reader decodes the standard output of this process using the
      +     * {@link Charset#defaultCharset() default charset}.
      +     *
      +     * <p>If the standard output of the process has been redirected using
      +     * {@link ProcessBuilder#redirectOutput(Redirect) ProcessBuilder.redirectOutput}
      +     * then this method will return a
      +     * <a href="ProcessBuilder.html#redirect-output">null input reader</a>.
      +     *
      +     * <p>Otherwise, if the standard error of the process has been redirected using
      +     * {@link ProcessBuilder#redirectErrorStream(boolean) ProcessBuilder.redirectErrorStream}
      +     * then the input stream returned by this method will receive the
      +     * merged standard output and the standard error of the process.
      +     *
      +     * @apiNote
      +     * Using both {@link #getInputStream} and {@link #inputReader} has unpredictable behavior
      +     * since the buffered reader reads ahead from the input stream.
      +     *
      +     * @implNote
      +     * This is equivalent to:
      +     * {@code
      +     *     return new BufferedReader(new InputStreamReader(getInputStream()));
      +     * }
      +     *
      +     * @return a BufferedReader using the default charset for the standard output
      +     *     of the process
      +     */
      +    public BufferedReader inputReader() {...}
      +
      +    /**
      +     * Returns a BufferedReader connected to the error output of the process.
      +     * The reader decodes the error output of this process using the
      +     * {@link Charset#defaultCharset() default charset}.
      +     *
      +     * <p>If the standard error of the process has been redirected using
      +     * {@link ProcessBuilder#redirectError(Redirect) ProcessBuilder.redirectError} or
      +     * {@link ProcessBuilder#redirectErrorStream(boolean)
      +     * ProcessBuilder.redirectErrorStream} then this method will return a
      +     * <a href="ProcessBuilder.html#redirect-output">null input reader</a>.
      +     *
      +     * @implNote
      +     * This is equivalent to:
      +     * {@code
      +     *     return new BufferedReader(new InputStreamReader(getErrorStream()));
      +     * }
      +     *
      +     * @apiNote
      +     * Using both {@link #getErrorStream} and {@link #errorReader} has unpredictable behavior
      +     * since the buffered reader reads ahead from the error stream.
      +     *
      +     * @return a BufferedReader using the default charset for the standard error
      +     *     of the process
      +     */
      +    public BufferedReader errorReader() {...}
      +
      +    /**
      +     * Returns a PrintWriter connected to the normal input of the process.
      +     * Characters written to the writer are converted to bytes using the
      +     * {@link Charset#defaultCharset() default charset} and piped into
      +     * the standard input of the process represented by this {@code Process} object.
      +     * The returned PrintWriter does <strong>not</strong> automatically flush.
      +     * Call the {@link PrintWriter#flush()} method to flush buffered output
      +     * to the process.
      +     *
      +     * <p>If the standard input of the process has been redirected using
      +     * {@link ProcessBuilder#redirectInput(Redirect)
      +     * ProcessBuilder.redirectInput} then this method will return a
      +     * <a href="ProcessBuilder.html#redirect-input">null output writer</a>.
      +     *
      +     * @implNote
      +     * This is equivalent to:
      +     * {@code
      +     *     return new PrintWriter(getOutputStream());
      +     * }
      +     *
      +     * @apiNote
      +     * Use {@link #getOutputStream} and {@link #outputWriter} with extreme care.
      +     * Output to the PrintWriter may be held in the buffer until
      +     * {@linkplain PrintWriter#flush flush} is called.
      +     *
      +     * @return a PrintWriter using the default charset to the standard input
      +     *     of the process
      +     */
      +    public PrintWriter outputWriter() {...}

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                rriggs Roger Riggs
                Reporter:
                rriggs Roger Riggs
                Reviewed By:
                Brian Burkhalter
              • Votes:
                0 Vote for this issue
                Watchers:
                3 Start watching this issue

                Dates

                • Created:
                  Updated: