author | jrose |
Tue, 14 Jun 2011 22:47:09 -0700 | |
changeset 9859 | 47e26ad535c4 |
parent 9500 | 268f823d9e1c |
child 11117 | b6e68b1344d4 |
permissions | -rw-r--r-- |
2 | 1 |
/* |
5506 | 2 |
* Copyright (c) 1995, 2006, Oracle and/or its affiliates. All rights reserved. |
2 | 3 |
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
4 |
* |
|
5 |
* This code is free software; you can redistribute it and/or modify it |
|
6 |
* under the terms of the GNU General Public License version 2 only, as |
|
5506 | 7 |
* published by the Free Software Foundation. Oracle designates this |
2 | 8 |
* particular file as subject to the "Classpath" exception as provided |
5506 | 9 |
* by Oracle in the LICENSE file that accompanied this code. |
2 | 10 |
* |
11 |
* This code is distributed in the hope that it will be useful, but WITHOUT |
|
12 |
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
|
13 |
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
|
14 |
* version 2 for more details (a copy is included in the LICENSE file that |
|
15 |
* accompanied this code). |
|
16 |
* |
|
17 |
* You should have received a copy of the GNU General Public License version |
|
18 |
* 2 along with this work; if not, write to the Free Software Foundation, |
|
19 |
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
|
20 |
* |
|
5506 | 21 |
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
22 |
* or visit www.oracle.com if you need additional information or have any |
|
23 |
* questions. |
|
2 | 24 |
*/ |
25 |
||
26 |
package java.lang; |
|
27 |
||
28 |
import java.io.*; |
|
29 |
import java.util.StringTokenizer; |
|
30 |
||
31 |
/** |
|
32 |
* Every Java application has a single instance of class |
|
33 |
* <code>Runtime</code> that allows the application to interface with |
|
34 |
* the environment in which the application is running. The current |
|
35 |
* runtime can be obtained from the <code>getRuntime</code> method. |
|
36 |
* <p> |
|
37 |
* An application cannot create its own instance of this class. |
|
38 |
* |
|
39 |
* @author unascribed |
|
40 |
* @see java.lang.Runtime#getRuntime() |
|
41 |
* @since JDK1.0 |
|
42 |
*/ |
|
43 |
||
44 |
public class Runtime { |
|
45 |
private static Runtime currentRuntime = new Runtime(); |
|
46 |
||
47 |
/** |
|
48 |
* Returns the runtime object associated with the current Java application. |
|
49 |
* Most of the methods of class <code>Runtime</code> are instance |
|
50 |
* methods and must be invoked with respect to the current runtime object. |
|
51 |
* |
|
52 |
* @return the <code>Runtime</code> object associated with the current |
|
53 |
* Java application. |
|
54 |
*/ |
|
55 |
public static Runtime getRuntime() { |
|
56 |
return currentRuntime; |
|
57 |
} |
|
58 |
||
59 |
/** Don't let anyone else instantiate this class */ |
|
60 |
private Runtime() {} |
|
61 |
||
62 |
/** |
|
63 |
* Terminates the currently running Java virtual machine by initiating its |
|
64 |
* shutdown sequence. This method never returns normally. The argument |
|
65 |
* serves as a status code; by convention, a nonzero status code indicates |
|
66 |
* abnormal termination. |
|
67 |
* |
|
68 |
* <p> The virtual machine's shutdown sequence consists of two phases. In |
|
69 |
* the first phase all registered {@link #addShutdownHook shutdown hooks}, |
|
70 |
* if any, are started in some unspecified order and allowed to run |
|
71 |
* concurrently until they finish. In the second phase all uninvoked |
|
72 |
* finalizers are run if {@link #runFinalizersOnExit finalization-on-exit} |
|
73 |
* has been enabled. Once this is done the virtual machine {@link #halt |
|
74 |
* halts}. |
|
75 |
* |
|
76 |
* <p> If this method is invoked after the virtual machine has begun its |
|
77 |
* shutdown sequence then if shutdown hooks are being run this method will |
|
78 |
* block indefinitely. If shutdown hooks have already been run and on-exit |
|
79 |
* finalization has been enabled then this method halts the virtual machine |
|
80 |
* with the given status code if the status is nonzero; otherwise, it |
|
81 |
* blocks indefinitely. |
|
82 |
* |
|
83 |
* <p> The <tt>{@link System#exit(int) System.exit}</tt> method is the |
|
84 |
* conventional and convenient means of invoking this method. <p> |
|
85 |
* |
|
86 |
* @param status |
|
87 |
* Termination status. By convention, a nonzero status code |
|
88 |
* indicates abnormal termination. |
|
89 |
* |
|
90 |
* @throws SecurityException |
|
91 |
* If a security manager is present and its <tt>{@link |
|
92 |
* SecurityManager#checkExit checkExit}</tt> method does not permit |
|
93 |
* exiting with the specified status |
|
94 |
* |
|
95 |
* @see java.lang.SecurityException |
|
96 |
* @see java.lang.SecurityManager#checkExit(int) |
|
97 |
* @see #addShutdownHook |
|
98 |
* @see #removeShutdownHook |
|
99 |
* @see #runFinalizersOnExit |
|
100 |
* @see #halt(int) |
|
101 |
*/ |
|
102 |
public void exit(int status) { |
|
103 |
SecurityManager security = System.getSecurityManager(); |
|
104 |
if (security != null) { |
|
105 |
security.checkExit(status); |
|
106 |
} |
|
107 |
Shutdown.exit(status); |
|
108 |
} |
|
109 |
||
110 |
/** |
|
111 |
* Registers a new virtual-machine shutdown hook. |
|
112 |
* |
|
113 |
* <p> The Java virtual machine <i>shuts down</i> in response to two kinds |
|
114 |
* of events: |
|
115 |
* |
|
116 |
* <ul> |
|
117 |
* |
|
118 |
* <p> <li> The program <i>exits</i> normally, when the last non-daemon |
|
119 |
* thread exits or when the <tt>{@link #exit exit}</tt> (equivalently, |
|
120 |
* <tt>{@link System#exit(int) System.exit}</tt>) method is invoked, or |
|
121 |
* |
|
122 |
* <p> <li> The virtual machine is <i>terminated</i> in response to a |
|
123 |
* user interrupt, such as typing <tt>^C</tt>, or a system-wide event, |
|
124 |
* such as user logoff or system shutdown. |
|
125 |
* |
|
126 |
* </ul> |
|
127 |
* |
|
128 |
* <p> A <i>shutdown hook</i> is simply an initialized but unstarted |
|
129 |
* thread. When the virtual machine begins its shutdown sequence it will |
|
130 |
* start all registered shutdown hooks in some unspecified order and let |
|
131 |
* them run concurrently. When all the hooks have finished it will then |
|
132 |
* run all uninvoked finalizers if finalization-on-exit has been enabled. |
|
133 |
* Finally, the virtual machine will halt. Note that daemon threads will |
|
134 |
* continue to run during the shutdown sequence, as will non-daemon threads |
|
135 |
* if shutdown was initiated by invoking the <tt>{@link #exit exit}</tt> |
|
136 |
* method. |
|
137 |
* |
|
138 |
* <p> Once the shutdown sequence has begun it can be stopped only by |
|
139 |
* invoking the <tt>{@link #halt halt}</tt> method, which forcibly |
|
140 |
* terminates the virtual machine. |
|
141 |
* |
|
142 |
* <p> Once the shutdown sequence has begun it is impossible to register a |
|
143 |
* new shutdown hook or de-register a previously-registered hook. |
|
144 |
* Attempting either of these operations will cause an |
|
145 |
* <tt>{@link IllegalStateException}</tt> to be thrown. |
|
146 |
* |
|
147 |
* <p> Shutdown hooks run at a delicate time in the life cycle of a virtual |
|
148 |
* machine and should therefore be coded defensively. They should, in |
|
149 |
* particular, be written to be thread-safe and to avoid deadlocks insofar |
|
150 |
* as possible. They should also not rely blindly upon services that may |
|
151 |
* have registered their own shutdown hooks and therefore may themselves in |
|
152 |
* the process of shutting down. Attempts to use other thread-based |
|
153 |
* services such as the AWT event-dispatch thread, for example, may lead to |
|
154 |
* deadlocks. |
|
155 |
* |
|
156 |
* <p> Shutdown hooks should also finish their work quickly. When a |
|
157 |
* program invokes <tt>{@link #exit exit}</tt> the expectation is |
|
158 |
* that the virtual machine will promptly shut down and exit. When the |
|
159 |
* virtual machine is terminated due to user logoff or system shutdown the |
|
160 |
* underlying operating system may only allow a fixed amount of time in |
|
161 |
* which to shut down and exit. It is therefore inadvisable to attempt any |
|
162 |
* user interaction or to perform a long-running computation in a shutdown |
|
163 |
* hook. |
|
164 |
* |
|
165 |
* <p> Uncaught exceptions are handled in shutdown hooks just as in any |
|
166 |
* other thread, by invoking the <tt>{@link ThreadGroup#uncaughtException |
|
167 |
* uncaughtException}</tt> method of the thread's <tt>{@link |
|
168 |
* ThreadGroup}</tt> object. The default implementation of this method |
|
169 |
* prints the exception's stack trace to <tt>{@link System#err}</tt> and |
|
170 |
* terminates the thread; it does not cause the virtual machine to exit or |
|
171 |
* halt. |
|
172 |
* |
|
173 |
* <p> In rare circumstances the virtual machine may <i>abort</i>, that is, |
|
174 |
* stop running without shutting down cleanly. This occurs when the |
|
175 |
* virtual machine is terminated externally, for example with the |
|
176 |
* <tt>SIGKILL</tt> signal on Unix or the <tt>TerminateProcess</tt> call on |
|
177 |
* Microsoft Windows. The virtual machine may also abort if a native |
|
178 |
* method goes awry by, for example, corrupting internal data structures or |
|
179 |
* attempting to access nonexistent memory. If the virtual machine aborts |
|
180 |
* then no guarantee can be made about whether or not any shutdown hooks |
|
181 |
* will be run. <p> |
|
182 |
* |
|
183 |
* @param hook |
|
184 |
* An initialized but unstarted <tt>{@link Thread}</tt> object |
|
185 |
* |
|
186 |
* @throws IllegalArgumentException |
|
187 |
* If the specified hook has already been registered, |
|
188 |
* or if it can be determined that the hook is already running or |
|
189 |
* has already been run |
|
190 |
* |
|
191 |
* @throws IllegalStateException |
|
192 |
* If the virtual machine is already in the process |
|
193 |
* of shutting down |
|
194 |
* |
|
195 |
* @throws SecurityException |
|
196 |
* If a security manager is present and it denies |
|
197 |
* <tt>{@link RuntimePermission}("shutdownHooks")</tt> |
|
198 |
* |
|
199 |
* @see #removeShutdownHook |
|
200 |
* @see #halt(int) |
|
201 |
* @see #exit(int) |
|
202 |
* @since 1.3 |
|
203 |
*/ |
|
204 |
public void addShutdownHook(Thread hook) { |
|
205 |
SecurityManager sm = System.getSecurityManager(); |
|
206 |
if (sm != null) { |
|
207 |
sm.checkPermission(new RuntimePermission("shutdownHooks")); |
|
208 |
} |
|
209 |
ApplicationShutdownHooks.add(hook); |
|
210 |
} |
|
211 |
||
212 |
/** |
|
213 |
* De-registers a previously-registered virtual-machine shutdown hook. <p> |
|
214 |
* |
|
215 |
* @param hook the hook to remove |
|
216 |
* @return <tt>true</tt> if the specified hook had previously been |
|
217 |
* registered and was successfully de-registered, <tt>false</tt> |
|
218 |
* otherwise. |
|
219 |
* |
|
220 |
* @throws IllegalStateException |
|
221 |
* If the virtual machine is already in the process of shutting |
|
222 |
* down |
|
223 |
* |
|
224 |
* @throws SecurityException |
|
225 |
* If a security manager is present and it denies |
|
226 |
* <tt>{@link RuntimePermission}("shutdownHooks")</tt> |
|
227 |
* |
|
228 |
* @see #addShutdownHook |
|
229 |
* @see #exit(int) |
|
230 |
* @since 1.3 |
|
231 |
*/ |
|
232 |
public boolean removeShutdownHook(Thread hook) { |
|
233 |
SecurityManager sm = System.getSecurityManager(); |
|
234 |
if (sm != null) { |
|
235 |
sm.checkPermission(new RuntimePermission("shutdownHooks")); |
|
236 |
} |
|
237 |
return ApplicationShutdownHooks.remove(hook); |
|
238 |
} |
|
239 |
||
240 |
/** |
|
241 |
* Forcibly terminates the currently running Java virtual machine. This |
|
242 |
* method never returns normally. |
|
243 |
* |
|
244 |
* <p> This method should be used with extreme caution. Unlike the |
|
245 |
* <tt>{@link #exit exit}</tt> method, this method does not cause shutdown |
|
246 |
* hooks to be started and does not run uninvoked finalizers if |
|
247 |
* finalization-on-exit has been enabled. If the shutdown sequence has |
|
248 |
* already been initiated then this method does not wait for any running |
|
249 |
* shutdown hooks or finalizers to finish their work. <p> |
|
250 |
* |
|
251 |
* @param status |
|
252 |
* Termination status. By convention, a nonzero status code |
|
253 |
* indicates abnormal termination. If the <tt>{@link Runtime#exit |
|
254 |
* exit}</tt> (equivalently, <tt>{@link System#exit(int) |
|
255 |
* System.exit}</tt>) method has already been invoked then this |
|
256 |
* status code will override the status code passed to that method. |
|
257 |
* |
|
258 |
* @throws SecurityException |
|
259 |
* If a security manager is present and its <tt>{@link |
|
260 |
* SecurityManager#checkExit checkExit}</tt> method does not permit |
|
261 |
* an exit with the specified status |
|
262 |
* |
|
263 |
* @see #exit |
|
264 |
* @see #addShutdownHook |
|
265 |
* @see #removeShutdownHook |
|
266 |
* @since 1.3 |
|
267 |
*/ |
|
268 |
public void halt(int status) { |
|
269 |
SecurityManager sm = System.getSecurityManager(); |
|
270 |
if (sm != null) { |
|
271 |
sm.checkExit(status); |
|
272 |
} |
|
273 |
Shutdown.halt(status); |
|
274 |
} |
|
275 |
||
276 |
/** |
|
277 |
* Enable or disable finalization on exit; doing so specifies that the |
|
278 |
* finalizers of all objects that have finalizers that have not yet been |
|
279 |
* automatically invoked are to be run before the Java runtime exits. |
|
280 |
* By default, finalization on exit is disabled. |
|
281 |
* |
|
282 |
* <p>If there is a security manager, |
|
283 |
* its <code>checkExit</code> method is first called |
|
284 |
* with 0 as its argument to ensure the exit is allowed. |
|
285 |
* This could result in a SecurityException. |
|
286 |
* |
|
287 |
* @param value true to enable finalization on exit, false to disable |
|
288 |
* @deprecated This method is inherently unsafe. It may result in |
|
289 |
* finalizers being called on live objects while other threads are |
|
290 |
* concurrently manipulating those objects, resulting in erratic |
|
291 |
* behavior or deadlock. |
|
292 |
* |
|
293 |
* @throws SecurityException |
|
294 |
* if a security manager exists and its <code>checkExit</code> |
|
295 |
* method doesn't allow the exit. |
|
296 |
* |
|
297 |
* @see java.lang.Runtime#exit(int) |
|
298 |
* @see java.lang.Runtime#gc() |
|
299 |
* @see java.lang.SecurityManager#checkExit(int) |
|
300 |
* @since JDK1.1 |
|
301 |
*/ |
|
302 |
@Deprecated |
|
303 |
public static void runFinalizersOnExit(boolean value) { |
|
304 |
SecurityManager security = System.getSecurityManager(); |
|
305 |
if (security != null) { |
|
306 |
try { |
|
307 |
security.checkExit(0); |
|
308 |
} catch (SecurityException e) { |
|
309 |
throw new SecurityException("runFinalizersOnExit"); |
|
310 |
} |
|
311 |
} |
|
312 |
Shutdown.setRunFinalizersOnExit(value); |
|
313 |
} |
|
314 |
||
315 |
/** |
|
316 |
* Executes the specified string command in a separate process. |
|
317 |
* |
|
318 |
* <p>This is a convenience method. An invocation of the form |
|
319 |
* <tt>exec(command)</tt> |
|
320 |
* behaves in exactly the same way as the invocation |
|
321 |
* <tt>{@link #exec(String, String[], File) exec}(command, null, null)</tt>. |
|
322 |
* |
|
323 |
* @param command a specified system command. |
|
324 |
* |
|
325 |
* @return A new {@link Process} object for managing the subprocess |
|
326 |
* |
|
327 |
* @throws SecurityException |
|
328 |
* If a security manager exists and its |
|
329 |
* {@link SecurityManager#checkExec checkExec} |
|
330 |
* method doesn't allow creation of the subprocess |
|
331 |
* |
|
332 |
* @throws IOException |
|
333 |
* If an I/O error occurs |
|
334 |
* |
|
335 |
* @throws NullPointerException |
|
336 |
* If <code>command</code> is <code>null</code> |
|
337 |
* |
|
338 |
* @throws IllegalArgumentException |
|
339 |
* If <code>command</code> is empty |
|
340 |
* |
|
341 |
* @see #exec(String[], String[], File) |
|
342 |
* @see ProcessBuilder |
|
343 |
*/ |
|
344 |
public Process exec(String command) throws IOException { |
|
345 |
return exec(command, null, null); |
|
346 |
} |
|
347 |
||
348 |
/** |
|
349 |
* Executes the specified string command in a separate process with the |
|
350 |
* specified environment. |
|
351 |
* |
|
352 |
* <p>This is a convenience method. An invocation of the form |
|
353 |
* <tt>exec(command, envp)</tt> |
|
354 |
* behaves in exactly the same way as the invocation |
|
355 |
* <tt>{@link #exec(String, String[], File) exec}(command, envp, null)</tt>. |
|
356 |
* |
|
357 |
* @param command a specified system command. |
|
358 |
* |
|
359 |
* @param envp array of strings, each element of which |
|
360 |
* has environment variable settings in the format |
|
361 |
* <i>name</i>=<i>value</i>, or |
|
362 |
* <tt>null</tt> if the subprocess should inherit |
|
363 |
* the environment of the current process. |
|
364 |
* |
|
365 |
* @return A new {@link Process} object for managing the subprocess |
|
366 |
* |
|
367 |
* @throws SecurityException |
|
368 |
* If a security manager exists and its |
|
369 |
* {@link SecurityManager#checkExec checkExec} |
|
370 |
* method doesn't allow creation of the subprocess |
|
371 |
* |
|
372 |
* @throws IOException |
|
373 |
* If an I/O error occurs |
|
374 |
* |
|
375 |
* @throws NullPointerException |
|
376 |
* If <code>command</code> is <code>null</code>, |
|
377 |
* or one of the elements of <code>envp</code> is <code>null</code> |
|
378 |
* |
|
379 |
* @throws IllegalArgumentException |
|
380 |
* If <code>command</code> is empty |
|
381 |
* |
|
382 |
* @see #exec(String[], String[], File) |
|
383 |
* @see ProcessBuilder |
|
384 |
*/ |
|
385 |
public Process exec(String command, String[] envp) throws IOException { |
|
386 |
return exec(command, envp, null); |
|
387 |
} |
|
388 |
||
389 |
/** |
|
390 |
* Executes the specified string command in a separate process with the |
|
391 |
* specified environment and working directory. |
|
392 |
* |
|
393 |
* <p>This is a convenience method. An invocation of the form |
|
394 |
* <tt>exec(command, envp, dir)</tt> |
|
395 |
* behaves in exactly the same way as the invocation |
|
396 |
* <tt>{@link #exec(String[], String[], File) exec}(cmdarray, envp, dir)</tt>, |
|
397 |
* where <code>cmdarray</code> is an array of all the tokens in |
|
398 |
* <code>command</code>. |
|
399 |
* |
|
400 |
* <p>More precisely, the <code>command</code> string is broken |
|
401 |
* into tokens using a {@link StringTokenizer} created by the call |
|
402 |
* <code>new {@link StringTokenizer}(command)</code> with no |
|
403 |
* further modification of the character categories. The tokens |
|
404 |
* produced by the tokenizer are then placed in the new string |
|
405 |
* array <code>cmdarray</code>, in the same order. |
|
406 |
* |
|
407 |
* @param command a specified system command. |
|
408 |
* |
|
409 |
* @param envp array of strings, each element of which |
|
410 |
* has environment variable settings in the format |
|
411 |
* <i>name</i>=<i>value</i>, or |
|
412 |
* <tt>null</tt> if the subprocess should inherit |
|
413 |
* the environment of the current process. |
|
414 |
* |
|
415 |
* @param dir the working directory of the subprocess, or |
|
416 |
* <tt>null</tt> if the subprocess should inherit |
|
417 |
* the working directory of the current process. |
|
418 |
* |
|
419 |
* @return A new {@link Process} object for managing the subprocess |
|
420 |
* |
|
421 |
* @throws SecurityException |
|
422 |
* If a security manager exists and its |
|
423 |
* {@link SecurityManager#checkExec checkExec} |
|
424 |
* method doesn't allow creation of the subprocess |
|
425 |
* |
|
426 |
* @throws IOException |
|
427 |
* If an I/O error occurs |
|
428 |
* |
|
429 |
* @throws NullPointerException |
|
430 |
* If <code>command</code> is <code>null</code>, |
|
431 |
* or one of the elements of <code>envp</code> is <code>null</code> |
|
432 |
* |
|
433 |
* @throws IllegalArgumentException |
|
434 |
* If <code>command</code> is empty |
|
435 |
* |
|
436 |
* @see ProcessBuilder |
|
437 |
* @since 1.3 |
|
438 |
*/ |
|
439 |
public Process exec(String command, String[] envp, File dir) |
|
440 |
throws IOException { |
|
441 |
if (command.length() == 0) |
|
442 |
throw new IllegalArgumentException("Empty command"); |
|
443 |
||
444 |
StringTokenizer st = new StringTokenizer(command); |
|
445 |
String[] cmdarray = new String[st.countTokens()]; |
|
446 |
for (int i = 0; st.hasMoreTokens(); i++) |
|
447 |
cmdarray[i] = st.nextToken(); |
|
448 |
return exec(cmdarray, envp, dir); |
|
449 |
} |
|
450 |
||
451 |
/** |
|
452 |
* Executes the specified command and arguments in a separate process. |
|
453 |
* |
|
454 |
* <p>This is a convenience method. An invocation of the form |
|
455 |
* <tt>exec(cmdarray)</tt> |
|
456 |
* behaves in exactly the same way as the invocation |
|
457 |
* <tt>{@link #exec(String[], String[], File) exec}(cmdarray, null, null)</tt>. |
|
458 |
* |
|
459 |
* @param cmdarray array containing the command to call and |
|
460 |
* its arguments. |
|
461 |
* |
|
462 |
* @return A new {@link Process} object for managing the subprocess |
|
463 |
* |
|
464 |
* @throws SecurityException |
|
465 |
* If a security manager exists and its |
|
466 |
* {@link SecurityManager#checkExec checkExec} |
|
467 |
* method doesn't allow creation of the subprocess |
|
468 |
* |
|
469 |
* @throws IOException |
|
470 |
* If an I/O error occurs |
|
471 |
* |
|
472 |
* @throws NullPointerException |
|
473 |
* If <code>cmdarray</code> is <code>null</code>, |
|
474 |
* or one of the elements of <code>cmdarray</code> is <code>null</code> |
|
475 |
* |
|
476 |
* @throws IndexOutOfBoundsException |
|
477 |
* If <code>cmdarray</code> is an empty array |
|
478 |
* (has length <code>0</code>) |
|
479 |
* |
|
480 |
* @see ProcessBuilder |
|
481 |
*/ |
|
482 |
public Process exec(String cmdarray[]) throws IOException { |
|
483 |
return exec(cmdarray, null, null); |
|
484 |
} |
|
485 |
||
486 |
/** |
|
487 |
* Executes the specified command and arguments in a separate process |
|
488 |
* with the specified environment. |
|
489 |
* |
|
490 |
* <p>This is a convenience method. An invocation of the form |
|
491 |
* <tt>exec(cmdarray, envp)</tt> |
|
492 |
* behaves in exactly the same way as the invocation |
|
493 |
* <tt>{@link #exec(String[], String[], File) exec}(cmdarray, envp, null)</tt>. |
|
494 |
* |
|
495 |
* @param cmdarray array containing the command to call and |
|
496 |
* its arguments. |
|
497 |
* |
|
498 |
* @param envp array of strings, each element of which |
|
499 |
* has environment variable settings in the format |
|
500 |
* <i>name</i>=<i>value</i>, or |
|
501 |
* <tt>null</tt> if the subprocess should inherit |
|
502 |
* the environment of the current process. |
|
503 |
* |
|
504 |
* @return A new {@link Process} object for managing the subprocess |
|
505 |
* |
|
506 |
* @throws SecurityException |
|
507 |
* If a security manager exists and its |
|
508 |
* {@link SecurityManager#checkExec checkExec} |
|
509 |
* method doesn't allow creation of the subprocess |
|
510 |
* |
|
511 |
* @throws IOException |
|
512 |
* If an I/O error occurs |
|
513 |
* |
|
514 |
* @throws NullPointerException |
|
515 |
* If <code>cmdarray</code> is <code>null</code>, |
|
516 |
* or one of the elements of <code>cmdarray</code> is <code>null</code>, |
|
517 |
* or one of the elements of <code>envp</code> is <code>null</code> |
|
518 |
* |
|
519 |
* @throws IndexOutOfBoundsException |
|
520 |
* If <code>cmdarray</code> is an empty array |
|
521 |
* (has length <code>0</code>) |
|
522 |
* |
|
523 |
* @see ProcessBuilder |
|
524 |
*/ |
|
525 |
public Process exec(String[] cmdarray, String[] envp) throws IOException { |
|
526 |
return exec(cmdarray, envp, null); |
|
527 |
} |
|
528 |
||
529 |
||
530 |
/** |
|
531 |
* Executes the specified command and arguments in a separate process with |
|
532 |
* the specified environment and working directory. |
|
533 |
* |
|
534 |
* <p>Given an array of strings <code>cmdarray</code>, representing the |
|
535 |
* tokens of a command line, and an array of strings <code>envp</code>, |
|
536 |
* representing "environment" variable settings, this method creates |
|
537 |
* a new process in which to execute the specified command. |
|
538 |
* |
|
539 |
* <p>This method checks that <code>cmdarray</code> is a valid operating |
|
540 |
* system command. Which commands are valid is system-dependent, |
|
541 |
* but at the very least the command must be a non-empty list of |
|
542 |
* non-null strings. |
|
543 |
* |
|
544 |
* <p>If <tt>envp</tt> is <tt>null</tt>, the subprocess inherits the |
|
545 |
* environment settings of the current process. |
|
546 |
* |
|
9500
268f823d9e1c
7034570: java.lang.Runtime.exec(String[] cmd, String[] env) can not work properly if SystemRoot not inherited
michaelm
parents:
5506
diff
changeset
|
547 |
* <p>A minimal set of system dependent environment variables may |
268f823d9e1c
7034570: java.lang.Runtime.exec(String[] cmd, String[] env) can not work properly if SystemRoot not inherited
michaelm
parents:
5506
diff
changeset
|
548 |
* be required to start a process on some operating systems. |
268f823d9e1c
7034570: java.lang.Runtime.exec(String[] cmd, String[] env) can not work properly if SystemRoot not inherited
michaelm
parents:
5506
diff
changeset
|
549 |
* As a result, the subprocess may inherit additional environment variable |
268f823d9e1c
7034570: java.lang.Runtime.exec(String[] cmd, String[] env) can not work properly if SystemRoot not inherited
michaelm
parents:
5506
diff
changeset
|
550 |
* settings beyond those in the specified environment. |
268f823d9e1c
7034570: java.lang.Runtime.exec(String[] cmd, String[] env) can not work properly if SystemRoot not inherited
michaelm
parents:
5506
diff
changeset
|
551 |
* |
2 | 552 |
* <p>{@link ProcessBuilder#start()} is now the preferred way to |
553 |
* start a process with a modified environment. |
|
554 |
* |
|
555 |
* <p>The working directory of the new subprocess is specified by <tt>dir</tt>. |
|
556 |
* If <tt>dir</tt> is <tt>null</tt>, the subprocess inherits the |
|
557 |
* current working directory of the current process. |
|
558 |
* |
|
559 |
* <p>If a security manager exists, its |
|
560 |
* {@link SecurityManager#checkExec checkExec} |
|
561 |
* method is invoked with the first component of the array |
|
562 |
* <code>cmdarray</code> as its argument. This may result in a |
|
563 |
* {@link SecurityException} being thrown. |
|
564 |
* |
|
565 |
* <p>Starting an operating system process is highly system-dependent. |
|
566 |
* Among the many things that can go wrong are: |
|
567 |
* <ul> |
|
568 |
* <li>The operating system program file was not found. |
|
569 |
* <li>Access to the program file was denied. |
|
570 |
* <li>The working directory does not exist. |
|
571 |
* </ul> |
|
572 |
* |
|
573 |
* <p>In such cases an exception will be thrown. The exact nature |
|
574 |
* of the exception is system-dependent, but it will always be a |
|
575 |
* subclass of {@link IOException}. |
|
576 |
* |
|
577 |
* |
|
578 |
* @param cmdarray array containing the command to call and |
|
579 |
* its arguments. |
|
580 |
* |
|
581 |
* @param envp array of strings, each element of which |
|
582 |
* has environment variable settings in the format |
|
583 |
* <i>name</i>=<i>value</i>, or |
|
584 |
* <tt>null</tt> if the subprocess should inherit |
|
585 |
* the environment of the current process. |
|
586 |
* |
|
587 |
* @param dir the working directory of the subprocess, or |
|
588 |
* <tt>null</tt> if the subprocess should inherit |
|
589 |
* the working directory of the current process. |
|
590 |
* |
|
591 |
* @return A new {@link Process} object for managing the subprocess |
|
592 |
* |
|
593 |
* @throws SecurityException |
|
594 |
* If a security manager exists and its |
|
595 |
* {@link SecurityManager#checkExec checkExec} |
|
596 |
* method doesn't allow creation of the subprocess |
|
597 |
* |
|
598 |
* @throws IOException |
|
599 |
* If an I/O error occurs |
|
600 |
* |
|
601 |
* @throws NullPointerException |
|
602 |
* If <code>cmdarray</code> is <code>null</code>, |
|
603 |
* or one of the elements of <code>cmdarray</code> is <code>null</code>, |
|
604 |
* or one of the elements of <code>envp</code> is <code>null</code> |
|
605 |
* |
|
606 |
* @throws IndexOutOfBoundsException |
|
607 |
* If <code>cmdarray</code> is an empty array |
|
608 |
* (has length <code>0</code>) |
|
609 |
* |
|
610 |
* @see ProcessBuilder |
|
611 |
* @since 1.3 |
|
612 |
*/ |
|
613 |
public Process exec(String[] cmdarray, String[] envp, File dir) |
|
614 |
throws IOException { |
|
615 |
return new ProcessBuilder(cmdarray) |
|
616 |
.environment(envp) |
|
617 |
.directory(dir) |
|
618 |
.start(); |
|
619 |
} |
|
620 |
||
621 |
/** |
|
622 |
* Returns the number of processors available to the Java virtual machine. |
|
623 |
* |
|
624 |
* <p> This value may change during a particular invocation of the virtual |
|
625 |
* machine. Applications that are sensitive to the number of available |
|
626 |
* processors should therefore occasionally poll this property and adjust |
|
627 |
* their resource usage appropriately. </p> |
|
628 |
* |
|
629 |
* @return the maximum number of processors available to the virtual |
|
630 |
* machine; never smaller than one |
|
631 |
* @since 1.4 |
|
632 |
*/ |
|
633 |
public native int availableProcessors(); |
|
634 |
||
635 |
/** |
|
636 |
* Returns the amount of free memory in the Java Virtual Machine. |
|
637 |
* Calling the |
|
638 |
* <code>gc</code> method may result in increasing the value returned |
|
639 |
* by <code>freeMemory.</code> |
|
640 |
* |
|
641 |
* @return an approximation to the total amount of memory currently |
|
642 |
* available for future allocated objects, measured in bytes. |
|
643 |
*/ |
|
644 |
public native long freeMemory(); |
|
645 |
||
646 |
/** |
|
647 |
* Returns the total amount of memory in the Java virtual machine. |
|
648 |
* The value returned by this method may vary over time, depending on |
|
649 |
* the host environment. |
|
650 |
* <p> |
|
651 |
* Note that the amount of memory required to hold an object of any |
|
652 |
* given type may be implementation-dependent. |
|
653 |
* |
|
654 |
* @return the total amount of memory currently available for current |
|
655 |
* and future objects, measured in bytes. |
|
656 |
*/ |
|
657 |
public native long totalMemory(); |
|
658 |
||
659 |
/** |
|
660 |
* Returns the maximum amount of memory that the Java virtual machine will |
|
661 |
* attempt to use. If there is no inherent limit then the value {@link |
|
662 |
* java.lang.Long#MAX_VALUE} will be returned. </p> |
|
663 |
* |
|
664 |
* @return the maximum amount of memory that the virtual machine will |
|
665 |
* attempt to use, measured in bytes |
|
666 |
* @since 1.4 |
|
667 |
*/ |
|
668 |
public native long maxMemory(); |
|
669 |
||
670 |
/** |
|
671 |
* Runs the garbage collector. |
|
672 |
* Calling this method suggests that the Java virtual machine expend |
|
673 |
* effort toward recycling unused objects in order to make the memory |
|
674 |
* they currently occupy available for quick reuse. When control |
|
675 |
* returns from the method call, the virtual machine has made |
|
676 |
* its best effort to recycle all discarded objects. |
|
677 |
* <p> |
|
678 |
* The name <code>gc</code> stands for "garbage |
|
679 |
* collector". The virtual machine performs this recycling |
|
680 |
* process automatically as needed, in a separate thread, even if the |
|
681 |
* <code>gc</code> method is not invoked explicitly. |
|
682 |
* <p> |
|
683 |
* The method {@link System#gc()} is the conventional and convenient |
|
684 |
* means of invoking this method. |
|
685 |
*/ |
|
686 |
public native void gc(); |
|
687 |
||
688 |
/* Wormhole for calling java.lang.ref.Finalizer.runFinalization */ |
|
689 |
private static native void runFinalization0(); |
|
690 |
||
691 |
/** |
|
692 |
* Runs the finalization methods of any objects pending finalization. |
|
693 |
* Calling this method suggests that the Java virtual machine expend |
|
694 |
* effort toward running the <code>finalize</code> methods of objects |
|
695 |
* that have been found to be discarded but whose <code>finalize</code> |
|
696 |
* methods have not yet been run. When control returns from the |
|
697 |
* method call, the virtual machine has made a best effort to |
|
698 |
* complete all outstanding finalizations. |
|
699 |
* <p> |
|
700 |
* The virtual machine performs the finalization process |
|
701 |
* automatically as needed, in a separate thread, if the |
|
702 |
* <code>runFinalization</code> method is not invoked explicitly. |
|
703 |
* <p> |
|
704 |
* The method {@link System#runFinalization()} is the conventional |
|
705 |
* and convenient means of invoking this method. |
|
706 |
* |
|
707 |
* @see java.lang.Object#finalize() |
|
708 |
*/ |
|
709 |
public void runFinalization() { |
|
710 |
runFinalization0(); |
|
711 |
} |
|
712 |
||
713 |
/** |
|
714 |
* Enables/Disables tracing of instructions. |
|
715 |
* If the <code>boolean</code> argument is <code>true</code>, this |
|
716 |
* method suggests that the Java virtual machine emit debugging |
|
717 |
* information for each instruction in the virtual machine as it |
|
718 |
* is executed. The format of this information, and the file or other |
|
719 |
* output stream to which it is emitted, depends on the host environment. |
|
720 |
* The virtual machine may ignore this request if it does not support |
|
721 |
* this feature. The destination of the trace output is system |
|
722 |
* dependent. |
|
723 |
* <p> |
|
724 |
* If the <code>boolean</code> argument is <code>false</code>, this |
|
725 |
* method causes the virtual machine to stop performing the |
|
726 |
* detailed instruction trace it is performing. |
|
727 |
* |
|
728 |
* @param on <code>true</code> to enable instruction tracing; |
|
729 |
* <code>false</code> to disable this feature. |
|
730 |
*/ |
|
731 |
public native void traceInstructions(boolean on); |
|
732 |
||
733 |
/** |
|
734 |
* Enables/Disables tracing of method calls. |
|
735 |
* If the <code>boolean</code> argument is <code>true</code>, this |
|
736 |
* method suggests that the Java virtual machine emit debugging |
|
737 |
* information for each method in the virtual machine as it is |
|
738 |
* called. The format of this information, and the file or other output |
|
739 |
* stream to which it is emitted, depends on the host environment. The |
|
740 |
* virtual machine may ignore this request if it does not support |
|
741 |
* this feature. |
|
742 |
* <p> |
|
743 |
* Calling this method with argument false suggests that the |
|
744 |
* virtual machine cease emitting per-call debugging information. |
|
745 |
* |
|
746 |
* @param on <code>true</code> to enable instruction tracing; |
|
747 |
* <code>false</code> to disable this feature. |
|
748 |
*/ |
|
749 |
public native void traceMethodCalls(boolean on); |
|
750 |
||
751 |
/** |
|
752 |
* Loads the specified filename as a dynamic library. The filename |
|
753 |
* argument must be a complete path name, |
|
754 |
* (for example |
|
755 |
* <code>Runtime.getRuntime().load("/home/avh/lib/libX11.so");</code>). |
|
756 |
* <p> |
|
757 |
* First, if there is a security manager, its <code>checkLink</code> |
|
758 |
* method is called with the <code>filename</code> as its argument. |
|
759 |
* This may result in a security exception. |
|
760 |
* <p> |
|
761 |
* This is similar to the method {@link #loadLibrary(String)}, but it |
|
762 |
* accepts a general file name as an argument rather than just a library |
|
763 |
* name, allowing any file of native code to be loaded. |
|
764 |
* <p> |
|
765 |
* The method {@link System#load(String)} is the conventional and |
|
766 |
* convenient means of invoking this method. |
|
767 |
* |
|
768 |
* @param filename the file to load. |
|
769 |
* @exception SecurityException if a security manager exists and its |
|
770 |
* <code>checkLink</code> method doesn't allow |
|
771 |
* loading of the specified dynamic library |
|
772 |
* @exception UnsatisfiedLinkError if the file does not exist. |
|
773 |
* @exception NullPointerException if <code>filename</code> is |
|
774 |
* <code>null</code> |
|
775 |
* @see java.lang.Runtime#getRuntime() |
|
776 |
* @see java.lang.SecurityException |
|
777 |
* @see java.lang.SecurityManager#checkLink(java.lang.String) |
|
778 |
*/ |
|
779 |
public void load(String filename) { |
|
780 |
load0(System.getCallerClass(), filename); |
|
781 |
} |
|
782 |
||
783 |
synchronized void load0(Class fromClass, String filename) { |
|
784 |
SecurityManager security = System.getSecurityManager(); |
|
785 |
if (security != null) { |
|
786 |
security.checkLink(filename); |
|
787 |
} |
|
788 |
if (!(new File(filename).isAbsolute())) { |
|
789 |
throw new UnsatisfiedLinkError( |
|
790 |
"Expecting an absolute path of the library: " + filename); |
|
791 |
} |
|
792 |
ClassLoader.loadLibrary(fromClass, filename, true); |
|
793 |
} |
|
794 |
||
795 |
/** |
|
796 |
* Loads the dynamic library with the specified library name. |
|
797 |
* A file containing native code is loaded from the local file system |
|
798 |
* from a place where library files are conventionally obtained. The |
|
799 |
* details of this process are implementation-dependent. The |
|
800 |
* mapping from a library name to a specific filename is done in a |
|
801 |
* system-specific manner. |
|
802 |
* <p> |
|
803 |
* First, if there is a security manager, its <code>checkLink</code> |
|
804 |
* method is called with the <code>libname</code> as its argument. |
|
805 |
* This may result in a security exception. |
|
806 |
* <p> |
|
807 |
* The method {@link System#loadLibrary(String)} is the conventional |
|
808 |
* and convenient means of invoking this method. If native |
|
809 |
* methods are to be used in the implementation of a class, a standard |
|
810 |
* strategy is to put the native code in a library file (call it |
|
811 |
* <code>LibFile</code>) and then to put a static initializer: |
|
812 |
* <blockquote><pre> |
|
813 |
* static { System.loadLibrary("LibFile"); } |
|
814 |
* </pre></blockquote> |
|
815 |
* within the class declaration. When the class is loaded and |
|
816 |
* initialized, the necessary native code implementation for the native |
|
817 |
* methods will then be loaded as well. |
|
818 |
* <p> |
|
819 |
* If this method is called more than once with the same library |
|
820 |
* name, the second and subsequent calls are ignored. |
|
821 |
* |
|
822 |
* @param libname the name of the library. |
|
823 |
* @exception SecurityException if a security manager exists and its |
|
824 |
* <code>checkLink</code> method doesn't allow |
|
825 |
* loading of the specified dynamic library |
|
826 |
* @exception UnsatisfiedLinkError if the library does not exist. |
|
827 |
* @exception NullPointerException if <code>libname</code> is |
|
828 |
* <code>null</code> |
|
829 |
* @see java.lang.SecurityException |
|
830 |
* @see java.lang.SecurityManager#checkLink(java.lang.String) |
|
831 |
*/ |
|
832 |
public void loadLibrary(String libname) { |
|
833 |
loadLibrary0(System.getCallerClass(), libname); |
|
834 |
} |
|
835 |
||
836 |
synchronized void loadLibrary0(Class fromClass, String libname) { |
|
837 |
SecurityManager security = System.getSecurityManager(); |
|
838 |
if (security != null) { |
|
839 |
security.checkLink(libname); |
|
840 |
} |
|
841 |
if (libname.indexOf((int)File.separatorChar) != -1) { |
|
842 |
throw new UnsatisfiedLinkError( |
|
843 |
"Directory separator should not appear in library name: " + libname); |
|
844 |
} |
|
845 |
ClassLoader.loadLibrary(fromClass, libname, false); |
|
846 |
} |
|
847 |
||
848 |
/** |
|
849 |
* Creates a localized version of an input stream. This method takes |
|
850 |
* an <code>InputStream</code> and returns an <code>InputStream</code> |
|
851 |
* equivalent to the argument in all respects except that it is |
|
852 |
* localized: as characters in the local character set are read from |
|
853 |
* the stream, they are automatically converted from the local |
|
854 |
* character set to Unicode. |
|
855 |
* <p> |
|
856 |
* If the argument is already a localized stream, it may be returned |
|
857 |
* as the result. |
|
858 |
* |
|
859 |
* @param in InputStream to localize |
|
860 |
* @return a localized input stream |
|
861 |
* @see java.io.InputStream |
|
862 |
* @see java.io.BufferedReader#BufferedReader(java.io.Reader) |
|
863 |
* @see java.io.InputStreamReader#InputStreamReader(java.io.InputStream) |
|
864 |
* @deprecated As of JDK 1.1, the preferred way to translate a byte |
|
865 |
* stream in the local encoding into a character stream in Unicode is via |
|
866 |
* the <code>InputStreamReader</code> and <code>BufferedReader</code> |
|
867 |
* classes. |
|
868 |
*/ |
|
869 |
@Deprecated |
|
870 |
public InputStream getLocalizedInputStream(InputStream in) { |
|
871 |
return in; |
|
872 |
} |
|
873 |
||
874 |
/** |
|
875 |
* Creates a localized version of an output stream. This method |
|
876 |
* takes an <code>OutputStream</code> and returns an |
|
877 |
* <code>OutputStream</code> equivalent to the argument in all respects |
|
878 |
* except that it is localized: as Unicode characters are written to |
|
879 |
* the stream, they are automatically converted to the local |
|
880 |
* character set. |
|
881 |
* <p> |
|
882 |
* If the argument is already a localized stream, it may be returned |
|
883 |
* as the result. |
|
884 |
* |
|
885 |
* @deprecated As of JDK 1.1, the preferred way to translate a |
|
886 |
* Unicode character stream into a byte stream in the local encoding is via |
|
887 |
* the <code>OutputStreamWriter</code>, <code>BufferedWriter</code>, and |
|
888 |
* <code>PrintWriter</code> classes. |
|
889 |
* |
|
890 |
* @param out OutputStream to localize |
|
891 |
* @return a localized output stream |
|
892 |
* @see java.io.OutputStream |
|
893 |
* @see java.io.BufferedWriter#BufferedWriter(java.io.Writer) |
|
894 |
* @see java.io.OutputStreamWriter#OutputStreamWriter(java.io.OutputStream) |
|
895 |
* @see java.io.PrintWriter#PrintWriter(java.io.OutputStream) |
|
896 |
*/ |
|
897 |
@Deprecated |
|
898 |
public OutputStream getLocalizedOutputStream(OutputStream out) { |
|
899 |
return out; |
|
900 |
} |
|
901 |
||
902 |
} |