Class Process

java.lang.Object
java.lang.Process
public abstract classProcessextendsObject
Process provides control of native processes started by ProcessBuilder.start and Runtime.exec. The class provides methods for performing input from the process, performing output to the process, waiting for the process to complete, checking the exit status of the process, and destroying (killing) the process. TheProcessBuilder.start() andRuntime.exec methods create a native process and return an instance of a subclass ofProcess that can be used to control the process and obtain information about it.

The methods that create processes may not work well for special processes on certain native platforms, such as native windowing processes, daemon processes, Win16/DOS processes on Microsoft Windows, or shell scripts.

By default, the created process does not have its own terminal or console. All its standard I/O (i.e. stdin, stdout, stderr) operations will be redirected to the parent process, where they can be accessed via the streams obtained using the methodsgetOutputStream(),getInputStream(), andgetErrorStream(). The I/O streams of characters and lines can be written and read using the methodsoutputWriter(),outputWriter(Charset),inputReader(),inputReader(Charset),errorReader(), anderrorReader(Charset). The parent process uses these streams to feed input to and get output from the process. Because some native platforms only provide limited buffer size for standard input and output streams, failure to promptly write the input stream or read the output stream of the process may cause the process to block, or even deadlock.

Where desired, process I/O can also be redirected using methods of theProcessBuilder class.

The process is not killed when there are no more references to theProcess object, but rather the process continues executing asynchronously.

There is no requirement that the process represented by a Process object execute asynchronously or concurrently with respect to the Java process that owns theProcess object.

As of 1.5,ProcessBuilder.start() is the preferred way to create aProcess.

Subclasses of Process should override theonExit() andtoHandle() methods to provide a fully functional Process including theprocess id,information about the process,direct children, anddirect children plus descendants of those children of the process. Delegating to the underlying Process or ProcessHandle is typically easiest and most efficient.

