com.oracle.truffle.api.io

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 TruffleProcessBuilder.start() method creates a new Process instance with those attributes. The TruffleProcessBuilder.start() method can be invoked repeatedly from the same instance to create new subprocesses with the same attributes.

Since:

19.1.0

Method Summary

Modifier and Type	Method and Description
TruffleProcessBuilder	clearEnvironment(boolean clear) If true the environment variables are not inherited by the subprocess.
TruffleProcessBuilder	command(List<String> command) Sets the executable and arguments.
TruffleProcessBuilder	command(String... command) Sets the executable and arguments.
ProcessHandler.Redirect	createRedirectToStream(OutputStream stream) Creates a redirect to write into the given OutputStream.
TruffleProcessBuilder	directory(TruffleFile currentWorkingDirectory) Sets this process current working directory.
TruffleProcessBuilder	environment(Map<String,String> environment) Shortcut for setting multiple environment variables using a map.
TruffleProcessBuilder	environment(String name, String value) Sets the subprocess environment variable.
TruffleProcessBuilder	inheritIO(boolean enabled) If true the subprocess standard input, output and error output are the same as those of the current Java process.
TruffleProcessBuilder	redirectError(ProcessHandler.Redirect destination) Sets the standard error output destination.
TruffleProcessBuilder	redirectErrorStream(boolean enabled) If true the standard error output is merged into standard output.
TruffleProcessBuilder	redirectInput(ProcessHandler.Redirect source) Sets the standard input source.
TruffleProcessBuilder	redirectOutput(ProcessHandler.Redirect destination) Sets the standard output destination.
Process	start() Starts a new subprocess using the attributes of this builder.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

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(ProcessHandler.Redirect source)

Sets the standard input source. Process started by the TruffleProcessBuilder.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(ProcessHandler.Redirect destination)

Sets the standard output destination. Process started by the TruffleProcessBuilder.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(ProcessHandler.Redirect destination)

Sets the standard error output destination. Process started by the TruffleProcessBuilder.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:

To set a single environment variable.

createRedirectToStream

public 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 TruffleProcessBuilder.command(java.lang.String...), in a working directory given by TruffleProcessBuilder.directory(com.oracle.truffle.api.TruffleFile), with a process environment inherited from Context and possibly extended by TruffleProcessBuilder.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