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 18 package java.lang; 19 20 import java.io.InputStream; 21 import 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 */ 60 public abstract class Process { 61 62 /** 63 * Terminates this process and closes any associated streams. 64 */ destroy()65 public abstract 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 */ exitValue()75 public abstract 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 */ getErrorStream()84 public abstract 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 */ getInputStream()93 public abstract 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 */ getOutputStream()102 public abstract 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 */ waitFor()112 public abstract int waitFor() throws InterruptedException; 113 } 114