Process

public Process()

getOutputStream

public abstract OutputStream getOutputStream()

API Note:

When writing to both getOutputStream() and either outputWriter() or outputWriter(Charset), BufferedWriter.flush should be called before writes to the OutputStream.

Implementation Note:

Implementation note: It is a good idea for the returned output stream to be buffered.

Returns:

the output stream connected to the normal input of the process

getInputStream

public abstract InputStream getInputStream()

API Note:

Use getInputStream() and inputReader() with extreme care. The BufferedReader may have buffered input from the input stream.

Implementation Note:

Implementation note: It is a good idea for the returned input stream to be buffered.

Returns:

the input stream connected to the normal output of the process

getErrorStream

public abstract InputStream getErrorStream()

API Note:

Use getErrorStream() and errorReader() with extreme care. The BufferedReader may have buffered input from the error stream.

Implementation Note:

Implementation note: It is a good idea for the returned input stream to be buffered.

Returns:

the input stream connected to the error output of the process

inputReader

public final BufferedReader inputReader()

Returns:

a BufferedReader using the native.encoding if supported, otherwise, the Charset.defaultCharset()

Since:

17

inputReader

public final BufferedReader inputReader(Charset charset)

API Note:

Using both getInputStream() and inputReader(Charset) has unpredictable behavior since the buffered reader reads ahead from the input stream.

When the process has terminated, and the standard input has not been redirected, reading of the bytes available from the underlying stream is on a best effort basis and may be unpredictable.

Parameters:

charset - the Charset used to decode bytes to characters

Returns:

a BufferedReader for the standard output of the process using the charset

Throws:

NullPointerException - if the charset is null

IllegalStateException - if called more than once with different charset arguments

Since:

17

errorReader

public final BufferedReader errorReader()

Returns:

a BufferedReader using the native.encoding if supported, otherwise, the Charset.defaultCharset()

Since:

17

errorReader

public final BufferedReader errorReader(Charset charset)

API Note:

Using both getErrorStream() and errorReader(Charset) has unpredictable behavior since the buffered reader reads ahead from the error stream.

When the process has terminated, and the standard error has not been redirected, reading of the bytes available from the underlying stream is on a best effort basis and may be unpredictable.

Parameters:

charset - the Charset used to decode bytes to characters

Returns:

a BufferedReader for the standard error of the process using the charset

Throws:

NullPointerException - if the charset is null

IllegalStateException - if called more than once with different charset arguments

Since:

17

outputWriter

public final BufferedWriter outputWriter()

Returns:

a BufferedWriter to the standard input of the process using the charset for the native.encoding system property

Since:

17

outputWriter

public final BufferedWriter outputWriter(Charset charset)

API Note:

A BufferedWriter writes characters, arrays of characters, and strings. Wrapping the BufferedWriter with a PrintWriter provides efficient buffering and formatting of primitives and objects as well as support for auto-flush on line endings. Call the BufferedWriter.flush() method to flush buffered output to the process.

When writing to both getOutputStream() and either outputWriter() or outputWriter(Charset), BufferedWriter.flush should be called before writes to the OutputStream.

Parameters:

charset - the Charset to encode characters to bytes

Returns:

a BufferedWriter to the standard input of the process using the charset

Throws:

NullPointerException - if the charset is null

IllegalStateException - if called more than once with different charset arguments

Since:

17

waitFor

public abstract int waitFor() throws InterruptedException

Returns:

the exit value of the process represented by this Process object. By convention, the value 0 indicates normal termination.

Throws:

InterruptedException - if the current thread is interrupted by another thread while it is waiting, then the wait is ended and an InterruptedException is thrown.

waitFor

public boolean waitFor(long timeout, TimeUnit unit) throws InterruptedException

Parameters:

timeout - the maximum time to wait

unit - the time unit of the timeout argument

Returns:

true if the process has exited and false if the waiting time elapsed before the process has exited.

Throws:

InterruptedException - if the current thread is interrupted while waiting.

NullPointerException - if unit is null

Since:

1.8

exitValue

public abstract int exitValue()

Returns:

the exit value of the process represented by this Process object. By convention, the value 0 indicates normal termination.

Throws:

