Process.java revision 31741c01ddb025995692d3c46155b0626b55a389 
1/*
2 *  Licensed to the Apache Software Foundation (ASF) under one or more
3 *  contributor license agreements.  See the NOTICE file distributed with
4 *  this work for additional information regarding copyright ownership.
5 *  The ASF licenses this file to You under the Apache License, Version 2.0
6 *  (the "License"); you may not use this file except in compliance with
7 *  the License.  You may obtain a copy of the License at
8 *
9 *     http://www.apache.org/licenses/LICENSE-2.0
10 *
11 *  Unless required by applicable law or agreed to in writing, software
12 *  distributed under the License is distributed on an "AS IS" BASIS,
13 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 *  See the License for the specific language governing permissions and
15 *  limitations under the License.
16 */
17
18package java.lang;
19
20import java.io.InputStream;
21import java.io.OutputStream;
22
23/**
24 * Represents an external process. Enables writing to, reading from, destroying,
25 * and waiting for the external process, as well as querying its exit value. Use
26 * {@link ProcessBuilder} to create processes.
27 *
28 * <p>The child process writes its output to two streams, {@code out} and
29 * {@code err}. These streams should be read by the parent process using {@link
30 * #getInputStream()} and {@link #getErrorStream()} respectively. If these
31 * streams are not read, the target process may block while it awaits buffer
32 * space. It isn't sufficient to read the streams in sequence; to avoid blocking
33 * each of the two streams must have its own reader thread. If you are not
34 * interested in differentiating the out and err streams, use {@link
35 * ProcessBuilder#redirectErrorStream(boolean) redirectErrorStream(true)} to
36 * merge the two streams. This simplifies your reading code and makes it easier
37 * to avoid blocking the target process.
38 *
39 * <p>Running processes hold resources. When a process is no longer used, the
40 * process should be closed by calling {@link #destroy}. This will kill the
41 * process and release the resources that it holds.
42 *
43 * <p>For example, to run {@code /system/bin/ping} to ping {@code android.com}:
44 * <pre>   {@code
45 *   Process process = new ProcessBuilder()
46 *       .command("/system/bin/ping", "android.com")
47 *       .redirectErrorStream(true)
48 *       .start();
49 *   try {
50 *     InputStream in = process.getInputStream();
51 *     OutputStream out = process.getOutputStream();
52 *
53 *     readStream(in);
54 *
55 *   } finally {
56 *     process.destroy();
57 *   }
58 * }</pre>
59 */
60public abstract class Process {
61
62    /**
63     * Terminates this process and closes any associated streams.
64     */
65    abstract public void destroy();
66
67    /**
68     * Returns the exit value of the native process represented by this object.
69     * It is available only when the native process has terminated.
70     *
71     * @return the exit value of this process.
72     * @throws IllegalThreadStateException
73     *             if this process has not terminated.
74     */
75    abstract public int exitValue();
76
77    /**
78     * Returns an input stream that is connected to the error stream
79     * <em>(stderr)</em> of the native process represented by this object.
80     *
81     * @return the input stream to read from the error stream associated with
82     *         the native process.
83     */
84    abstract public InputStream getErrorStream();
85
86    /**
87     * Returns an input stream that is connected to the standard output stream
88     * <em>(stdout)</em> of the native process represented by this object.
89     *
90     * @return the input stream to read from the output stream associated with
91     *         the native process.
92     */
93    abstract public InputStream getInputStream();
94
95    /**
96     * Returns an output stream that is connected to the standard input stream
97     * <em>(stdin)</em> of the native process represented by this object.
98     *
99     * @return the output stream to write to the input stream associated with
100     *         the native process.
101     */
102    abstract public OutputStream getOutputStream();
103
104    /**
105     * Causes the calling thread to wait for the native process associated with
106     * this object to finish executing.
107     *
108     * @return the exit value of the native process being waited on.
109     * @throws InterruptedException
110     *             if the calling thread is interrupted.
111     */
112    abstract public int waitFor() throws InterruptedException;
113}
114