| java.lang.Object
 java.lang.ProcessBuilder
| ProcessBuilder | | final public class ProcessBuilder (Code) | | This class is used to create operating system processes.
Each ProcessBuilder instance manages a collection
of process attributes. The
ProcessBuilder.start() method creates a new
Process instance with those attributes. The
ProcessBuilder.start() method can be invoked repeatedly from the same instance
to create new subprocesses with identical or related attributes.
Each process builder manages these process attributes:
- a command, a list of strings which signifies the
external program file to be invoked and its arguments, if any.
Which string lists represent a valid operating system command is
system-dependent. For example, it is common for each conceptual
argument to be an element in this list, but there are operating
systems where programs are expected to tokenize command line
strings themselves - on such a system a Java implementation might
require commands to contain exactly two elements.
- an environment, which is a system-dependent mapping from
variables to values. The initial value is a copy of
the environment of the current process (see
System.getenv ).
- a working directory. The default value is the current
working directory of the current process, usually the directory
named by the system property
user.dir.
- a redirectErrorStream property. Initially, this property
is
false, meaning that the standard output and error
output of a subprocess are sent to two separate streams, which can
be accessed using the
Process.getInputStream and
Process.getErrorStream methods. If the value is set to
true, the standard error is merged with the standard
output. This makes it easier to correlate error messages with the
corresponding output. In this case, the merged data can be read
from the stream returned by
Process.getInputStream , while
reading from the stream returned by
Process.getErrorStream will get an immediate end of file.
Modifying a process builder's attributes will affect processes
subsequently started by that object's
ProcessBuilder.start() method, but
will never affect previously started processes or the Java process
itself.
Most error checking is performed by the
ProcessBuilder.start() method.
It is possible to modify the state of an object so that
ProcessBuilder.start() will fail. For example, setting the command attribute to
an empty list will not throw an exception unless
ProcessBuilder.start() is invoked.
Note that this class is not synchronized.
If multiple threads access a ProcessBuilder instance
concurrently, and at least one of the threads modifies one of the
attributes structurally, it must be synchronized externally.
Starting a new process which uses the default working directory
and environment is easy:
Process p = new ProcessBuilder("myCommand", "myArg").start();
Here is an example that starts a process with a modified working
directory and environment:
ProcessBuilder pb = new ProcessBuilder("myCommand", "myArg1", "myArg2");
Map<String, String> env = pb.environment();
env.put("VAR1", "myValue");
env.remove("OTHERVAR");
env.put("VAR2", env.get("VAR1") + "suffix");
pb.directory(new File("myDir"));
Process p = pb.start();
To start a process with an explicit set of environment
variables, first call
java.util.Map.clear Map.clear() before adding environment variables.
since:
1.5 |
| Constructor Summary | |
| public | ProcessBuilder(List<String> command)
Constructs a process builder with the specified operating
system program and arguments. | | public | ProcessBuilder(String... command)
Constructs a process builder with the specified operating
system program and arguments. |
| ProcessBuilder | | public ProcessBuilder(List<String> command)(Code) | | Constructs a process builder with the specified operating
system program and arguments. This constructor does not
make a copy of the command list. Subsequent
updates to the list will be reflected in the state of the
process builder. It is not checked whether
command corresponds to a valid operating system
command.
Parameters:
command - The list containing the program and its arguments
throws:
NullPointerException - If the argument is null |
| ProcessBuilder | | public ProcessBuilder(String... command)(Code) | | Constructs a process builder with the specified operating
system program and arguments. This is a convenience
constructor that sets the process builder's command to a string
list containing the same strings as the command
array, in the same order. It is not checked whether
command corresponds to a valid operating system
command.
Parameters:
command - A string array containing the program and its arguments |
| command | | public ProcessBuilder command(List<String> command)(Code) | | Sets this process builder's operating system program and
arguments. This method does not make a copy of the
command list. Subsequent updates to the list will
be reflected in the state of the process builder. It is not
checked whether command corresponds to a valid
operating system command.
Parameters:
command - The list containing the program and its arguments This process builder
throws:
NullPointerException - If the argument is null |
| command | | public ProcessBuilder command(String... command)(Code) | | Sets this process builder's operating system program and
arguments. This is a convenience method that sets the command
to a string list containing the same strings as the
command array, in the same order. It is not
checked whether command corresponds to a valid
operating system command.
Parameters:
command - A string array containing the program and its arguments This process builder |
| command | | public List<String> command()(Code) | | Returns this process builder's operating system program and
arguments. The returned list is not a copy. Subsequent
updates to the list will be reflected in the state of this
process builder.
This process builder's program and its arguments |
| directory | | public File directory()(Code) | | Returns this process builder's working directory.
Subprocesses subsequently started by this object's
ProcessBuilder.start() method will use this as their working directory.
The returned value may be null -- this means to use
the working directory of the current Java process, usually the
directory named by the system property user.dir,
as the working directory of the child process.
This process builder's working directory |
| directory | | public ProcessBuilder directory(File directory)(Code) | | Sets this process builder's working directory.
Subprocesses subsequently started by this object's
ProcessBuilder.start() method will use this as their working directory.
The argument may be null -- this means to use the
working directory of the current Java process, usually the
directory named by the system property user.dir,
as the working directory of the child process.
Parameters:
directory - The new working directory This process builder |
| environment | | public Map<String, String> environment()(Code) | | Returns a string map view of this process builder's environment.
Whenever a process builder is created, the environment is
initialized to a copy of the current process environment (see
System.getenv ). Subprocesses subsequently started by
this object's
ProcessBuilder.start() method will use this map as
their environment.
The returned object may be modified using ordinary
java.util.Map Map operations. These modifications will be
visible to subprocesses started via the
ProcessBuilder.start() method. Two ProcessBuilder instances always
contain independent process environments, so changes to the
returned map will never be reflected in any other
ProcessBuilder instance or the values returned by
System.getenv System.getenv .
If the system does not support environment variables, an
empty map is returned.
The returned map does not permit null keys or values.
Attempting to insert or query the presence of a null key or
value will throw a
NullPointerException .
Attempting to query the presence of a key or value which is not
of type
String will throw a
ClassCastException .
The behavior of the returned map is system-dependent. A
system may not allow modifications to environment variables or
may forbid certain variable names or values. For this reason,
attempts to modify the map may fail with
UnsupportedOperationException or
IllegalArgumentException if the modification is not permitted by the operating system.
Since the external format of environment variable names and
values is system-dependent, there may not be a one-to-one
mapping between them and Java's Unicode strings. Nevertheless,
the map is implemented in such a way that environment variables
which are not modified by Java code will have an unmodified
native representation in the subprocess.
The returned map and its collection views may not obey the
general contract of the
Object.equals and
Object.hashCode methods.
The returned map is typically case-sensitive on all platforms.
If a security manager exists, its
SecurityManager.checkPermission checkPermission method is called with a
RuntimePermission ("getenv.*")
permission. This may result in a
SecurityException being
thrown.
When passing information to a Java subprocess,
system properties
are generally preferred over environment variables.
This process builder's environment
throws:
SecurityException - If a security manager exists and itsSecurityManager.checkPermission checkPermissionmethod doesn't allow access to the process environment
See Also: Runtime.exec(String[]String[]java.io.File)
See Also: System.getenv |
| redirectErrorStream | | public boolean redirectErrorStream()(Code) | | Tells whether this process builder merges standard error and
standard output.
If this property is true, then any error output
generated by subprocesses subsequently started by this object's
ProcessBuilder.start() method will be merged with the standard
output, so that both can be read using the
Process.getInputStream method. This makes it easier
to correlate error messages with the corresponding output.
The initial value is false.
This process builder's redirectErrorStream property |
| redirectErrorStream | | public ProcessBuilder redirectErrorStream(boolean redirectErrorStream)(Code) | | Sets this process builder's redirectErrorStream property.
If this property is true, then any error output
generated by subprocesses subsequently started by this object's
ProcessBuilder.start() method will be merged with the standard
output, so that both can be read using the
Process.getInputStream method. This makes it easier
to correlate error messages with the corresponding output.
The initial value is false.
Parameters:
redirectErrorStream - The new property value This process builder |
| start | | public Process start() throws IOException(Code) | | Starts a new process using the attributes of this process builder.
The new process will
invoke the command and arguments given by
ProcessBuilder.command() ,
in a working directory as given by
ProcessBuilder.directory() ,
with a process environment as given by
ProcessBuilder.environment() .
This method checks that the command is a valid operating
system command. Which commands are valid is system-dependent,
but at the very least the command must be a non-empty list of
non-null strings.
If there is a security manager, its
SecurityManager.checkExec checkExec method is called with the first component of this object's
command array as its argument. This may result in
a
SecurityException being thrown.
Starting an operating system process is highly system-dependent.
Among the many things that can go wrong are:
- The operating system program file was not found.
- Access to the program file was denied.
- The working directory does not exist.
In such cases an exception will be thrown. The exact nature
of the exception is system-dependent, but it will always be a
subclass of
IOException .
Subsequent modifications to this process builder will not
affect the returned
Process .
A new Process object for managing the subprocess
throws:
NullPointerException - If an element of the command list is null
throws:
IndexOutOfBoundsException - If the command is an empty list (has size 0)
throws:
SecurityException - If a security manager exists and itsSecurityManager.checkExec checkExecmethod doesn't allow creation of the subprocess
throws:
IOException - If an I/O error occurs
See Also: Runtime.exec(String[]String[]java.io.File)
See Also: SecurityManager.checkExec(String) |
|
|