IllegalThreadStateException - if the process represented by this Process object has not yet terminated

destroy

public abstract void destroy()

destroyForcibly

public Process destroyForcibly()

API Note:

The process may not terminate immediately. i.e. isAlive() may return true for a brief period after destroyForcibly() is called. This method may be chained to waitFor() if needed.

Implementation Requirements:

The default implementation of this method invokes destroy() and so may not forcibly terminate the process.

Implementation Note:

Concrete implementations of this class are strongly encouraged to override this method with a compliant implementation.

Returns:

the Process object representing the process forcibly destroyed

Since:

1.8

supportsNormalTermination

public boolean supportsNormalTermination()

Implementation Requirements:

This implementation throws an instance of UnsupportedOperationException and performs no other action.

Returns:

true if the implementation of destroy() is to normally terminate the process; otherwise, destroy() forcibly terminates the process

Throws:

UnsupportedOperationException - if the Process implementation does not support this operation

Since:

9

isAlive

public boolean isAlive()

Returns:

true if the process represented by this Process object has not yet terminated.

Since:

1.8

pid

public long pid()

Implementation Requirements:

The implementation of this method returns the process id as: toHandle().pid().

Returns:

the native process id of the process

Throws:

UnsupportedOperationException - if the Process implementation does not support this operation

Since:

9

onExit

public CompletableFuture<Process> onExit()

API Note:

Using onExit is an alternative to waitFor that enables both additional concurrency and convenient access to the result of the Process. Lambda expressions can be used to evaluate the result of the Process execution. If there is other processing to be done before the value is used then onExit is a convenient mechanism to free the current thread and block only if and when the value is needed.
For example, launching a process to compare two files and get a boolean if they are identical:

   Process p = new ProcessBuilder("cmp", "f1", "f2").start();
    Future<Boolean> identical = p.onExit().thenApply(p1 -> p1.exitValue() == 0);
    ...
    if (identical.get()) { ... }
 

, The process may be observed to have terminated with isAlive() before the ComputableFuture is completed and dependent actions are invoked.

Implementation Requirements:

This implementation executes waitFor() in a separate thread repeatedly until it returns successfully. If the execution of waitFor is interrupted, the thread's interrupt status is preserved.

When waitFor() returns successfully the CompletableFuture is completed regardless of the exit status of the process. This implementation may consume a lot of memory for thread stacks if a large number of processes are waited for concurrently.

External implementations should override this method and provide a more efficient implementation. For example, to delegate to the underlying process, it can do the following:

    public CompletableFuture<Process> onExit() {
       return delegate.onExit().thenApply(p -> this);
    }
 

Returns:

a new CompletableFuture<Process> for the Process

Since:

9

toHandle

public ProcessHandle toHandle()

Implementation Requirements:

This implementation throws an instance of UnsupportedOperationException and performs no other action. Subclasses should override this method to provide a ProcessHandle for the process. The methods pid(), info(), children(), and descendants(), unless overridden, operate on the ProcessHandle.

Returns:

Returns a ProcessHandle for the Process

Throws:

UnsupportedOperationException - if the Process implementation does not support this operation

SecurityException - if a security manager has been installed and it denies RuntimePermission("manageProcess")

Since:

9

info

public ProcessHandle.Info info()

Implementation Requirements:

This implementation returns information about the process as: toHandle().info().

Returns:

a snapshot of information about the process, always non-null

Throws:

UnsupportedOperationException - if the Process implementation does not support this operation

Since:

9

children

public Stream<ProcessHandle> children()

Implementation Requirements:

This implementation returns the direct children as: toHandle().children().

Returns:

a sequential Stream of ProcessHandles for processes that are direct children of the process

Throws:

UnsupportedOperationException - if the Process implementation does not support this operation

SecurityException - if a security manager has been installed and it denies RuntimePermission("manageProcess")

Since:

9

descendants

public Stream<ProcessHandle> descendants()

Implementation Requirements:

This implementation returns all children as: toHandle().descendants().

Returns:

a sequential Stream of ProcessHandles for processes that are descendants of the process

Throws:

UnsupportedOperationException - if the Process implementation does not support this operation

SecurityException - if a security manager has been installed and it denies RuntimePermission("manageProcess")

Since:

9