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 */ 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
