001 /* ProcessBuilder.java - Represent spawned system process
002 Copyright (C) 2005 Free Software Foundation, Inc.
003
004 This file is part of GNU Classpath.
005
006 GNU Classpath is free software; you can redistribute it and/or modify
007 it under the terms of the GNU General Public License as published by
008 the Free Software Foundation; either version 2, or (at your option)
009 any later version.
010
011 GNU Classpath is distributed in the hope that it will be useful, but
012 WITHOUT ANY WARRANTY; without even the implied warranty of
013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014 General Public License for more details.
015
016 You should have received a copy of the GNU General Public License
017 along with GNU Classpath; see the file COPYING. If not, write to the
018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019 02110-1301 USA.
020
021 Linking this library statically or dynamically with other modules is
022 making a combined work based on this library. Thus, the terms and
023 conditions of the GNU General Public License cover the whole
024 combination.
025
026 As a special exception, the copyright holders of this library give you
027 permission to link this library with independent modules to produce an
028 executable, regardless of the license terms of these independent
029 modules, and to copy and distribute the resulting executable under
030 terms of your choice, provided that you also meet, for each linked
031 independent module, the terms and conditions of the license of that
032 module. An independent module is a module which is not derived from
033 or based on this library. If you modify this library, you may extend
034 this exception to your version of the library, but you are not
035 obligated to do so. If you do not wish to do so, delete this
036 exception statement from your version. */
037
038
039 package java.lang;
040
041 import java.io.File;
042 import java.io.IOException;
043
044 import java.util.Arrays;
045 import java.util.List;
046 import java.util.Map;
047
048 /**
049 * <p>
050 * This class is used to construct new operating system processes.
051 * A <code>ProcessBuilder</code> instance basically represent a
052 * template for a new process. Actual processes are generated from
053 * this template via use of the <code>start()</code> method, which
054 * may be invoked multiple times, with each invocation spawning a
055 * new process with the current attributes of the
056 * <code>ProcessBuilder</code> object. Each spawned process is
057 * independent of the <code>ProcessBuilder</code> object, and is
058 * unaffected by changes in its attributes.
059 * </p>
060 * <p>
061 * The following attributes define a process:
062 * </p>
063 * <ul>
064 * <li>The <emphasis>working directory</emphasis>; the activities of a
065 * process begin with the current directory set to this. By default,
066 * this is the working directory of the current process, as defined
067 * by the <code>user.dir</code> property.</li>
068 * <li>The <emphasis>command</emphasis> which invokes the process. This
069 * usually consists of the name of the program binary followed by an
070 * arbitrary number of arguments. For example, <code>find -type f</code>
071 * invokes the <code>find</code> binary with the arguments "-type" and "f".
072 * The command is provided a list, the elements of which are defined in a
073 * system dependent manner; the layout is affected by expected operating
074 * system conventions. A common method is to split the command on each
075 * space within the string. Thus, <code>find -type f</code> forms a
076 * three element list. However, in some cases, the expectation is that
077 * this split is performed by the program itself; thus, the list consists
078 * of only two elements (the program name and its arguments).</li>
079 * <li>The <emphasis>environment map</emphasis>, which links environment
080 * variables to their corresponding values. The initial contents of the map
081 * are the current environment values i.e. it contains the contents of the
082 * map returned by <code>System.getenv()</code>.</li>
083 * <li>The <emphasis>redirection flag</emphasis>, which specifies whether
084 * or not the contents of the error stream should be redirected to standard
085 * output. By default, this is false, and there are two output streams, one
086 * for normal data ({@link Process#getOutputStream()}) and one for error data
087 * ({@link Process#getErrorStream()}). When set to true, the two are merged,
088 * which simplifies the interleaving of the two streams. Data is read using
089 * the stream returned by {@link Process#getOutputStream()}, and the
090 * stream returned by {@link Process#getErrorStream()} throws an immediate
091 * end-of-file exception.</li>
092 * </ul>
093 * <p>
094 * All checks on attribute validity are delayed until <code>start()</code>
095 * is called. <code>ProcessBuilder</code> objects are <strong>not
096 * synchronized</strong>; the user must provide external synchronization
097 * where multiple threads may interact with the same
098 * <code>ProcessBuilder</code> object.
099 * </p>
100 *
101 * @author Tom Tromey (tromey@redhat.com)
102 * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
103 * @see Process
104 * @see System#getenv()
105 * @since 1.5
106 */
107 public final class ProcessBuilder
108 {
109
110 /**
111 * The working directory of the process.
112 */
113 private File directory = new File(System.getProperty("user.dir"));
114
115 /**
116 * The command line syntax for invoking the process.
117 */
118 private List<String> command;
119
120 /**
121 * The mapping of environment variables to values.
122 */
123 private Map<String, String> environment =
124 new System.EnvironmentMap(System.getenv());
125
126 /**
127 * A flag indicating whether to redirect the error stream to standard
128 * output.
129 */
130 private boolean redirect = false;
131
132 /**
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>.
136 *
137 * @param command the name of the program followed by its arguments.
138 */
139 public ProcessBuilder(List<String> command)
140 {
141 this.command = command;
142 }
143
144 /**
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.
150 *
151 * @param command the name of the program followed by its arguments.
152 */
153 public ProcessBuilder(String... command)
154 {
155 this.command = Arrays.asList(command);
156 }
157
158 /**
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>.
164 *
165 * @return the list of command-line arguments.
166 */
167 public List<String> command()
168 {
169 return command;
170 }
171
172 /**
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>.
176 *
177 * @param command the name of the program followed by its arguments.
178 * @return a reference to this process builder.
179 */
180 public ProcessBuilder command(List<String> command)
181 {
182 this.command = command;
183 return this;
184 }
185
186 /**
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.
191 *
192 * @param command the name of the program followed by its arguments.
193 * @return a reference to this process builder.
194 */
195 public ProcessBuilder command(String... command)
196 {
197 this.command = Arrays.asList(command);
198 return this;
199 }
200
201 /**
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
206 * be adopted.
207 *
208 * @return the working directory.
209 */
210 public File directory()
211 {
212 return directory;
213 }
214
215 /**
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
220 * process.
221 *
222 * @param directory the new working directory.
223 * @return a reference to this process builder.
224 */
225 public ProcessBuilder directory(File directory)
226 {
227 this.directory = directory;
228 return this;
229 }
230
231 /**
232 * <p>
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.
236 * </p>
237 * <p>
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>.
243 * </p>
244 * <p>
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.
249 * </p>
250 * <p>
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.
256 * </p>
257 * <p>
258 * Use of this method may require a security check for the
259 * RuntimePermission "getenv.*".
260 * </p>
261 *
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.
266 * @since 1.5
267 */
268 public Map<String, String> environment()
269 {
270 return environment;
271 }
272
273 /**
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>.
277 *
278 * @return true if the output stream and error stream are to
279 * be merged.
280 */
281 public boolean redirectErrorStream()
282 {
283 return redirect;
284 }
285
286 /**
287 * Sets the error stream redirection flag. If set, the output
288 * and error streams are merged to form one composite stream.
289 *
290 * @param redirect the new value of the redirection flag.
291 * @return a reference to this process builder.
292 */
293 public ProcessBuilder redirectErrorStream(boolean redirect)
294 {
295 this.redirect = redirect;
296 return this;
297 }
298
299 /**
300 * <p>
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.
307 * </p>
308 * <p>
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.
312 * </p>
313 * <p>
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}.
317 * </p>
318 *
319 * @return a <code>Process</code> object, representing the spawned
320 * subprocess.
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.
329 */
330 public Process start() throws IOException
331 {
332 SecurityManager sm = SecurityManager.current; // Be thread-safe!
333 if (sm != null)
334 sm.checkExec(command.get(0));
335 return VMProcess.exec(command, environment, directory, redirect);
336 }
337 }