Class TruffleProcessBuilder

java.lang.Object
com.oracle.truffle.api.io.TruffleProcessBuilder
public final class TruffleProcessBuilder extends Object
A builder used to create an external subprocess. The TruffleProcessBuilder instance allows to set subprocess attributes. The start() method creates a new Process instance with those attributes. The start() method can be invoked repeatedly from the same instance to create new subprocesses with the same attributes.
Since:
19.1.0

  • Method Details

    • command

      public TruffleProcessBuilder command(List<String> command)
      Sets the executable and arguments.
      Parameters:
      command - the list containing the executable and its arguments
      Returns:
      this builder
      Since:
      19.1.0

    • command

      public TruffleProcessBuilder command(String... command)
      Sets the executable and arguments.
      Parameters:
      command - the string array containing the executable and its arguments
      Returns:
      this builder
      Since:
      19.1.0

    • directory

      public TruffleProcessBuilder directory(TruffleFile currentWorkingDirectory)
      Sets this process current working directory. The currentWorkingDirectory may be null, in this case the subprocess current working directory is set to file system current working directory.
      Parameters:
      currentWorkingDirectory - the new current working directory
      Returns:
      this builder
      Since:
      19.1.0

    • redirectErrorStream

      public TruffleProcessBuilder redirectErrorStream(boolean enabled)
      If true the standard error output is merged into standard output.
      Parameters:
      enabled - enables merging of standard error output into standard output
      Returns:
      this builder
      Since:
      19.1.0

    • redirectInput

      public TruffleProcessBuilder redirectInput(org.graalvm.polyglot.io.ProcessHandler.Redirect source)
      Sets the standard input source. Process started by the start() method obtain its standard input from this source.

      If the source is PIPE, the default value, then the standard input of a subprocess can be written to using the output stream returned by Process.getOutputStream(). If the source is set to INHERIT, then the Process.getOutputStream() returns a closed output stream.

      Parameters:
      source - the new standard input source
      Returns:
      this builder
      Since:
      19.1.0

    • redirectOutput

      public TruffleProcessBuilder redirectOutput(org.graalvm.polyglot.io.ProcessHandler.Redirect destination)
      Sets the standard output destination. Process started by the start() method send its standard output to this destination.

      If the destination is PIPE, the default value, then the standard output of a subprocess can be read using the input stream returned by Process.getInputStream(). If the destination is set to is set to INHERIT, then Process.getInputStream() returns a closed input stream.

      Parameters:
      destination - the new standard output destination
      Returns:
      this builder
      Since:
      19.1.0

    • redirectError

      public TruffleProcessBuilder redirectError(org.graalvm.polyglot.io.ProcessHandler.Redirect destination)
      Sets the standard error output destination. Process started by the start() method send its error output to this destination.

      If the destination is PIPE, the default value, then the standard error of a subprocess can be read using the input stream returned by Process.getErrorStream(). If the destination is set to is set to INHERIT, then Process.getErrorStream() returns a closed input stream.

      Parameters:
      destination - the new error output destination
      Returns:
      this builder
      Since:
      19.1.0

    • inheritIO

      public TruffleProcessBuilder inheritIO(boolean enabled)
      If true the subprocess standard input, output and error output are the same as those of the current Java process.
      Parameters:
      enabled - enables standard I/O inheritance
      Returns:
      this builder
      Since:
      19.1.0

    • clearEnvironment

      public TruffleProcessBuilder clearEnvironment(boolean clear)
      If true the environment variables are not inherited by the subprocess.
      Parameters:
      clear - disables inheritance of environment variables
      Returns:
      this builder
      Since:
      19.1.0

    • environment

      public TruffleProcessBuilder environment(String name, String value)
      Sets the subprocess environment variable.
      Parameters:
      name - the variable name
      value - the value
      Returns:
      this builder
      Since:
      19.1.0

    • environment

      public TruffleProcessBuilder environment(Map<String,String> environment)
      Shortcut for setting multiple environment variables using a map. All values of the provided map must be non-null.
      Parameters:
      environment - environment variables
      Returns:
      this builder
      Since:
      19.1.0
      See Also:

    • createRedirectToStream

      public org.graalvm.polyglot.io.ProcessHandler.Redirect createRedirectToStream(OutputStream stream)
      Creates a redirect to write into the given OutputStream.

      It is guaranteed that the process output (error output) is copied into the given stream before the call to Process.waitFor() method ends.

      The stream is not closed when the process terminates.

      Parameters:
      stream - the OutputStream to write into
      Throws:
      NullPointerException - if the given stream is null
      Since:
      19.2.0

    • start

      public Process start() throws IOException
      Starts a new subprocess using the attributes of this builder. The new process invokes the command with arguments given by command(java.lang.String...), in a working directory given by directory(com.oracle.truffle.api.TruffleFile), with a process environment inherited from Context and possibly extended by environment(java.lang.String, java.lang.String).
      Returns:
      a new Process instance
      Throws:
      NullPointerException - if an element of the command list is null
      IndexOutOfBoundsException - if the command is an empty list
      SecurityException - when process creation is forbidden by ProcessHandler
      IOException - if the process fails to execute
      Since:
      19.1.0