Since:
1.0

  • Constructor Details

    • Process

      public Process()
      Default constructor for Process.

  • Method Details

    • getOutputStream

      public abstract OutputStream getOutputStream()
      Returns the output stream connected to the normal input of the process. Output to the stream is piped into the standard input of the process represented by thisProcess object.

      If the standard input of the process has been redirected usingProcessBuilder.redirectInput then this method will return anull output stream.

      API Note:
      When writing to bothgetOutputStream() and eitheroutputWriter() oroutputWriter(Charset),BufferedWriter.flush should be called before writes to theOutputStream.
      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()
      Returns the input stream connected to the normal output of the process. The stream obtains data piped from the standard output of the process represented by thisProcess object.

      If the standard output of the process has been redirected usingProcessBuilder.redirectOutput then this method will return anull input stream.

      Otherwise, if the standard error of the process has been redirected usingProcessBuilder.redirectErrorStream then the input stream returned by this method will receive the merged standard output and the standard error of the process.

      API Note:
      UsegetInputStream() andinputReader() with extreme care. TheBufferedReader 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()
      Returns the input stream connected to the error output of the process. The stream obtains data piped from the error output of the process represented by thisProcess object.

      If the standard error of the process has been redirected usingProcessBuilder.redirectError orProcessBuilder.redirectErrorStream then this method will return anull input stream.

      API Note:
      UsegetErrorStream() anderrorReader() with extreme care. TheBufferedReader 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 aBufferedReader connected to the standard output of the process. TheCharset for the native encoding is used to read characters, lines, or stream lines from standard output.

      This method delegates toinputReader(Charset) using theCharset named by thenative.encoding system property. If thenative.encoding is not a valid charset name or not supported theCharset.defaultCharset() is used.

      Returns:
      aBufferedReader using thenative.encoding if supported, otherwise, theCharset.defaultCharset()
      Since:
      17

    • inputReader

      public final BufferedReader inputReader(Charset charset)
      Returns aBufferedReader connected to the standard output of this process using a Charset. TheBufferedReader can be used to read characters, lines, or stream lines of the standard output.

      Characters are read by an InputStreamReader that reads and decodes bytes from this processgetInputStream(). Bytes are decoded to characters using thecharset; malformed-input and unmappable-character sequences are replaced with the charset's default replacement. TheBufferedReader reads and buffers characters from the InputStreamReader.

      The first call to this method creates theBufferedReader, if called again with the samecharset the sameBufferedReader is returned. It is an error to call this method again with a differentcharset.

      If the standard output of the process has been redirected usingProcessBuilder.redirectOutput then theInputStreamReader will be reading from anull input stream.

      Otherwise, if the standard error of the process has been redirected usingProcessBuilder.redirectErrorStream then the input reader returned by this method will receive the merged standard output and the standard error of the process.

      API Note:
      Using bothgetInputStream() andinputReader(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 - theCharset used to decode bytes to characters
      Returns:
      aBufferedReader for the standard output of the process using thecharset
      Throws:
      NullPointerException - if thecharset isnull
      IllegalStateException - if called more than once with different charset arguments
      Since:
      17

    • errorReader

      public final BufferedReader errorReader()
      Returns aBufferedReader connected to the standard error of the process. TheCharset for the native encoding is used to read characters, lines, or stream lines from standard error.

      This method delegates toerrorReader(Charset) using theCharset named by thenative.encoding system property. If thenative.encoding is not a valid charset name or not supported theCharset.defaultCharset() is used.

      Returns:
      aBufferedReader using thenative.encoding if supported, otherwise, theCharset.defaultCharset()
      Since:
      17

    • errorReader

      public final BufferedReader errorReader(Charset charset)
      Returns aBufferedReader connected to the standard error of this process using a Charset. TheBufferedReader can be used to read characters, lines, or stream lines of the standard error.

      Characters are read by an InputStreamReader that reads and decodes bytes from this processgetErrorStream(). Bytes are decoded to characters using thecharset; malformed-input and unmappable-character sequences are replaced with the charset's default replacement. TheBufferedReader reads and buffers characters from the InputStreamReader.

      The first call to this method creates theBufferedReader, if called again with the samecharset the sameBufferedReader is returned. It is an error to call this method again with a differentcharset.

      If the standard error of the process has been redirected usingProcessBuilder.redirectError orProcessBuilder.redirectErrorStream then theInputStreamReader will be reading from anull input stream.

      API Note:
      Using bothgetErrorStream() anderrorReader(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 - theCharset used to decode bytes to characters
      Returns:
      aBufferedReader for the standard error of the process using thecharset
      Throws:
      NullPointerException - if thecharset isnull
      IllegalStateException - if called more than once with different charset arguments
      Since:
      17

    • outputWriter

      public final BufferedWriter outputWriter()
      Returns aBufferedWriter connected to the normal input of the process using the native encoding. Writes text to a character-output stream, buffering characters so as to provide for the efficient writing of single characters, arrays, and strings.

      This method delegates tooutputWriter(Charset) using theCharset named by thenative.encoding system property. If thenative.encoding is not a valid charset name or not supported theCharset.defaultCharset() is used.

      Returns:
      aBufferedWriter to the standard input of the process using the charset for thenative.encoding system property
      Since:
      17

    • outputWriter

      public final BufferedWriter outputWriter(Charset charset)
      Returns aBufferedWriter connected to the normal input of the process using a Charset. Writes text to a character-output stream, buffering characters so as to provide for the efficient writing of single characters, arrays, and strings.

      Characters written by the writer are encoded to bytes usingOutputStreamWriter and theCharset are written to the standard input of the process represented by thisProcess. Malformed-input and unmappable-character sequences are replaced with the charset's default replacement.

      The first call to this method creates theBufferedWriter, if called again with the samecharset the sameBufferedWriter is returned. It is an error to call this method again with a differentcharset.

      If the standard input of the process has been redirected usingProcessBuilder.redirectInput then theOutputStreamWriter writes to anull output stream.

      API Note:
      ABufferedWriter writes characters, arrays of characters, and strings. Wrapping theBufferedWriter with aPrintWriter provides efficient buffering and formatting of primitives and objects as well as support for auto-flush on line endings. Call theBufferedWriter.flush() method to flush buffered output to the process.

      When writing to bothgetOutputStream() and eitheroutputWriter() oroutputWriter(Charset),BufferedWriter.flush should be called before writes to theOutputStream.

      Parameters:
      charset - theCharset to encode characters to bytes
      Returns:
      aBufferedWriter to the standard input of the process using thecharset
      Throws:
      NullPointerException - if thecharset isnull
      IllegalStateException - if called more than once with different charset arguments
      Since:
      17

    • waitFor

      public abstract int waitFor() throwsInterruptedException
      Causes the current thread to wait, if necessary, until the process represented by thisProcess object has terminated. This method returns immediately if the process has already terminated. If the process has not yet terminated, the calling thread will be blocked until the process exits.
      Returns:
      the exit value of the process represented by thisProcess object. By convention, the value0 indicates normal termination.
      Throws:
      InterruptedException - if the current thread isinterrupted by another thread while it is waiting, then the wait is ended and anInterruptedException is thrown.

    • waitFor

      public boolean waitFor(long timeout,TimeUnit unit) throwsInterruptedException
      Causes the current thread to wait, if necessary, until the process represented by thisProcess object has terminated, or the specified waiting time elapses.

      If the process has already terminated then this method returns immediately with the valuetrue. If the process has not terminated and the timeout value is less than, or equal to, zero, then this method returns immediately with the valuefalse.

      Implementation Requirements:
      The default implementation of this method polls theexitValue to check if the process has terminated.
      Implementation Note:
      Concrete implementations of this class are strongly encouraged to override this method with a more efficient implementation.
      Parameters:
      timeout - the maximum time to wait
      unit - the time unit of thetimeout argument
      Returns:
      true if the process has exited andfalse 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

    • waitFor

      public boolean waitFor(Duration duration) throwsInterruptedException
      Causes the current thread to wait, if necessary, until the process represented by thisProcess object has terminated, or the specified waiting duration elapses.

      If the process has already terminated then this method returns immediately with the valuetrue. If the process has not terminated and the duration is not positive, then this method returns immediately with the valuefalse.

      Implementation Requirements:
      The default implementation of this method polls theexitValue to check if the process has terminated.
      Implementation Note:
      Concrete implementations of this class are strongly encouraged to override this method with a more efficient implementation.
      Parameters:
      duration - the maximum duration to wait; if not positive, this method returns immediately.
      Returns:
      true if the process has exited andfalse if the waiting duration elapsed before the process has exited.
      Throws:
      InterruptedException - if the current thread is interrupted while waiting.
      NullPointerException - if duration is null
      Since:
      24

    • exitValue

      public abstract int exitValue()
      Returns the exit value for the process.
      Returns:
      the exit value of the process represented by thisProcess object. By convention, the value0 indicates normal termination.
      Throws:
      IllegalThreadStateException - if the process represented by thisProcess object has not yet terminated

    • destroy

      public abstract void destroy()
      Kills the process. Whether the process represented by thisProcess object isnormally terminated or not is implementation dependent. Forcible process destruction is defined as the immediate termination of a process, whereas normal termination allows the process to shut down cleanly. If the process is not alive, no action is taken.

      TheCompletableFuture fromonExit() iscompleted when the process has terminated.

    • destroyForcibly

      public Process destroyForcibly()
      Kills the process forcibly. The process represented by thisProcess object is forcibly terminated. Forcible process destruction is defined as the immediate termination of a process, whereas normal termination allows the process to shut down cleanly. If the process is not alive, no action is taken.

      TheCompletableFuture fromonExit() iscompleted when the process has terminated.

      Invoking this method onProcess objects returned byProcessBuilder.start() andRuntime.exec(java.lang.String) forcibly terminate the process.

      API Note:
      The process may not terminate immediately. i.e.isAlive() may return true for a brief period afterdestroyForcibly() is called. This method may be chained towaitFor() if needed.
      Implementation Requirements:
      The default implementation of this method invokesdestroy() 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:
      theProcess object representing the process forcibly destroyed
      Since:
      1.8

    • supportsNormalTermination

      public boolean supportsNormalTermination()
      Returnstrue if the implementation ofdestroy() is to normally terminate the process, Returnsfalse if the implementation ofdestroy forcibly and immediately terminates the process.

      Invoking this method onProcess objects returned byProcessBuilder.start() andRuntime.exec(java.lang.String) returntrue orfalse depending on the platform implementation.

      Implementation Requirements:
      This implementation throws an instance ofUnsupportedOperationException and performs no other action.
      Returns:
      true if the implementation ofdestroy() 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()
      Tests whether the process represented by thisProcess is alive.
      Returns:
      true if the process represented by thisProcess object has not yet terminated.
      Since:
      1.8

    • pid

      public long pid()
      Returns the native process ID of the process. The native process ID is an identification number that the operating system assigns to the process.
      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()
      Returns aCompletableFuture<Process> for the termination of the Process. TheCompletableFuture provides the ability to trigger dependent functions or actions that may be run synchronously or asynchronously upon process termination. When the process has terminated the CompletableFuture iscompleted regardless of the exit status of the process.

      CallingonExit().get() waits for the process to terminate and returns the Process. The future can be used to check if the process isdone or towait for it to terminate.Cancelling the CompletableFuture does not affect the Process.

      Processes returned fromProcessBuilder.start() override the default implementation to provide an efficient mechanism to wait for process exit.

      API Note:
      UsingonExit is an alternative towaitFor 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 thenonExit 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 withisAlive() before the ComputableFuture is completed and dependent actions are invoked.
      Implementation Requirements:
      This implementation executeswaitFor() in a separate thread repeatedly until it returns successfully. If the execution ofwaitFor is interrupted, the thread's interrupt status is preserved.

      WhenwaitFor() returns successfully the CompletableFuture iscompleted 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 newCompletableFuture<Process> for the Process
      Since:
      9

    • toHandle

      public ProcessHandle toHandle()
      Returns a ProcessHandle for the Process.Process objects returned byProcessBuilder.start() andRuntime.exec(java.lang.String) implementtoHandle as the equivalent ofProcessHandle.of(pid).
      Implementation Requirements:
      This implementation throws an instance ofUnsupportedOperationException and performs no other action. Subclasses should override this method to provide a ProcessHandle for the process. The methodspid(),info(),children(), anddescendants(), unless overridden, operate on the ProcessHandle.
      Returns:
      Returns a ProcessHandle for the Process
      Throws:
      UnsupportedOperationException - if the Process implementation does not support this operation
      Since:
      9

    • info

      public ProcessHandle.Info info()
      Returns a snapshot of information about the process.

      AProcessHandle.Info instance has accessor methods that return information about the process if it is available.

      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()
      Returns a snapshot of the direct children of the process. The parent of a direct child process is the process. Typically, a process that isnot alive has no children.

      Note that processes are created and terminate asynchronously. There is no guarantee that a process isalive.

      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
      Since:
      9

    • descendants

      public Stream<ProcessHandle> descendants()
      Returns a snapshot of the descendants of the process. The descendants of a process are the children of the process plus the descendants of those children, recursively. Typically, a process that isnot alive has no children.

      Note that processes are created and terminate asynchronously. There is no guarantee that a process isalive.

      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
      Since:
      9