1 /* 2 * Copyright (c) 2014, 2015, 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 package java.lang; 26 27 import java.time.Duration; 28 import java.time.Instant; 29 import java.util.Optional; 30 import java.util.concurrent.CompletableFuture; 31 import java.util.stream.Stream; 32 33 /** 34 * ProcessHandle identifies and provides control of native processes. Each 35 * individual process can be monitored for liveness, list its children, 36 * get information about the process or destroy it. 37 * By comparison, {@link java.lang.Process Process} instances were started 38 * by the current process and additionally provide access to the process 39 * input, output, and error streams. 40 * <p> 41 * The native process ID is an identification number that the 42 * operating system assigns to the process. 43 * The range for process id values is dependent on the operating system. 44 * For example, an embedded system might use a 16-bit value. 45 * Status information about a process is retrieved from the native system 46 * and may change asynchronously; processes may be created or terminate 47 * spontaneously. 48 * The time between when a process terminates and the process id 49 * is reused for a new process is unpredictable. 50 * Race conditions can exist between checking the status of a process and 51 * acting upon it. When using ProcessHandles avoid assumptions 52 * about the liveness or identity of the underlying process. 53 * <p> 54 * Each ProcessHandle identifies and allows control of a process in the native 55 * system. ProcessHandles are returned from the factory methods {@link #current()}, 56 * {@link #of(long)}, 57 * {@link #children}, {@link #allChildren}, {@link #parent()} and 58 * {@link #allProcesses()}. 59 * <p> 60 * The {@link Process} instances created by {@link ProcessBuilder} can be queried 61 * for a ProcessHandle that provides information about the Process. 62 * ProcessHandle references should not be freely distributed. 63 * 64 * <p> 65 * A {@link java.util.concurrent.CompletableFuture} available from {@link #onExit} 66 * can be used to wait for process termination, and possibly trigger dependent 67 * actions. 68 * <p> 69 * The factory methods limit access to ProcessHandles using the 70 * SecurityManager checking the {@link RuntimePermission RuntimePermission("manageProcess")}. 71 * The ability to control processes is also restricted by the native system, 72 * ProcessHandle provides no more access to, or control over, the native process 73 * than would be allowed by a native application. 74 * <p> 75 * @implSpec 76 * In the case where ProcessHandles cannot be supported then the factory 77 * methods must consistently throw {@link java.lang.UnsupportedOperationException}. 78 * The methods of this class throw {@link java.lang.UnsupportedOperationException} 79 * if the operating system does not allow access to query or kill a process. 80 * 81 * @see Process 82 * @since 1.9 83 */ 84 public interface ProcessHandle extends Comparable<ProcessHandle> { 85 86 /** 87 * Returns the native process ID of the process. The native process ID is an 88 * identification number that the operating system assigns to the process. 89 * 90 * @return the native process ID of the process 91 * @throws UnsupportedOperationException if the implementation 92 * does not support this operation 93 */ 94 long getPid(); 95 96 /** 97 * Returns an {@code Optional<ProcessHandle>} for an existing native process. 98 * 99 * @param pid a native process ID 100 * @return an {@code Optional<ProcessHandle>} of the PID for the process; 101 * the {@code Optional} is empty if the process does not exist 102 * @throws SecurityException if a security manager has been installed and 103 * it denies RuntimePermission("manageProcess") 104 * @throws UnsupportedOperationException if the implementation 105 * does not support this operation 106 */ 107 public static Optional<ProcessHandle> of(long pid) { 108 return ProcessHandleImpl.get(pid); 109 } 110 111 /** 112 * Returns a ProcessHandle for the current process. The ProcessHandle cannot be 113 * used to destroy the current process, use {@link System#exit System.exit} instead. 114 * 115 * @return a ProcessHandle for the current process 116 * @throws SecurityException if a security manager has been installed and 117 * it denies RuntimePermission("manageProcess") 118 * @throws UnsupportedOperationException if the implementation 119 * does not support this operation 120 */ 121 public static ProcessHandle current() { 122 return ProcessHandleImpl.current(); 123 } 124 125 /** 126 * Returns an {@code Optional<ProcessHandle>} for the parent process. 127 * Note that Processes in a zombie state usually don't have a parent. 128 * 129 * @return an {@code Optional<ProcessHandle>} of the parent process; 130 * the {@code Optional} is empty if the child process does not have a parent 131 * or if the parent is not available, possibly due to operating system limitations 132 * @throws SecurityException if a security manager has been installed and 133 * it denies RuntimePermission("manageProcess") 134 */ 135 Optional<ProcessHandle> parent(); 136 137 /** 138 * Returns a snapshot of the current direct children of the process. 139 * A process that is {@link #isAlive not alive} has zero children. 140 * <p> 141 * <em>Note that processes are created and terminate asynchronously. 142 * There is no guarantee that a process is {@link #isAlive alive}. 143 * </em> 144 * 145 * @return a Stream of ProcessHandles for processes that are direct children 146 * of the process 147 * @throws SecurityException if a security manager has been installed and 148 * it denies RuntimePermission("manageProcess") 149 */ 150 Stream<ProcessHandle> children(); 151 152 /** 153 * Returns a snapshot of the current direct and indirect children of the process. 154 * A process that is {@link #isAlive not alive} has zero children. 155 * <p> 156 * <em>Note that processes are created and terminate asynchronously. 157 * There is no guarantee that a process is {@link #isAlive alive}. 158 * </em> 159 * 160 * @return a Stream of ProcessHandles for processes that are direct and 161 * indirect children of the process 162 * @throws SecurityException if a security manager has been installed and 163 * it denies RuntimePermission("manageProcess") 164 */ 165 Stream<ProcessHandle> allChildren(); 166 167 /** 168 * Returns a snapshot of all processes visible to the current process. 169 * <p> 170 * <em>Note that processes are created and terminate asynchronously. There 171 * is no guarantee that a process in the stream is alive or that no other 172 * processes may have been created since the inception of the snapshot. 173 * </em> 174 * 175 * @return a Stream of ProcessHandles for all processes 176 * @throws SecurityException if a security manager has been installed and 177 * it denies RuntimePermission("manageProcess") 178 * @throws UnsupportedOperationException if the implementation 179 * does not support this operation 180 */ 181 static Stream<ProcessHandle> allProcesses() { 182 return ProcessHandleImpl.children(0); 183 } 184 185 /** 186 * Returns a snapshot of information about the process. 187 * 188 * <p> An {@code Info} instance has various accessor methods that return 189 * information about the process, if the process is alive and the 190 * information is available. 191 * 192 * @return a snapshot of information about the process, always non-null 193 */ 194 Info info(); 195 196 /** 197 * Information snapshot about the process. 198 * The attributes of a process vary by operating system and are not available 199 * in all implementations. Information about processes is limited 200 * by the operating system privileges of the process making the request. 201 * The return types are {@code Optional<T>} allowing explicit tests 202 * and actions if the value is available. 203 * @since 1.9 204 */ 205 public interface Info { 206 /** 207 * Returns the executable pathname of the process. 208 * 209 * @return an {@code Optional<String>} of the executable pathname 210 * of the process 211 */ 212 public Optional<String> command(); 213 214 /** 215 * Returns an array of Strings of the arguments of the process. 216 * 217 * @return an {@code Optional<String[]>} of the arguments of the process 218 */ 219 public Optional<String[]> arguments(); 220 221 /** 222 * Returns the start time of the process. 223 * 224 * @return an {@code Optional<Instant>} of the start time of the process 225 */ 226 public Optional<Instant> startInstant(); 227 228 /** 229 * Returns the total cputime accumulated of the process. 230 * 231 * @return an {@code Optional<Duration>} for the accumulated total cputime 232 */ 233 public Optional<Duration> totalCpuDuration(); 234 235 /** 236 * Return the user of the process. 237 * 238 * @return an {@code Optional<String>} for the user of the process 239 */ 240 public Optional<String> user(); 241 } 242 243 /** 244 * Returns a {@code CompletableFuture<ProcessHandle>} for the termination 245 * of the process. 246 * The {@link java.util.concurrent.CompletableFuture} provides the ability 247 * to trigger dependent functions or actions that may be run synchronously 248 * or asynchronously upon process termination. 249 * When the process terminates the CompletableFuture is 250 * {@link java.util.concurrent.CompletableFuture#complete completed} regardless 251 * of the exit status of the process. 252 * The {@code onExit} method can be called multiple times to invoke 253 * independent actions when the process exits. 254 * <p> 255 * Calling {@code onExit().get()} waits for the process to terminate and returns 256 * the ProcessHandle. The future can be used to check if the process is 257 * {@link java.util.concurrent.CompletableFuture#isDone done} or to 258 * {@link java.util.concurrent.Future#get() wait} for it to terminate. 259 * {@link java.util.concurrent.Future#cancel(boolean) Cancelling} 260 * the CompleteableFuture does not affect the Process. 261 * <p> 262 * If the process is {@link #isAlive not alive} the {@link CompletableFuture} 263 * returned has been {@link java.util.concurrent.CompletableFuture#complete completed}. 264 * 265 * @return a new {@code CompletableFuture<ProcessHandle>} for the ProcessHandle 266 * 267 * @throws IllegalStateException if the process is the current process 268 */ 269 CompletableFuture<ProcessHandle> onExit(); 270 271 /** 272 * Returns {@code true} if the implementation of {@link #destroy} 273 * normally terminates the process. 274 * Returns {@code false} if the implementation of {@code destroy} 275 * forcibly and immediately terminates the process. 276 * 277 * @return {@code true} if the implementation of {@link #destroy} 278 * normally terminates the process; 279 * otherwise, {@link #destroy} forcibly terminates the process 280 */ 281 boolean supportsNormalTermination(); 282 283 /** 284 * Requests the process to be killed. 285 * Whether the process represented by this {@code ProcessHandle} object is 286 * {@link #supportsNormalTermination normally terminated} or not is 287 * implementation dependent. 288 * Forcible process destruction is defined as the immediate termination of the 289 * process, whereas normal termination allows the process to shut down cleanly. 290 * If the process is not alive, no action is taken. 291 * The operating system access controls may prevent the process 292 * from being killed. 293 * <p> 294 * The {@link java.util.concurrent.CompletableFuture} from {@link #onExit} is 295 * {@link java.util.concurrent.CompletableFuture#complete completed} 296 * when the process has terminated. 297 * <p> 298 * Note: The process may not terminate immediately. 299 * For example, {@code isAlive()} may return true for a brief period 300 * after {@code destroy()} is called. 301 * 302 * @return {@code true} if termination was successfully requested, 303 * otherwise {@code false} 304 * @throws IllegalStateException if the process is the current process 305 */ 306 boolean destroy(); 307 308 /** 309 * Requests the process to be killed forcibly. 310 * The process represented by this {@code ProcessHandle} object is 311 * forcibly terminated. 312 * Forcible process destruction is defined as the immediate termination of the 313 * process, whereas normal termination allows the process to shut down cleanly. 314 * If the process is not alive, no action is taken. 315 * The operating system access controls may prevent the process 316 * from being killed. 317 * <p> 318 * The {@link java.util.concurrent.CompletableFuture} from {@link #onExit} is 319 * {@link java.util.concurrent.CompletableFuture#complete completed} 320 * when the process has terminated. 321 * <p> 322 * Note: The process may not terminate immediately. 323 * For example, {@code isAlive()} may return true for a brief period 324 * after {@code destroyForcibly()} is called. 325 * 326 * @return {@code true} if termination was successfully requested, 327 * otherwise {@code false} 328 * @throws IllegalStateException if the process is the current process 329 */ 330 boolean destroyForcibly(); 331 332 /** 333 * Tests whether the process represented by this {@code ProcessHandle} is alive. 334 * Process termination is implementation and operating system specific. 335 * The process is considered alive as long as the PID is valid. 336 * 337 * @return {@code true} if the process represented by this 338 * {@code ProcessHandle} object has not yet terminated 339 */ 340 boolean isAlive(); 341 342 /** 343 * Compares this ProcessHandle with the specified ProcessHandle for order. 344 * The order is not specified, but is consistent with {@link Object#equals}, 345 * which returns {@code true} if and only if two instances of ProcessHandle 346 * are of the same implementation and represent the same system process. 347 * Comparison is only supported among objects of same implementation. 348 * If attempt is made to mutually compare two different implementations 349 * of {@link ProcessHandle}s, {@link ClassCastException} is thrown. 350 * 351 * @param other the ProcessHandle to be compared 352 * @return a negative integer, zero, or a positive integer as this object 353 * is less than, equal to, or greater than the specified object. 354 * @throws NullPointerException if the specified object is null 355 * @throws ClassCastException if the specified object is not of same class 356 * as this object 357 */ 358 @Override 359 int compareTo(ProcessHandle other); 360 361 }