Package: java.lang

## [Java] Class Process

- java.lang.Process

-     public class Process
      extends Object

  GDK enhancements for Process.

  displayName:
    Process
  receiverFqcn:
    java.lang.Process

- - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `public void` | `closeStreams()` Closes all the streams associated with the process (ignoring any IOExceptions).
    `` | `public Thread` | `consumeProcessErrorStream(OutputStream err)` Gets the error stream from a process and reads it to keep the process from blocking due to a full buffer.
    `` | `public Thread` | `consumeProcessErrorStream(Appendable error)` Gets the error stream from a process and reads it to keep the process from blocking due to a full buffer.
    `` | `public Thread` | `consumeProcessErrorStream(Appendable error, Charset charset)` Gets the error stream from a process and reads it to keep the process from blocking due to a full buffer.
    `` | `public void` | `consumeProcessOutput()` Gets the output and error streams from a process and reads them to keep the process from blocking due to a full output buffer.
    `` | `public void` | `consumeProcessOutput(Appendable output, Appendable error)` Gets the output and error streams from a process and reads them to keep the process from blocking due to a full output buffer.
    `` | `public void` | `consumeProcessOutput(Appendable output, Appendable error, Charset charset)` Gets the output and error streams from a process and reads them to keep the process from blocking due to a full output buffer.
    `` | `public void` | `consumeProcessOutput(OutputStream output, OutputStream error)` Gets the output and error streams from a process and reads them to keep the process from blocking due to a full output buffer.
    `` | `public Thread` | `consumeProcessOutputStream(Appendable output)` Gets the output stream from a process and reads it to keep the process from blocking due to a full output buffer.
    `` | `public Thread` | `consumeProcessOutputStream(Appendable output, Charset charset)` Gets the output stream from a process and reads it to keep the process from blocking due to a full output buffer.
    `` | `public Thread` | `consumeProcessOutputStream(OutputStream output)` Gets the output stream from a process and reads it to keep the process from blocking due to a full output buffer.
    `` | `public InputStream` | `getErr()` An alias method so that a process appears similar to System.out, System.in, System.err; you can use process.in, process.out, process.err in a similar fashion.
    `` | `public InputStream` | `getIn()` An alias method so that a process appears similar to System.out, System.in, System.err; you can use process.in, process.out, process.err in a similar fashion.
    `` | `public OutputStream` | `getOut()` An alias method so that a process appears similar to System.out, System.in, System.err; you can use process.in, process.out, process.err in a similar fashion.
    `` | `public String` | `getText()` Read the text of the output stream of the Process, decoding using the operating system's native encoding (or {@value #PROCESS_ENCODING_PROPERTY} when set).
    `` | `public String` | `getText(Charset charset)` Read the text of the output stream of the Process using the given charset.
    `` | `public Writer` | `leftShift(Object value)` Overloads the left shift operator (<<) to provide an append mechanism to pipe data to a Process.
    `` | `public OutputStream` | `leftShift(byte[] value)` Overloads the left shift operator to provide an append mechanism to pipe into a Process
    `` | `public Process` | `onExit(Closure action)` Registers a closure to be called when the process terminates.
    `` | `public Process` | `or(Process right)` Overrides the or operator to allow one Process to asynchronously pipe data to another Process.
    `` | `public Process` | `pipeTo(Process right)` Allows one Process to asynchronously pipe data to another Process.
    `` | `public void` | `waitForOrKill(long numberOfMillis)` Wait for the process to finish during a certain amount of time, otherwise stops the process.
    `` | `public void` | `waitForProcessOutput()` Gets the output and error streams from a process and reads them to keep the process from blocking due to a full output buffer.
    `` | `public void` | `waitForProcessOutput(Appendable output, Appendable error)` Gets the output and error streams from a process and reads them to keep the process from blocking due to a full output buffer.
    `` | `public void` | `waitForProcessOutput(Appendable output, Appendable error, Charset charset)` Gets the output and error streams from a process and reads them to keep the process from blocking due to a full output buffer.
    `` | `public void` | `waitForProcessOutput(OutputStream output, OutputStream error)` Gets the output and error streams from a process and reads them to keep the process from blocking due to a full output buffer.
    `` | `public ProcessResult` | `waitForResult()` Executes the process and waits for it to complete, capturing the standard output, standard error, and exit code into a ProcessResult.
    `` | `public ProcessResult` | `waitForResult(Charset charset)` Executes the process and waits for it to complete, capturing the standard output and standard error decoded using the given charset, plus the exit code, into a ProcessResult.
    `` | `public ProcessResult` | `waitForResult(long timeout, TimeUnit unit)` Executes the process and waits for it to complete within the given timeout, capturing the standard output, standard error, and exit code into a ProcessResult.
    `` | `public ProcessResult` | `waitForResult(long timeout, TimeUnit unit, Charset charset)` Executes the process and waits for it to complete within the given timeout, capturing the standard output and standard error decoded using the given charset, plus the exit code, into a ProcessResult.
    `` | `public void` | `withOutputStream(Closure closure)` Creates a new buffered OutputStream as stdin for this process, passes it to the closure, and ensures the stream is flushed and closed after the closure returns.
    `` | `public void` | `withWriter(Closure closure)` Creates a new BufferedWriter as stdin for this process, passes it to the closure, and ensures the stream is flushed and closed after the closure returns.
    `` | `public void` | `withWriter(Charset charset, Closure closure)` Creates a new BufferedWriter as stdin for this process using the given charset, passes it to the closure, and ensures the stream is flushed and closed after the closure returns.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class Object` | `addShutdownHook, any, any, asBoolean, asType, clamp, clamp, collect, collect, collect, dump, each, eachMatch, eachMatch, eachWithIndex, every, every, find, find, findAll, findAll, findIndexOf, findIndexOf, findIndexValues, findIndexValues, findLastIndexOf, findLastIndexOf, findResult, findResult, findResult, findResult, getAt, getMetaClass, getMetaPropertyValues, getProperties, grep, grep, hasProperty, identity, inject, inject, inject, inject, inspect, invokeMethod, is, isCase, isNotCase, iterator, metaClass, print, print, printf, printf, println, println, println, putAt, respondsTo, respondsTo, setMetaClass, sleep, sleep, split, sprintf, sprintf, stream, takeIf, tap, toString, use, use, use, with, with, withCloseable, withCloseable, withMethodClosure, withStream, withStream, withTraits`

- - ### Method Detail

    - #### public void closeStreams()

      Closes all the streams associated with the process (ignoring any IOExceptions).

      Since:
        2.1

    - #### public Thread consumeProcessErrorStream(OutputStream err)

      Gets the error stream from a process and reads it to keep the process from blocking due to a full buffer. The processed stream data is appended to the supplied OutputStream. A new Thread is started, so this method will return immediately.

      Parameters:
        `err` - an OutputStream to capture the process stderr
      Returns:
        the Thread
      Since:
        1.5.2

    - #### public Thread consumeProcessErrorStream(Appendable error)

      Gets the error stream from a process and reads it to keep the process from blocking due to a full buffer. The processed stream data is appended to the supplied Appendable. A new Thread is started, so this method will return immediately.

      Parameters:
        `error` - an Appendable to capture the process stderr
      Returns:
        the Thread
      Since:
        1.7.5

    - #### public Thread consumeProcessErrorStream(Appendable error, Charset charset)

      Gets the error stream from a process and reads it to keep the process from blocking due to a full buffer. The stream data is decoded using the given charset and appended to the supplied Appendable. A new Thread is started, so this method will return immediately.

      Parameters:
        `error` - an Appendable to capture the process stderr
        `charset` - the charset the process writes its error output in
      Returns:
        the Thread
      Since:
        6.0.0

    - #### public void consumeProcessOutput()

      Gets the output and error streams from a process and reads them to keep the process from blocking due to a full output buffer. The stream data is thrown away but blocking due to a full output buffer is avoided. Use this method if you don't care about the standard or error output and just want the process to run silently - use carefully however, because since the stream data is thrown away, it might be difficult to track down when something goes wrong. For this, two Threads are started, so this method will return immediately.

      Since:
        1.0

    - #### public void consumeProcessOutput(Appendable output, Appendable error)

      Gets the output and error streams from a process and reads them to keep the process from blocking due to a full output buffer. The processed stream data is appended to the supplied Appendable. For this, two Threads are started, so this method will return immediately. The threads will not be join()ed, even if waitFor() is called. To wait for the output to be fully consumed call waitForProcessOutput().

      Parameters:
        `output` - an Appendable to capture the process stdout
        `error` - an Appendable to capture the process stderr
      Since:
        1.7.5

    - #### public void consumeProcessOutput(Appendable output, Appendable error, Charset charset)

      Gets the output and error streams from a process and reads them to keep the process from blocking due to a full output buffer. The processed stream data is decoded using the given charset and appended to the supplied Appendable. For this, two Threads are started, so this method will return immediately. The threads will not be join()ed, even if waitFor() is called. To wait for the output to be fully consumed call waitForProcessOutput().

      Parameters:
        `output` - an Appendable to capture the process stdout
        `error` - an Appendable to capture the process stderr
        `charset` - the charset the process writes its output in
      Since:
        6.0.0

    - #### public void consumeProcessOutput(OutputStream output, OutputStream error)

      Gets the output and error streams from a process and reads them to keep the process from blocking due to a full output buffer. The processed stream data is appended to the supplied OutputStream. For this, two Threads are started, so this method will return immediately. The threads will not be join()ed, even if waitFor() is called. To wait for the output to be fully consumed call waitForProcessOutput().

      Parameters:
        `output` - an OutputStream to capture the process stdout
        `error` - an OutputStream to capture the process stderr
      Since:
        1.5.2

    - #### public Thread consumeProcessOutputStream(Appendable output)

      Gets the output stream from a process and reads it to keep the process from blocking due to a full output buffer. The processed stream data is appended to the supplied Appendable. A new Thread is started, so this method will return immediately.

      Parameters:
        `output` - an Appendable to capture the process stdout
      Returns:
        the Thread
      Since:
        1.7.5

    - #### public Thread consumeProcessOutputStream(Appendable output, Charset charset)

      Gets the output stream from a process and reads it to keep the process from blocking due to a full output buffer. The stream data is decoded using the given charset and appended to the supplied Appendable. A new Thread is started, so this method will return immediately.

      Parameters:
        `output` - an Appendable to capture the process stdout
        `charset` - the charset the process writes its output in
      Returns:
        the Thread
      Since:
        6.0.0

    - #### public Thread consumeProcessOutputStream(OutputStream output)

      Gets the output stream from a process and reads it to keep the process from blocking due to a full output buffer. The processed stream data is appended to the supplied OutputStream. A new Thread is started, so this method will return immediately.

      Parameters:
        `output` - an OutputStream to capture the process stdout
      Returns:
        the Thread
      Since:
        1.5.2

    - #### public InputStream getErr()

      An alias method so that a process appears similar to System.out, System.in, System.err; you can use process.in, process.out, process.err in a similar fashion.

      Returns:
        the error InputStream for the process
      Since:
        1.0

    - #### public InputStream getIn()

      An alias method so that a process appears similar to System.out, System.in, System.err; you can use process.in, process.out, process.err in a similar fashion.

      Returns:
        the InputStream for the process
      Since:
        1.0

    - #### public OutputStream getOut()

      An alias method so that a process appears similar to System.out, System.in, System.err; you can use process.in, process.out, process.err in a similar fashion.

      Returns:
        the OutputStream for the process
      Since:
        1.0

    - #### public String getText()

      Read the text of the output stream of the Process, decoding using the operating system's native encoding (or {@value #PROCESS_ENCODING_PROPERTY} when set). Closes all the streams associated with the process after retrieving the text.

      throws:
        java.io.IOException if an IOException occurs.
      Returns:
        the text of the output
      Since:
        1.0

    - #### public String getText(Charset charset)

      Read the text of the output stream of the Process using the given charset. Closes all the streams associated with the process after retrieving the text.

      throws:
        java.io.IOException if an IOException occurs.
      Parameters:
        `charset` - the charset the process writes its output in, or null to use the process encoding
      Returns:
        the text of the output
      Since:
        6.0.0

    - #### public Writer leftShift(Object value)

      Overloads the left shift operator (<<) to provide an append mechanism to pipe data to a Process. The value is encoded using the operating system's native encoding (or {@value #PROCESS_ENCODING_PROPERTY} when set), which is what the child process expects to read.

      throws:
        java.io.IOException if an IOException occurs.
      Parameters:
        `value` - a value to append
      Returns:
        a Writer
      Since:
        1.0

    - #### public OutputStream leftShift(byte[] value)

      Overloads the left shift operator to provide an append mechanism to pipe into a Process

      throws:
        java.io.IOException if an IOException occurs.
      Parameters:
        `value` - data to append
      Returns:
        an OutputStream
      Since:
        1.0

    - #### public Process onExit(Closure action)

      Registers a closure to be called when the process terminates. Uses Process.onExit to asynchronously notify completion.

           "cmd".execute().onExit { proc ->
               println "Exited with code: ${proc.exitValue()}"
           }

      Parameters:
        `action` - a closure to call with the completed Process
      Returns:
        the Process to allow chaining
      Since:
        6.0.0

    - #### public Process or(Process right)

      Overrides the or operator to allow one Process to asynchronously pipe data to another Process.

      throws:
        java.io.IOException if an IOException occurs.
      Parameters:
        `right` - a Process to pipe output to
      Returns:
        the second Process to allow chaining
      Since:
        1.5.1

    - #### public Process pipeTo(Process right)

      Allows one Process to asynchronously pipe data to another Process.

      throws:
        java.io.IOException if an IOException occurs.
      Parameters:
        `right` - a Process to pipe output to
      Returns:
        the second Process to allow chaining
      Since:
        1.5.2

    - #### public void waitForOrKill(long numberOfMillis)

      Wait for the process to finish during a certain amount of time, otherwise stops the process.

      Parameters:
        `numberOfMillis` - the number of milliseconds to wait before stopping the process
      Since:
        1.0

    - #### public void waitForProcessOutput()

      Gets the output and error streams from a process and reads them to keep the process from blocking due to a full output buffer. The stream data is thrown away but blocking due to a full output buffer is avoided. Use this method if you don't care about the standard or error output and just want the process to run silently - use carefully however, because since the stream data is thrown away, it might be difficult to track down when something goes wrong. For this, two Threads are started, but join()ed, so we wait. As implied by the waitFor... name, we also wait until we finish as well. Finally, the output and error streams are closed.

      Since:
        1.6.5

    - #### public void waitForProcessOutput(Appendable output, Appendable error)

      Gets the output and error streams from a process and reads them to keep the process from blocking due to a full output buffer. The processed stream data is appended to the supplied Appendable. For this, two Threads are started, but join()ed, so we wait. As implied by the waitFor... name, we also wait until we finish as well. Finally, the input, output and error streams are closed.

      Parameters:
        `output` - an Appendable to capture the process stdout
        `error` - an Appendable to capture the process stderr
      Since:
        1.7.5

    - #### public void waitForProcessOutput(Appendable output, Appendable error, Charset charset)

      Gets the output and error streams from a process and reads them to keep the process from blocking due to a full output buffer. The processed stream data is decoded using the given charset and appended to the supplied Appendable. For this, two Threads are started, but join()ed, so we wait. As implied by the waitFor... name, we also wait until we finish as well. Finally, the input, output and error streams are closed.

      Parameters:
        `output` - an Appendable to capture the process stdout
        `error` - an Appendable to capture the process stderr
        `charset` - the charset the process writes its output in
      Since:
        6.0.0

    - #### public void waitForProcessOutput(OutputStream output, OutputStream error)

      Gets the output and error streams from a process and reads them to keep the process from blocking due to a full output buffer. The processed stream data is appended to the supplied OutputStream. For this, two Threads are started, but join()ed, so we wait. As implied by the waitFor... name, we also wait until we finish as well. Finally, the input, output and error streams are closed.

      Parameters:
        `output` - an OutputStream to capture the process stdout
        `error` - an OutputStream to capture the process stderr
      Since:
        1.6.5

    - #### public ProcessResult waitForResult()

      Executes the process and waits for it to complete, capturing the standard output, standard error, and exit code into a ProcessResult.

           def result = "ls -la".execute().waitForResult()
           if (result.ok) println result.out
           else System.err.println result.err

      throws:
        InterruptedException if the current thread is interrupted.
      Returns:
        a ProcessResult containing stdout, stderr, and exit code
      Since:
        6.0.0

    - #### public ProcessResult waitForResult(Charset charset)

      Executes the process and waits for it to complete, capturing the standard output and standard error decoded using the given charset, plus the exit code, into a ProcessResult.

      throws:
        InterruptedException if the current thread is interrupted.
      Parameters:
        `charset` - the charset the process writes its output in
      Returns:
        a ProcessResult containing stdout, stderr, and exit code
      Since:
        6.0.0

    - #### public ProcessResult waitForResult(long timeout, TimeUnit unit)

      Executes the process and waits for it to complete within the given timeout, capturing the standard output, standard error, and exit code into a ProcessResult. If the process does not complete within the timeout, it is forcibly destroyed.

           def result = "cmd".execute().waitForResult(30, TimeUnit.SECONDS)

      throws:
        InterruptedException if the current thread is interrupted.
      Parameters:
        `timeout` - the maximum time to wait
        `unit` - the time unit of the timeout argument
      Returns:
        a ProcessResult containing stdout, stderr, and exit code
      Since:
        6.0.0

    - #### public ProcessResult waitForResult(long timeout, TimeUnit unit, Charset charset)

      Executes the process and waits for it to complete within the given timeout, capturing the standard output and standard error decoded using the given charset, plus the exit code, into a ProcessResult. If the process does not complete within the timeout, it is forcibly destroyed.

      throws:
        InterruptedException if the current thread is interrupted.
      Parameters:
        `timeout` - the maximum time to wait
        `unit` - the time unit of the timeout argument
        `charset` - the charset the process writes its output in
      Returns:
        a ProcessResult containing stdout, stderr, and exit code
      Since:
        6.0.0

    - #### public void withOutputStream(Closure closure)

      Creates a new buffered OutputStream as stdin for this process, passes it to the closure, and ensures the stream is flushed and closed after the closure returns. A new Thread is started, so this method will return immediately.

      Parameters:
        `closure` - a closure
      Since:
        1.5.2

    - #### public void withWriter(Closure closure)

      Creates a new BufferedWriter as stdin for this process, passes it to the closure, and ensures the stream is flushed and closed after the closure returns. Text is encoded using the operating system's native encoding (or {@value #PROCESS_ENCODING_PROPERTY} when set). A new Thread is started, so this method will return immediately.

      Parameters:
        `closure` - a closure
      Since:
        1.5.2

    - #### public void withWriter(Charset charset, Closure closure)

      Creates a new BufferedWriter as stdin for this process using the given charset, passes it to the closure, and ensures the stream is flushed and closed after the closure returns. A new Thread is started, so this method will return immediately.

      Parameters:
        `charset` - the charset the process expects to read its input in
        `closure` - a closure
      Since:
        6.0.0