1 *java.lang.ProcessBuilder* *ProcessBuilder* This class is used to create operati
3 public final class ProcessBuilder
4 extends |java.lang.Object|
6 |java.lang.ProcessBuilder_Description|
7 |java.lang.ProcessBuilder_Fields|
8 |java.lang.ProcessBuilder_Constructors|
9 |java.lang.ProcessBuilder_Methods|
11 ================================================================================
13 *java.lang.ProcessBuilder_Constructors*
14 |java.lang.ProcessBuilder(List)|Constructs a process builder with the specified
15 |java.lang.ProcessBuilder(String[])|Constructs a process builder with the speci
17 *java.lang.ProcessBuilder_Methods*
18 |java.lang.ProcessBuilder.command()|Returns this process builder's operating sy
19 |java.lang.ProcessBuilder.command(List)|Sets this process builder's operating s
20 |java.lang.ProcessBuilder.command(String[])|Sets this process builder's operati
21 |java.lang.ProcessBuilder.directory()|Returns this process builder's working di
22 |java.lang.ProcessBuilder.directory(File)|Sets this process builder's working d
23 |java.lang.ProcessBuilder.environment()|Returns a string map view of this proce
24 |java.lang.ProcessBuilder.redirectErrorStream()|Tells whether this process buil
25 |java.lang.ProcessBuilder.redirectErrorStream(boolean)|Sets this process builde
26 |java.lang.ProcessBuilder.start()|Starts a new process using the attributes of
28 *java.lang.ProcessBuilder_Description*
30 This class is used to create operating system processes.
32 Each ProcessBuilder instance manages a collection of process attributes. The
33 (|java.lang.ProcessBuilder|) method creates a new (|java.lang.Process|)
34 instance with those attributes. The (|java.lang.ProcessBuilder|) method can be
35 invoked repeatedly from the same instance to create new subprocesses with
36 identical or related attributes.
38 Each process builder manages these process attributes:
42 a command, a list of strings which signifies the external program file to be
43 invoked and its arguments, if any. Which string lists represent a valid
44 operating system command is system-dependent. For example, it is common for
45 each conceptual argument to be an element in this list, but there are operating
46 systems where programs are expected to tokenize command line strings themselves
47 - on such a system a Java implementation might require commands to contain
50 an environment, which is a system-dependent mapping from variables to values.
51 The initial value is a copy of the environment of the current process (see
52 (|java.lang.System|) ).
54 a working directory. The default value is the current working directory of the
55 current process, usually the directory named by the system property user.dir.
57 a redirectErrorStream property. Initially, this property is false, meaning that
58 the standard output and error output of a subprocess are sent to two separate
59 streams, which can be accessed using the (|java.lang.Process|) and
60 (|java.lang.Process|) methods. If the value is set to true, the standard error
61 is merged with the standard output. This makes it easier to correlate error
62 messages with the corresponding output. In this case, the merged data can be
63 read from the stream returned by (|java.lang.Process|) , while reading from the
64 stream returned by (|java.lang.Process|) will get an immediate end of file.
68 Modifying a process builder's attributes will affect processes subsequently
69 started by that object's (|java.lang.ProcessBuilder|) method, but will never
70 affect previously started processes or the Java process itself.
72 Most error checking is performed by the (|java.lang.ProcessBuilder|) method. It
73 is possible to modify the state of an object so that
74 (|java.lang.ProcessBuilder|) will fail. For example, setting the command
75 attribute to an empty list will not throw an exception unless
76 (|java.lang.ProcessBuilder|) is invoked.
78 Note that this class is not synchronized. If multiple threads access a
79 ProcessBuilder instance concurrently, and at least one of the threads modifies
80 one of the attributes structurally, it must be synchronized externally.
82 Starting a new process which uses the default working directory and environment
87 Process p = new ProcessBuilder("myCommand", "myArg").start();
89 Here is an example that starts a process with a modified working directory and
94 ProcessBuilder pb = new ProcessBuilder("myCommand", "myArg1", "myArg2");
95 Map<String, String> env = pb.environment(); env.put("VAR1", "myValue");
96 env.remove("OTHERVAR"); env.put("VAR2", env.get("VAR1") + "suffix");
97 pb.directory("myDir"); Process p = pb.start();
99 To start a process with an explicit set of environment variables, first call
100 Map.clear()(|java.util.Map|) before adding environment variables.
103 *java.lang.ProcessBuilder(List)*
105 public ProcessBuilder(java.util.List command)
107 Constructs a process builder with the specified operating system program and
108 arguments. This constructor does not make a copy of the command list.
109 Subsequent updates to the list will be reflected in the state of the process
110 builder. It is not checked whether command corresponds to a valid operating
113 command - The list containing the program and its arguments
115 *java.lang.ProcessBuilder(String[])*
117 public ProcessBuilder(java.lang.String[] command)
119 Constructs a process builder with the specified operating system program and
120 arguments. This is a convenience constructor that sets the process builder's
121 command to a string list containing the same strings as the command array, in
122 the same order. It is not checked whether command corresponds to a valid
123 operating system command.
125 command - A string array containing the program and its arguments
127 *java.lang.ProcessBuilder.command()*
129 public |java.util.List| command()
131 Returns this process builder's operating system program and arguments. The
132 returned list is not a copy. Subsequent updates to the list will be reflected
133 in the state of this process builder.
136 Returns: This process builder's program and its arguments
137 *java.lang.ProcessBuilder.command(List)*
139 public |java.lang.ProcessBuilder| command(java.util.List command)
141 Sets this process builder's operating system program and arguments. This method
142 does not make a copy of the command list. Subsequent updates to the list will
143 be reflected in the state of the process builder. It is not checked whether
144 command corresponds to a valid operating system command.
146 command - The list containing the program and its arguments
148 Returns: This process builder
149 *java.lang.ProcessBuilder.command(String[])*
151 public |java.lang.ProcessBuilder| command(java.lang.String[] command)
153 Sets this process builder's operating system program and arguments. This is a
154 convenience method that sets the command to a string list containing the same
155 strings as the command array, in the same order. It is not checked whether
156 command corresponds to a valid operating system command.
158 command - A string array containing the program and its arguments
160 Returns: This process builder
161 *java.lang.ProcessBuilder.directory()*
163 public |java.io.File| directory()
165 Returns this process builder's working directory.
167 Subprocesses subsequently started by this object's (|java.lang.ProcessBuilder|)
168 method will use this as their working directory. The returned value may be null
169 -- this means to use the working directory of the current Java process, usually
170 the directory named by the system property user.dir, as the working directory
171 of the child process.
174 Returns: This process builder's working directory
175 *java.lang.ProcessBuilder.directory(File)*
177 public |java.lang.ProcessBuilder| directory(java.io.File directory)
179 Sets this process builder's working directory.
181 Subprocesses subsequently started by this object's (|java.lang.ProcessBuilder|)
182 method will use this as their working directory. The argument may be null --
183 this means to use the working directory of the current Java process, usually
184 the directory named by the system property user.dir, as the working directory
185 of the child process.
187 directory - The new working directory
189 Returns: This process builder
190 *java.lang.ProcessBuilder.environment()*
192 public |java.util.Map| environment()
194 Returns a string map view of this process builder's environment.
196 Whenever a process builder is created, the environment is initialized to a copy
197 of the current process environment (see (|java.lang.System|) ). Subprocesses
198 subsequently started by this object's (|java.lang.ProcessBuilder|) method will
199 use this map as their environment.
201 The returned object may be modified using ordinary Map(|java.util.Map|)
202 operations. These modifications will be visible to subprocesses started via the
203 (|java.lang.ProcessBuilder|) method. Two ProcessBuilder instances always
204 contain independent process environments, so changes to the returned map will
205 never be reflected in any other ProcessBuilder instance or the values returned
206 by System.getenv(|java.lang.System|) .
208 If the system does not support environment variables, an empty map is returned.
210 The returned map does not permit null keys or values. Attempting to insert or
211 query the presence of a null key or value will throw a
212 (|java.lang.NullPointerException|) . Attempting to query the presence of a key
213 or value which is not of type (|java.lang.String|) will throw a
214 (|java.lang.ClassCastException|) .
216 The behavior of the returned map is system-dependent. A system may not allow
217 modifications to environment variables or may forbid certain variable names or
218 values. For this reason, attempts to modify the map may fail with
219 (|java.lang.UnsupportedOperationException|) or
220 (|java.lang.IllegalArgumentException|) if the modification is not permitted by
221 the operating system.
223 Since the external format of environment variable names and values is
224 system-dependent, there may not be a one-to-one mapping between them and Java's
225 Unicode strings. Nevertheless, the map is implemented in such a way that
226 environment variables which are not modified by Java code will have an
227 unmodified native representation in the subprocess.
229 The returned map and its collection views may not obey the general contract of
230 the (|java.lang.Object|) and (|java.lang.Object|) methods.
232 The returned map is typically case-sensitive on all platforms.
234 If a security manager exists, its checkPermission(|java.lang.SecurityManager|)
235 method is called with a (|java.lang.RuntimePermission|) ("getenv.*")
236 permission. This may result in a (|java.lang.SecurityException|) being thrown.
238 When passing information to a Java subprocess, system properties are generally
239 preferred over environment variables.
242 Returns: This process builder's environment
243 *java.lang.ProcessBuilder.redirectErrorStream()*
245 public boolean redirectErrorStream()
247 Tells whether this process builder merges standard error and standard output.
249 If this property is true, then any error output generated by subprocesses
250 subsequently started by this object's (|java.lang.ProcessBuilder|) method will
251 be merged with the standard output, so that both can be read using the
252 (|java.lang.Process|) method. This makes it easier to correlate error messages
253 with the corresponding output. The initial value is false.
256 Returns: This process builder's redirectErrorStream property
257 *java.lang.ProcessBuilder.redirectErrorStream(boolean)*
259 public |java.lang.ProcessBuilder| redirectErrorStream(boolean redirectErrorStream)
261 Sets this process builder's redirectErrorStream property.
263 If this property is true, then any error output generated by subprocesses
264 subsequently started by this object's (|java.lang.ProcessBuilder|) method will
265 be merged with the standard output, so that both can be read using the
266 (|java.lang.Process|) method. This makes it easier to correlate error messages
267 with the corresponding output. The initial value is false.
269 redirectErrorStream - The new property value
271 Returns: This process builder
272 *java.lang.ProcessBuilder.start()*
274 public |java.lang.Process| start()
275 throws |java.io.IOException|
277 Starts a new process using the attributes of this process builder.
279 The new process will invoke the command and arguments given by
280 (|java.lang.ProcessBuilder|) , in a working directory as given by
281 (|java.lang.ProcessBuilder|) , with a process environment as given by
282 (|java.lang.ProcessBuilder|) .
284 This method checks that the command is a valid operating system command. Which
285 commands are valid is system-dependent, but at the very least the command must
286 be a non-empty list of non-null strings.
288 If there is a security manager, its checkExec(|java.lang.SecurityManager|)
289 method is called with the first component of this object's command array as its
290 argument. This may result in a (|java.lang.SecurityException|) being thrown.
292 Starting an operating system process is highly system-dependent. Among the many
293 things that can go wrong are:
295 The operating system program file was not found. Access to the program file was
296 denied. The working directory does not exist.
298 In such cases an exception will be thrown. The exact nature of the exception is
299 system-dependent, but it will always be a subclass of (|java.io.IOException|) .
301 Subsequent modifications to this process builder will not affect the returned
302 (|java.lang.Process|) .
305 Returns: A new {@link Process} object for managing the subprocess