1 /* ProcessBuilder.java - Represent spawned system process
2 Copyright (C) 2005 Free Software Foundation, Inc.
4 This file is part of GNU Classpath.
6 GNU Classpath is free software; you can redistribute it and/or modify
7 it under the terms of the GNU General Public License as published by
8 the Free Software Foundation; either version 2, or (at your option)
11 GNU Classpath is distributed in the hope that it will be useful, but
12 WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 General Public License for more details.
16 You should have received a copy of the GNU General Public License
17 along with GNU Classpath; see the file COPYING. If not, write to the
18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
21 Linking this library statically or dynamically with other modules is
22 making a combined work based on this library. Thus, the terms and
23 conditions of the GNU General Public License cover the whole
26 As a special exception, the copyright holders of this library give you
27 permission to link this library with independent modules to produce an
28 executable, regardless of the license terms of these independent
29 modules, and to copy and distribute the resulting executable under
30 terms of your choice, provided that you also meet, for each linked
31 independent module, the terms and conditions of the license of that
32 module. An independent module is a module which is not derived from
33 or based on this library. If you modify this library, you may extend
34 this exception to your version of the library, but you are not
35 obligated to do so. If you do not wish to do so, delete this
36 exception statement from your version. */
42 import java
.io
.IOException
;
44 import java
.util
.Arrays
;
45 import java
.util
.List
;
50 * This class is used to construct new operating system processes.
51 * A <code>ProcessBuilder</code> instance basically represent a
52 * template for a new process. Actual processes are generated from
53 * this template via use of the <code>start()</code> method, which
54 * may be invoked multiple times, with each invocation spawning a
55 * new process with the current attributes of the
56 * <code>ProcessBuilder</code> object. Each spawned process is
57 * independent of the <code>ProcessBuilder</code> object, and is
58 * unaffected by changes in its attributes.
61 * The following attributes define a process:
64 * <li>The <emphasis>working directory</emphasis>; the activities of a
65 * process begin with the current directory set to this. By default,
66 * this is the working directory of the current process, as defined
67 * by the <code>user.dir</code> property.</li>
68 * <li>The <emphasis>command</emphasis> which invokes the process. This
69 * usually consists of the name of the program binary followed by an
70 * arbitrary number of arguments. For example, <code>find -type f</code>
71 * invokes the <code>find</code> binary with the arguments "-type" and "f".
72 * The command is provided a list, the elements of which are defined in a
73 * system dependent manner; the layout is affected by expected operating
74 * system conventions. A common method is to split the command on each
75 * space within the string. Thus, <code>find -type f</code> forms a
76 * three element list. However, in some cases, the expectation is that
77 * this split is performed by the program itself; thus, the list consists
78 * of only two elements (the program name and its arguments).</li>
79 * <li>The <emphasis>environment map</emphasis>, which links environment
80 * variables to their corresponding values. The initial contents of the map
81 * are the current environment values i.e. it contains the contents of the
82 * map returned by <code>System.getenv()</code>.</li>
83 * <li>The <emphasis>redirection flag</emphasis>, which specifies whether
84 * or not the contents of the error stream should be redirected to standard
85 * output. By default, this is false, and there are two output streams, one
86 * for normal data ({@link Process#getOutputStream()}) and one for error data
87 * ({@link Process#getErrorStream()}). When set to true, the two are merged,
88 * which simplifies the interleaving of the two streams. Data is read using
89 * the stream returned by {@link Process#getOutputStream()}, and the
90 * stream returned by {@link Process#getErrorStream()} throws an immediate
91 * end-of-file exception.</li>
94 * All checks on attribute validity are delayed until <code>start()</code>
95 * is called. <code>ProcessBuilder</code> objects are <strong>not
96 * synchronized</strong>; the user must provide external synchronization
97 * where multiple threads may interact with the same
98 * <code>ProcessBuilder</code> object.
101 * @author Tom Tromey (tromey@redhat.com)
102 * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
104 * @see System#getenv()
107 public final class ProcessBuilder
111 * The working directory of the process.
113 private File directory
= new File(System
.getProperty("user.dir"));
116 * The command line syntax for invoking the process.
118 private List
<String
> command
;
121 * The mapping of environment variables to values.
123 private Map
<String
, String
> environment
=
124 new System
.EnvironmentMap(System
.getenv());
127 * A flag indicating whether to redirect the error stream to standard
130 private boolean redirect
= false;
133 * Constructs a new <code>ProcessBuilder</code> with the specified
134 * command being used to invoke the process. The list is used directly;
135 * external changes are reflected in the <code>ProcessBuilder</code>.
137 * @param command the name of the program followed by its arguments.
139 public ProcessBuilder(List
<String
> command
)
141 this.command
= command
;
145 * Constructs a new <code>ProcessBuilder</code> with the specified
146 * command being used to invoke the process. This constructor
147 * simplifies creating a new <code>ProcessBuilder</code> by
148 * converting the provided series of constructor arguments into a
149 * list of command-line arguments.
151 * @param command the name of the program followed by its arguments.
153 public ProcessBuilder(String
... command
)
155 this.command
= Arrays
.asList(command
);
159 * Returns the current command line, used to invoke the process.
160 * The return value is simply a reference to the list of command
161 * line arguments used by the <code>ProcessBuilder</code> object;
162 * any changes made to it will be reflected in the operation of
163 * the <code>ProcessBuilder</code>.
165 * @return the list of command-line arguments.
167 public List
<String
> command()
173 * Sets the command-line arguments to those specified. The list is
174 * used directly; external changes are reflected in the
175 * <code>ProcessBuilder</code>.
177 * @param command the name of the program followed by its arguments.
178 * @return a reference to this process builder.
180 public ProcessBuilder
command(List
<String
> command
)
182 this.command
= command
;
187 * Sets the command-line arguments to those specified.
188 * This simplifies modifying the arguments by converting
189 * the provided series of constructor arguments into a
190 * list of command-line arguments.
192 * @param command the name of the program followed by its arguments.
193 * @return a reference to this process builder.
195 public ProcessBuilder
command(String
... command
)
197 this.command
= Arrays
.asList(command
);
202 * Returns the working directory of the process. The
203 * returned value may be <code>null</code>; this
204 * indicates that the default behaviour of using the
205 * working directory of the current process should
208 * @return the working directory.
210 public File
directory()
216 * Sets the working directory to that specified.
217 * The supplied argument may be <code>null</code>,
218 * which indicates the default value should be used.
219 * The default is the working directory of the current
222 * @param directory the new working directory.
223 * @return a reference to this process builder.
225 public ProcessBuilder
directory(File directory
)
227 this.directory
= directory
;
233 * Returns the system environment variables of the process.
234 * If the underlying system does not support environment variables,
235 * an empty map is returned.
238 * The returned map does not accept queries using
239 * null keys or values, or those of a type other than
240 * <code>String</code>. Attempts to pass in a null value will
241 * throw a <code>NullPointerException</code>. Types other than
242 * <code>String</code> throw a <code>ClassCastException</code>.
245 * As the returned map is generated using data from the underlying
246 * platform, it may not comply with the <code>equals()</code>
247 * and <code>hashCode()</code> contracts. It is also likely that
248 * the keys of this map will be case-sensitive.
251 * Modification of the map is reliant on the underlying platform;
252 * some may not allow any changes to the environment variables or
253 * may prevent certain values being used. Attempts to do so will
254 * throw an <code>UnsupportedOperationException</code> or
255 * <code>IllegalArgumentException</code>, respectively.
258 * Use of this method may require a security check for the
259 * RuntimePermission "getenv.*".
262 * @return a map of the system environment variables for the process.
263 * @throws SecurityException if the checkPermission method of
264 * an installed security manager prevents access to
265 * the system environment variables.
268 public Map
<String
, String
> environment()
274 * Returns true if the output stream and error stream of the
275 * process will be merged to form one composite stream. The
276 * default return value is <code>false</code>.
278 * @return true if the output stream and error stream are to
281 public boolean redirectErrorStream()
287 * Sets the error stream redirection flag. If set, the output
288 * and error streams are merged to form one composite stream.
290 * @param redirect the new value of the redirection flag.
291 * @return a reference to this process builder.
293 public ProcessBuilder
redirectErrorStream(boolean redirect
)
295 this.redirect
= redirect
;
301 * Starts execution of a new process, based on the attributes of
302 * this <code>ProcessBuilder</code> object. This is the point
303 * at which the command-line arguments are checked. The list
304 * must be non-empty and contain only non-null string objects.
305 * The other attributes have default values which are used in
306 * cases where their values are not explicitly specified.
309 * If a security manager is in place, then the
310 * {@link SecurityManager#checkExec()} method is called to
311 * ensure that permission is given to execute the process.
314 * The execution of the process is system-dependent. Various
315 * exceptions may result, due to problems at the operating system
316 * level. These are all returned as a form of {@link IOException}.
319 * @return a <code>Process</code> object, representing the spawned
321 * @throws IOException if a problem occurs with executing the process
322 * at the operating system level.
323 * @throws IndexOutOfBoundsException if the command to execute is
324 * actually an empty list.
325 * @throws NullPointerException if the command to execute is null
326 * or the list contains null elements.
327 * @throws SecurityException if a security manager exists and prevents
328 * execution of the subprocess.
330 public Process
start() throws IOException
332 SecurityManager sm
= SecurityManager
.current
; // Be thread-safe!
334 sm
.checkExec(command
.get(0));
335 return VMProcess
.exec(command
, environment
, directory
, redirect
);