java.lang
public final class ProcessBuilder extends Object
This class is used to construct new operating system processes.
A ProcessBuilder instance basically represent a
template for a new process. Actual processes are generated from
this template via use of the start() method, which
may be invoked multiple times, with each invocation spawning a
new process with the current attributes of the
ProcessBuilder object. Each spawned process is
independent of the ProcessBuilder object, and is
unaffected by changes in its attributes.
The following attributes define a process:
user.dir property.find -type f
invokes the find binary with the arguments "-type" and "f".
The command is provided a list, the elements of which are defined in a
system dependent manner; the layout is affected by expected operating
system conventions. A common method is to split the command on each
space within the string. Thus, find -type f forms a
three element list. However, in some cases, the expectation is that
this split is performed by the program itself; thus, the list consists
of only two elements (the program name and its arguments).System.getenv().
All checks on attribute validity are delayed until start()
is called. ProcessBuilder objects are not
synchronized; the user must provide external synchronization
where multiple threads may interact with the same
ProcessBuilder object.
Since: 1.5
| Constructor Summary | |
|---|---|
| ProcessBuilder(List<String> command)
Constructs a new ProcessBuilder with the specified
command being used to invoke the process. | |
| ProcessBuilder(String... command)
Constructs a new ProcessBuilder with the specified
command being used to invoke the process. | |
| Method Summary | |
|---|---|
| List<String> | command()
Returns the current command line, used to invoke the process.
|
| ProcessBuilder | command(List<String> command)
Sets the command-line arguments to those specified. |
| ProcessBuilder | command(String... command)
Sets the command-line arguments to those specified.
|
| File | directory()
Returns the working directory of the process. |
| ProcessBuilder | directory(File directory)
Sets the working directory to that specified.
|
| Map<String,String> | environment() Returns the system environment variables of the process. |
| boolean | redirectErrorStream()
Returns true if the output stream and error stream of the
process will be merged to form one composite stream. |
| ProcessBuilder | redirectErrorStream(boolean redirect)
Sets the error stream redirection flag. |
| Process | start()
Starts execution of a new process, based on the attributes of
this |
ProcessBuilder with the specified
command being used to invoke the process. The list is used directly;
external changes are reflected in the ProcessBuilder.
Parameters: command the name of the program followed by its arguments.
ProcessBuilder with the specified
command being used to invoke the process. This constructor
simplifies creating a new ProcessBuilder by
converting the provided series of constructor arguments into a
list of command-line arguments.
Parameters: command the name of the program followed by its arguments.
ProcessBuilder object;
any changes made to it will be reflected in the operation of
the ProcessBuilder.
Returns: the list of command-line arguments.
ProcessBuilder.
Parameters: command the name of the program followed by its arguments.
Returns: a reference to this process builder.
Parameters: command the name of the program followed by its arguments.
Returns: a reference to this process builder.
null; this
indicates that the default behaviour of using the
working directory of the current process should
be adopted.
Returns: the working directory.
null,
which indicates the default value should be used.
The default is the working directory of the current
process.
Parameters: directory the new working directory.
Returns: a reference to this process builder.
Returns the system environment variables of the process. If the underlying system does not support environment variables, an empty map is returned.
The returned map does not accept queries using
null keys or values, or those of a type other than
String. Attempts to pass in a null value will
throw a NullPointerException. Types other than
String throw a ClassCastException.
As the returned map is generated using data from the underlying
platform, it may not comply with the equals()
and hashCode() contracts. It is also likely that
the keys of this map will be case-sensitive.
Modification of the map is reliant on the underlying platform;
some may not allow any changes to the environment variables or
may prevent certain values being used. Attempts to do so will
throw an UnsupportedOperationException or
IllegalArgumentException, respectively.
Use of this method may require a security check for the RuntimePermission "getenv.*".
Returns: a map of the system environment variables for the process.
Throws: SecurityException if the checkPermission method of an installed security manager prevents access to the system environment variables.
Since: 1.5
false.
Returns: true if the output stream and error stream are to be merged.
Parameters: redirect the new value of the redirection flag.
Returns: a reference to this process builder.
Starts execution of a new process, based on the attributes of
this ProcessBuilder object. This is the point
at which the command-line arguments are checked. The list
must be non-empty and contain only non-null string objects.
The other attributes have default values which are used in
cases where their values are not explicitly specified.
If a security manager is in place, then the {@link SecurityManager#checkExec()} method is called to ensure that permission is given to execute the process.
The execution of the process is system-dependent. Various exceptions may result, due to problems at the operating system level. These are all returned as a form of {@link IOException}.
Returns: a Process object, representing the spawned
subprocess.
Throws: IOException if a problem occurs with executing the process at the operating system level. IndexOutOfBoundsException if the command to execute is actually an empty list. NullPointerException if the command to execute is null or the list contains null elements. SecurityException if a security manager exists and prevents execution of the subprocess.