1 /*
2 * Copyright (c) 1995, 2008, Oracle and/or its affiliates. All rights reserved.
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
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
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 *
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.
24 */
25
26 package java.lang;
27
28 import java.io.*;
29
30 /**
31 * The {@link ProcessBuilder#start()} and
32 * {@link Runtime#exec(String[],String[],File) Runtime.exec}
33 * methods create a native process and return an instance of a
34 * subclass of {@code Process} that can be used to control the process
35 * and obtain information about it. The class {@code Process}
36 * provides methods for performing input from the process, performing
37 * output to the process, waiting for the process to complete,
38 * checking the exit status of the process, and destroying (killing)
39 * the process.
40 *
41 * <p>The methods that create processes may not work well for special
42 * processes on certain native platforms, such as native windowing
43 * processes, daemon processes, Win16/DOS processes on Microsoft
44 * Windows, or shell scripts.
45 *
46 * <p>By default, the created subprocess does not have its own terminal
47 * or console. All its standard I/O (i.e. stdin, stdout, stderr)
48 * operations will be redirected to the parent process, where they can
74 * @since JDK1.0
75 */
76 public abstract class Process {
77 /**
78 * Returns the output stream connected to the normal input of the
79 * subprocess. Output to the stream is piped into the standard
80 * input of the process represented by this {@code Process} object.
81 *
82 * <p>If the standard input of the subprocess has been redirected using
83 * {@link ProcessBuilder#redirectInput(Redirect)
84 * ProcessBuilder.redirectInput}
85 * then this method will return a
86 * <a href="ProcessBuilder.html#redirect-input">null output stream</a>.
87 *
88 * <p>Implementation note: It is a good idea for the returned
89 * output stream to be buffered.
90 *
91 * @return the output stream connected to the normal input of the
92 * subprocess
93 */
94 abstract public OutputStream getOutputStream();
95
96 /**
97 * Returns the input stream connected to the normal output of the
98 * subprocess. The stream obtains data piped from the standard
99 * output of the process represented by this {@code Process} object.
100 *
101 * <p>If the standard output of the subprocess has been redirected using
102 * {@link ProcessBuilder#redirectOutput(Redirect)
103 * ProcessBuilder.redirectOutput}
104 * then this method will return a
105 * <a href="ProcessBuilder.html#redirect-output">null input stream</a>.
106 *
107 * <p>Otherwise, if the standard error of the subprocess has been
108 * redirected using
109 * {@link ProcessBuilder#redirectErrorStream(boolean)
110 * ProcessBuilder.redirectErrorStream}
111 * then the input stream returned by this method will receive the
112 * merged standard output and the standard error of the subprocess.
113 *
114 * <p>Implementation note: It is a good idea for the returned
115 * input stream to be buffered.
116 *
117 * @return the input stream connected to the normal output of the
118 * subprocess
119 */
120 abstract public InputStream getInputStream();
121
122 /**
123 * Returns the input stream connected to the error output of the
124 * subprocess. The stream obtains data piped from the error output
125 * of the process represented by this {@code Process} object.
126 *
127 * <p>If the standard error of the subprocess has been redirected using
128 * {@link ProcessBuilder#redirectError(Redirect)
129 * ProcessBuilder.redirectError} or
130 * {@link ProcessBuilder#redirectErrorStream(boolean)
131 * ProcessBuilder.redirectErrorStream}
132 * then this method will return a
133 * <a href="ProcessBuilder.html#redirect-output">null input stream</a>.
134 *
135 * <p>Implementation note: It is a good idea for the returned
136 * input stream to be buffered.
137 *
138 * @return the input stream connected to the error output of
139 * the subprocess
140 */
141 abstract public InputStream getErrorStream();
142
143 /**
144 * Causes the current thread to wait, if necessary, until the
145 * process represented by this {@code Process} object has
146 * terminated. This method returns immediately if the subprocess
147 * has already terminated. If the subprocess has not yet
148 * terminated, the calling thread will be blocked until the
149 * subprocess exits.
150 *
151 * @return the exit value of the subprocess represented by this
152 * {@code Process} object. By convention, the value
153 * {@code 0} indicates normal termination.
154 * @throws InterruptedException if the current thread is
155 * {@linkplain Thread#interrupt() interrupted} by another
156 * thread while it is waiting, then the wait is ended and
157 * an {@link InterruptedException} is thrown.
158 */
159 abstract public int waitFor() throws InterruptedException;
160
161 /**
162 * Returns the exit value for the subprocess.
163 *
164 * @return the exit value of the subprocess represented by this
165 * {@code Process} object. By convention, the value
166 * {@code 0} indicates normal termination.
167 * @throws IllegalThreadStateException if the subprocess represented
168 * by this {@code Process} object has not yet terminated
169 */
170 abstract public int exitValue();
171
172 /**
173 * Kills the subprocess. The subprocess represented by this
174 * {@code Process} object is forcibly terminated.
175 */
176 abstract public void destroy();
177 }
|
1 /*
2 * Copyright (c) 1995, 2012, Oracle and/or its affiliates. All rights reserved.
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
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
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 *
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.
24 */
25
26 package java.lang;
27
28 import java.io.*;
29 import java.util.concurrent.TimeUnit;
30
31 /**
32 * The {@link ProcessBuilder#start()} and
33 * {@link Runtime#exec(String[],String[],File) Runtime.exec}
34 * methods create a native process and return an instance of a
35 * subclass of {@code Process} that can be used to control the process
36 * and obtain information about it. The class {@code Process}
37 * provides methods for performing input from the process, performing
38 * output to the process, waiting for the process to complete,
39 * checking the exit status of the process, and destroying (killing)
40 * the process.
41 *
42 * <p>The methods that create processes may not work well for special
43 * processes on certain native platforms, such as native windowing
44 * processes, daemon processes, Win16/DOS processes on Microsoft
45 * Windows, or shell scripts.
46 *
47 * <p>By default, the created subprocess does not have its own terminal
48 * or console. All its standard I/O (i.e. stdin, stdout, stderr)
49 * operations will be redirected to the parent process, where they can
75 * @since JDK1.0
76 */
77 public abstract class Process {
78 /**
79 * Returns the output stream connected to the normal input of the
80 * subprocess. Output to the stream is piped into the standard
81 * input of the process represented by this {@code Process} object.
82 *
83 * <p>If the standard input of the subprocess has been redirected using
84 * {@link ProcessBuilder#redirectInput(Redirect)
85 * ProcessBuilder.redirectInput}
86 * then this method will return a
87 * <a href="ProcessBuilder.html#redirect-input">null output stream</a>.
88 *
89 * <p>Implementation note: It is a good idea for the returned
90 * output stream to be buffered.
91 *
92 * @return the output stream connected to the normal input of the
93 * subprocess
94 */
95 public abstract OutputStream getOutputStream();
96
97 /**
98 * Returns the input stream connected to the normal output of the
99 * subprocess. The stream obtains data piped from the standard
100 * output of the process represented by this {@code Process} object.
101 *
102 * <p>If the standard output of the subprocess has been redirected using
103 * {@link ProcessBuilder#redirectOutput(Redirect)
104 * ProcessBuilder.redirectOutput}
105 * then this method will return a
106 * <a href="ProcessBuilder.html#redirect-output">null input stream</a>.
107 *
108 * <p>Otherwise, if the standard error of the subprocess has been
109 * redirected using
110 * {@link ProcessBuilder#redirectErrorStream(boolean)
111 * ProcessBuilder.redirectErrorStream}
112 * then the input stream returned by this method will receive the
113 * merged standard output and the standard error of the subprocess.
114 *
115 * <p>Implementation note: It is a good idea for the returned
116 * input stream to be buffered.
117 *
118 * @return the input stream connected to the normal output of the
119 * subprocess
120 */
121 public abstract InputStream getInputStream();
122
123 /**
124 * Returns the input stream connected to the error output of the
125 * subprocess. The stream obtains data piped from the error output
126 * of the process represented by this {@code Process} object.
127 *
128 * <p>If the standard error of the subprocess has been redirected using
129 * {@link ProcessBuilder#redirectError(Redirect)
130 * ProcessBuilder.redirectError} or
131 * {@link ProcessBuilder#redirectErrorStream(boolean)
132 * ProcessBuilder.redirectErrorStream}
133 * then this method will return a
134 * <a href="ProcessBuilder.html#redirect-output">null input stream</a>.
135 *
136 * <p>Implementation note: It is a good idea for the returned
137 * input stream to be buffered.
138 *
139 * @return the input stream connected to the error output of
140 * the subprocess
141 */
142 public abstract InputStream getErrorStream();
143
144 /**
145 * Causes the current thread to wait, if necessary, until the
146 * process represented by this {@code Process} object has
147 * terminated. This method returns immediately if the subprocess
148 * has already terminated. If the subprocess has not yet
149 * terminated, the calling thread will be blocked until the
150 * subprocess exits.
151 *
152 * @return the exit value of the subprocess represented by this
153 * {@code Process} object. By convention, the value
154 * {@code 0} indicates normal termination.
155 * @throws InterruptedException if the current thread is
156 * {@linkplain Thread#interrupt() interrupted} by another
157 * thread while it is waiting, then the wait is ended and
158 * an {@link InterruptedException} is thrown.
159 */
160 public abstract int waitFor() throws InterruptedException;
161
162 /**
163 * Causes the current thread to wait, if necessary, until the
164 * subprocess represented by this {@code Process} object has
165 * terminated, or the specified waiting time elapses.
166 *
167 * <p>If the subprocess has already terminated then this method returns
168 * immediately with the value {@code true}. If the process has not
169 * terminated and the timeout value is less than, or equal to, zero, then
170 * this method returns immediately with the value {@code false}.
171 *
172 * <p>The default implementation of this methods polls the {@code exitValue}
173 * to check if the process has terminated. Concrete implementations of this
174 * class are strongly encouraged to override this method with a more
175 * efficient implementation.
176 *
177 * @param timeout the maximum time to wait
178 * @param unit the time unit of the {@code timeout} argument
179 * @return {@code true} if the subprocess has exited and {@code false} if
180 * the waiting time elapsed before the subprocess has exited.
181 * @throws InterruptedException if the current thread is interrupted
182 * while waiting.
183 * @since 1.8
184 */
185 public boolean waitFor(long timeout, TimeUnit unit)
186 throws InterruptedException {
187 long now = System.nanoTime();
188
189 long end = now +
190 (timeout <= 0 ? 0 : TimeUnit.NANOSECONDS.convert(timeout, unit));
191
192 if (end <= 0) // overflow
193 end = Long.MAX_VALUE;
194
195 long rem = end - now;
196 do {
197 try {
198 exitValue();
199 return true;
200 } catch(IllegalThreadStateException ex) {
201 if(rem > 0)
202 Thread.sleep(
203 Math.min(TimeUnit.NANOSECONDS.toMillis(rem) + 1, 100));
204 }
205 rem = end - System.nanoTime();
206 } while(rem > 0);
207 return false;
208 }
209
210 /**
211 * Returns the exit value for the subprocess.
212 *
213 * @return the exit value of the subprocess represented by this
214 * {@code Process} object. By convention, the value
215 * {@code 0} indicates normal termination.
216 * @throws IllegalThreadStateException if the subprocess represented
217 * by this {@code Process} object has not yet terminated
218 */
219 public abstract int exitValue();
220
221 /**
222 * Kills the subprocess. Whether the subprocess represented by this
223 * {@code Process} object is forcibly terminated or not is
224 * implementation dependent.
225 */
226 public abstract void destroy();
227
228 /**
229 * Kills the subprocess. The subprocess represented by this
230 * {@code Process} object is forcibly terminated.
231 *
232 * <p>The default implementation of this method invokes {@link #destroy}
233 * and so may not forcibly terminate the process. Concrete implementations
234 * of this class are strongly encouraged to override this method with a
235 * compliant implementation. {@code Process} objects returned by
236 * {@link ProcessBuilder#start} and {@link Runtime#exec} are of type that
237 * overrides this method and so invoking this method will forcibly terminate
238 * the process.
239 *
240 * <p>Note: The subprocess may not terminate immediately.
241 * i.e. {@code isAlive()} may return true for a brief period
242 * after {@code destroyForcibly()} is called, however this method
243 * may be chained to {@code waitFor()} if needed.
244 *
245 * @return the {@code Process} object representing the
246 * subprocess to be forcibly destroyed.
247 * @since 1.8
248 */
249 public Process destroyForcibly() {
250 destroy();
251 return this;
252 }
253
254 /**
255 * Tests whether the subprocess represented by this {@code Process} is
256 * alive.
257 *
258 * @return {@code true} if the subprocess represented by this
259 * {@code Process} object has not yet terminated.
260 * @since 1.8
261 */
262 public boolean isAlive() {
263 try {
264 exitValue();
265 return false;
266 } catch(IllegalThreadStateException e) {
267 return true;
268 }
269 }
270 }
|