-
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
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() {...}
- csr of
-
JDK-8191441 (Process) add Readers and Writer access to java.lang.Process streams
-
- Open
-