java.lang
Class ProcessBuilder
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:
- The working directory; the activities of a
process begin with the current directory set to this. By default,
this is the working directory of the current process, as defined
by the
user.dir property. - The command which invokes the process. This
usually consists of the name of the program binary followed by an
arbitrary number of arguments. For example,
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). - The environment map, which links environment
variables to their corresponding values. The initial contents of the map
are the current environment values i.e. it contains the contents of the
map returned by
System.getenv(). - The redirection flag, which specifies whether
or not the contents of the error stream should be redirected to standard
output. By default, this is false, and there are two output streams, one
for normal data (
Process.getOutputStream()) and one for error data
(Process.getErrorStream()). When set to true, the two are merged,
which simplifies the interleaving of the two streams. Data is read using
the stream returned by Process.getOutputStream(), and the
stream returned by Process.getErrorStream() throws an immediate
end-of-file exception.
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.
ProcessBuilder(List command)- Constructs a new
ProcessBuilder with the specified
command being used to invoke the process.
|
ProcessBuilder(java.lang.String... command)- Constructs a new
ProcessBuilder with the specified
command being used to invoke the process.
|
clone, equals, extends Object> getClass, finalize, hashCode, notify, notifyAll, toString, wait, wait, wait |
ProcessBuilder
public ProcessBuilder(List command)
Constructs a new ProcessBuilder with the specified
command being used to invoke the process. The list is used directly;
external changes are reflected in the ProcessBuilder.
command - the name of the program followed by its arguments.
ProcessBuilder
public ProcessBuilder(java.lang.String... command)
Constructs a new 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.
command - the name of the program followed by its arguments.
String> environment
public MapString> environment()
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.*".
- a map of the system environment variables for the process.
SecurityException - if the checkPermission method of
an installed security manager prevents access to
the system environment variables.
command
public List command()
Returns the current command line, used to invoke the process.
The return value is simply a reference to the list of command
line arguments used by the ProcessBuilder object;
any changes made to it will be reflected in the operation of
the ProcessBuilder.
- the list of command-line arguments.
command
public ProcessBuilder command(List command)
Sets the command-line arguments to those specified. The list is
used directly; external changes are reflected in the
ProcessBuilder.
command - the name of the program followed by its arguments.
- a reference to this process builder.
command
public ProcessBuilder command(java.lang.String... command)
Sets the command-line arguments to those specified.
This simplifies modifying the arguments by converting
the provided series of constructor arguments into a
list of command-line arguments.
command - the name of the program followed by its arguments.
- a reference to this process builder.
directory
public File directory()
Returns the working directory of the process. The
returned value may be null; this
indicates that the default behaviour of using the
working directory of the current process should
be adopted.
directory
public ProcessBuilder directory(File directory)
Sets the working directory to that specified.
The supplied argument may be null,
which indicates the default value should be used.
The default is the working directory of the current
process.
directory - the new working directory.
- a reference to this process builder.
redirectErrorStream
public boolean redirectErrorStream()
Returns true if the output stream and error stream of the
process will be merged to form one composite stream. The
default return value is false.
- true if the output stream and error stream are to
be merged.
redirectErrorStream
public ProcessBuilder redirectErrorStream(boolean redirect)
Sets the error stream redirection flag. If set, the output
and error streams are merged to form one composite stream.
redirect - the new value of the redirection flag.
- a reference to this process builder.
start
public Process start()
throws IOException
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
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
IOException.
- a
Process object, representing the spawned
subprocess.
ProcessBuilder.java - Represent spawned system process
Copyright (C) 2005 Free Software Foundation, Inc.
This file is part of GNU Classpath.
GNU Classpath is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option)
any later version.
GNU Classpath is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License
along with GNU Classpath; see the file COPYING. If not, write to the
Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02110-1301 USA.
Linking this library statically or dynamically with other modules is
making a combined work based on this library. Thus, the terms and
conditions of the GNU General Public License cover the whole
combination.
As a special exception, the copyright holders of this library give you
permission to link this library with independent modules to produce an
executable, regardless of the license terms of these independent
modules, and to copy and distribute the resulting executable under
terms of your choice, provided that you also meet, for each linked
independent module, the terms and conditions of the license of that
module. An independent module is a module which is not derived from
or based on this library. If you modify this library, you may extend
this exception to your version of the library, but you are not
obligated to do so. If you do not wish to do so, delete this
exception statement from your version.