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
50  * be accessed via the streams obtained using the methods
51  * {@link #getOutputStream()},
52  * {@link #getInputStream()}, and
53  * {@link #getErrorStream()}.
54  * The parent process uses these streams to feed input to and get output
55  * from the subprocess.  Because some native platforms only provide
56  * limited buffer size for standard input and output streams, failure
57  * to promptly write the input stream or read the output stream of
58  * the subprocess may cause the subprocess to block, or even deadlock.
59  *
60  * <p>Where desired, <a href="ProcessBuilder.html#redirect-input">
61  * subprocess I/O can also be redirected</a>
62  * using methods of the {@link ProcessBuilder} class.
63  *
64  * <p>The subprocess is not killed when there are no more references to
65  * the {@code Process} object, but rather the subprocess
66  * continues executing asynchronously.
67  *
68  * <p>There is no requirement that a process represented by a {@code
69  * Process} object execute asynchronously or concurrently with respect
70  * to the Java process that owns the {@code Process} object.
71  *
72  * <p>As of 1.5, {@link ProcessBuilder#start()} is the preferred way
73  * to create a {@code Process}.
74  *
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      */
getOutputStream()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      */
getInputStream()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      */
getErrorStream()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      */
waitFor()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      * @throws NullPointerException if unit is null
184      * @since 1.8
185      */
waitFor(long timeout, TimeUnit unit)186     public boolean waitFor(long timeout, TimeUnit unit)
187         throws InterruptedException
188     {
189         long startTime = System.nanoTime();
190         long rem = unit.toNanos(timeout);
191 
192         do {
193             try {
194                 exitValue();
195                 return true;
196             } catch(IllegalThreadStateException ex) {
197                 if (rem > 0)
198                     Thread.sleep(
199                         Math.min(TimeUnit.NANOSECONDS.toMillis(rem) + 1, 100));
200             }
201             rem = unit.toNanos(timeout) - (System.nanoTime() - startTime);
202         } while (rem > 0);
203         return false;
204     }
205 
206     /**
207      * Returns the exit value for the subprocess.
208      *
209      * @return the exit value of the subprocess represented by this
210      *         {@code Process} object.  By convention, the value
211      *         {@code 0} indicates normal termination.
212      * @throws IllegalThreadStateException if the subprocess represented
213      *         by this {@code Process} object has not yet terminated
214      */
exitValue()215     public abstract int exitValue();
216 
217     /**
218      * Kills the subprocess. Whether the subprocess represented by this
219      * {@code Process} object is forcibly terminated or not is
220      * implementation dependent.
221      */
destroy()222     public abstract void destroy();
223 
224     /**
225      * Kills the subprocess. The subprocess represented by this
226      * {@code Process} object is forcibly terminated.
227      *
228      * <p>The default implementation of this method invokes {@link #destroy}
229      * and so may not forcibly terminate the process. Concrete implementations
230      * of this class are strongly encouraged to override this method with a
231      * compliant implementation.  Invoking this method on {@code Process}
232      * objects returned by {@link ProcessBuilder#start} and
233      * {@link Runtime#exec} will forcibly terminate the process.
234      *
235      * <p>Note: The subprocess may not terminate immediately.
236      * i.e. {@code isAlive()} may return true for a brief period
237      * after {@code destroyForcibly()} is called. This method
238      * may be chained to {@code waitFor()} if needed.
239      *
240      * @return the {@code Process} object representing the
241      *         subprocess to be forcibly destroyed.
242      * @since 1.8
243      */
destroyForcibly()244     public Process destroyForcibly() {
245         destroy();
246         return this;
247     }
248 
249     /**
250      * Tests whether the subprocess represented by this {@code Process} is
251      * alive.
252      *
253      * @return {@code true} if the subprocess represented by this
254      *         {@code Process} object has not yet terminated.
255      * @since 1.8
256      */
isAlive()257     public boolean isAlive() {
258         try {
259             exitValue();
260             return false;
261         } catch(IllegalThreadStateException e) {
262             return true;
263         }
264     }
265 }
266