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
26package java.lang;
27
28import java.io.*;
29import 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 */
77public 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     * @throws NullPointerException if unit is null
184     * @since 1.8
185     */
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     */
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     */
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     */
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     */
257    public boolean isAlive() {
258        try {
259            exitValue();
260            return false;
261        } catch(IllegalThreadStateException e) {
262            return true;
263        }
264    }
265}
266