1 /* 2 * Copyright (c) 2014, 2017, 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 #descendants}, {@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 * 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 * <p> 82 * The {@code ProcessHandle} static factory methods return instances that are 83 * <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>, 84 * immutable and thread-safe. 85 * Use of identity-sensitive operations (including reference equality 86 * ({@code ==}), identity hash code, or synchronization) on these instances of 87 * {@code ProcessHandle} may have unpredictable results and should be avoided. 88 * Use {@link #equals(Object) equals} or 89 * {@link #compareTo(ProcessHandle) compareTo} methods to compare ProcessHandles. 90 * 91 * @see Process 92 * @since 9 93 */ 94 public interface ProcessHandle extends Comparable<ProcessHandle> { 95 96 /** 97 * Returns the native process ID of the process. The native process ID is an 98 * identification number that the operating system assigns to the process. 99 * The operating system may reuse the process ID after a process terminates. 100 * Use {@link #equals(Object) equals} or 101 * {@link #compareTo(ProcessHandle) compareTo} to compare ProcessHandles. 102 * 103 * @return the native process ID of the process 104 * @throws UnsupportedOperationException if the implementation 105 * does not support this operation 106 */ 107 long pid(); 108 109 /** 110 * Returns an {@code Optional<ProcessHandle>} for an existing native process. 111 * 112 * @param pid a native process ID 113 * @return an {@code Optional<ProcessHandle>} of the PID for the process; 114 * the {@code Optional} is empty if the process does not exist 115 * @throws SecurityException if a security manager has been installed and 116 * it denies RuntimePermission("manageProcess") 117 * @throws UnsupportedOperationException if the implementation 118 * does not support this operation 119 */ 120 public static Optional<ProcessHandle> of(long pid) { 121 return ProcessHandleImpl.get(pid); 122 } 123 124 /** 125 * Returns a ProcessHandle for the current process. The ProcessHandle cannot be 126 * used to destroy the current process, use {@link System#exit System.exit} instead. 127 * 128 * @return a ProcessHandle for the current process 129 * @throws SecurityException if a security manager has been installed and 130 * it denies RuntimePermission("manageProcess") 131 * @throws UnsupportedOperationException if the implementation 132 * does not support this operation 133 */ 134 public static ProcessHandle current() { 135 return ProcessHandleImpl.current(); 136 } 137 138 /** 139 * Returns an {@code Optional<ProcessHandle>} for the parent process. 140 * Note that Processes in a zombie state usually don't have a parent. 141 * 142 * @return an {@code Optional<ProcessHandle>} of the parent process; 143 * the {@code Optional} is empty if the child process does not have a parent 144 * or if the parent is not available, possibly due to operating system limitations 145 * @throws SecurityException if a security manager has been installed and 146 * it denies RuntimePermission("manageProcess") 147 */ 148 Optional<ProcessHandle> parent(); 149 150 /** 151 * Returns a snapshot of the current direct children of the process. 152 * The {@link #parent} of a direct child process is the process. 153 * Typically, a process that is {@link #isAlive not alive} has no children. 154 * <p> 155 * <em>Note that processes are created and terminate asynchronously. 156 * There is no guarantee that a process is {@link #isAlive alive}. 157 * </em> 158 * 159 * @return a sequential Stream of ProcessHandles for processes that are 160 * direct children of the process 161 * @throws SecurityException if a security manager has been installed and 162 * it denies RuntimePermission("manageProcess") 163 */ 164 Stream<ProcessHandle> children(); 165 166 /** 167 * Returns a snapshot of the descendants of the process. 168 * The descendants of a process are the children of the process 169 * plus the descendants of those children, recursively. 170 * Typically, a process that is {@link #isAlive not alive} has no children. 171 * <p> 172 * <em>Note that processes are created and terminate asynchronously. 173 * There is no guarantee that a process is {@link #isAlive alive}. 174 * </em> 175 * 176 * @return a sequential Stream of ProcessHandles for processes that 177 * are descendants of the process 178 * @throws SecurityException if a security manager has been installed and 179 * it denies RuntimePermission("manageProcess") 180 */ 181 Stream<ProcessHandle> descendants(); 182 183 /** 184 * Returns a snapshot of all processes visible to the current process. 185 * <p> 186 * <em>Note that processes are created and terminate asynchronously. There 187 * is no guarantee that a process in the stream is alive or that no other 188 * processes may have been created since the inception of the snapshot. 189 * </em> 190 * 191 * @return a Stream of ProcessHandles for all processes 192 * @throws SecurityException if a security manager has been installed and 193 * it denies RuntimePermission("manageProcess") 194 * @throws UnsupportedOperationException if the implementation 195 * does not support this operation 196 */ 197 static Stream<ProcessHandle> allProcesses() { 198 return ProcessHandleImpl.children(0); 199 } 200 201 /** 202 * Returns a snapshot of information about the process. 203 * 204 * <p> A {@link ProcessHandle.Info} instance has accessor methods that return 205 * information about the process if it is available. 206 * 207 * @return a snapshot of information about the process, always non-null 208 */ 209 Info info(); 210 211 /** 212 * Information snapshot about the process. 213 * The attributes of a process vary by operating system and are not available 214 * in all implementations. Information about processes is limited 215 * by the operating system privileges of the process making the request. 216 * The return types are {@code Optional<T>} allowing explicit tests 217 * and actions if the value is available. 218 * @since 9 219 */ 220 public interface Info { 221 /** 222 * Returns the executable pathname of the process. 223 * 224 * @return an {@code Optional<String>} of the executable pathname 225 * of the process 226 */ 227 public Optional<String> command(); 228 229 /** 230 * Returns the command line of the process. 231 * <p> 232 * If {@link #command command()} and {@link #arguments arguments()} return 233 * non-empty optionals, this is simply a convenience method which concatenates 234 * the values of the two functions separated by spaces. Otherwise it will return a 235 * best-effort, platform dependent representation of the command line. 236 * 237 * @apiNote Note that the returned executable pathname and the 238 * arguments may be truncated on some platforms due to system 239 * limitations. 240 * <p> 241 * The executable pathname may contain only the 242 * name of the executable without the full path information. 243 * It is undecideable whether white space separates different 244 * arguments or is part of a single argument. 245 * 246 * @return an {@code Optional<String>} of the command line 247 * of the process 248 */ 249 public Optional<String> commandLine(); 250 251 /** 252 * Returns an array of Strings of the arguments of the process. 253 * 254 * @apiNote On some platforms, native applications are free to change 255 * the arguments array after startup and this method may only 256 * show the changed values. 257 * 258 * @return an {@code Optional<String[]>} of the arguments of the process 259 */ 260 public Optional<String[]> arguments(); 261 262 /** 263 * Returns the start time of the process. 264 * 265 * @return an {@code Optional<Instant>} of the start time of the process 266 */ 267 public Optional<Instant> startInstant(); 268 269 /** 270 * Returns the total cputime accumulated of the process. 271 * 272 * @return an {@code Optional<Duration>} for the accumulated total cputime 273 */ 274 public Optional<Duration> totalCpuDuration(); 275 276 /** 277 * Return the user of the process. 278 * 279 * @return an {@code Optional<String>} for the user of the process 280 */ 281 public Optional<String> user(); 282 } 283 284 /** 285 * Returns a {@code CompletableFuture<ProcessHandle>} for the termination 286 * of the process. 287 * The {@link java.util.concurrent.CompletableFuture} provides the ability 288 * to trigger dependent functions or actions that may be run synchronously 289 * or asynchronously upon process termination. 290 * When the process has terminated the CompletableFuture is 291 * {@link java.util.concurrent.CompletableFuture#complete completed} regardless 292 * of the exit status of the process. 293 * The {@code onExit} method can be called multiple times to invoke 294 * independent actions when the process exits. 295 * <p> 296 * Calling {@code onExit().get()} waits for the process to terminate and returns 297 * the ProcessHandle. The future can be used to check if the process is 298 * {@link java.util.concurrent.CompletableFuture#isDone done} or to 299 * {@link java.util.concurrent.Future#get() wait} for it to terminate. 300 * {@link java.util.concurrent.Future#cancel(boolean) Cancelling} 301 * the CompleteableFuture does not affect the Process. 302 * @apiNote 303 * The process may be observed to have terminated with {@link #isAlive} 304 * before the ComputableFuture is completed and dependent actions are invoked. 305 * 306 * @return a new {@code CompletableFuture<ProcessHandle>} for the ProcessHandle 307 * 308 * @throws IllegalStateException if the process is the current process 309 */ 310 CompletableFuture<ProcessHandle> onExit(); 311 312 /** 313 * Returns {@code true} if the implementation of {@link #destroy} 314 * normally terminates the process. 315 * Returns {@code false} if the implementation of {@code destroy} 316 * forcibly and immediately terminates the process. 317 * 318 * @return {@code true} if the implementation of {@link #destroy} 319 * normally terminates the process; 320 * otherwise, {@link #destroy} forcibly terminates the process 321 */ 322 boolean supportsNormalTermination(); 323 324 /** 325 * Requests the process to be killed. 326 * Whether the process represented by this {@code ProcessHandle} object is 327 * {@link #supportsNormalTermination normally terminated} or not is 328 * implementation dependent. 329 * Forcible process destruction is defined as the immediate termination of the 330 * process, whereas normal termination allows the process to shut down cleanly. 331 * If the process is not alive, no action is taken. 332 * The operating system access controls may prevent the process 333 * from being killed. 334 * <p> 335 * The {@link java.util.concurrent.CompletableFuture} from {@link #onExit} is 336 * {@link java.util.concurrent.CompletableFuture#complete completed} 337 * when the process has terminated. 338 * <p> 339 * Note: The process may not terminate immediately. 340 * For example, {@code isAlive()} may return true for a brief period 341 * after {@code destroy()} is called. 342 * 343 * @return {@code true} if termination was successfully requested, 344 * otherwise {@code false} 345 * @throws IllegalStateException if the process is the current process 346 */ 347 boolean destroy(); 348 349 /** 350 * Requests the process to be killed forcibly. 351 * The process represented by this {@code ProcessHandle} object is 352 * forcibly terminated. 353 * Forcible process destruction is defined as the immediate termination of the 354 * process, whereas normal termination allows the process to shut down cleanly. 355 * If the process is not alive, no action is taken. 356 * The operating system access controls may prevent the process 357 * from being killed. 358 * <p> 359 * The {@link java.util.concurrent.CompletableFuture} from {@link #onExit} is 360 * {@link java.util.concurrent.CompletableFuture#complete completed} 361 * when the process has terminated. 362 * <p> 363 * Note: The process may not terminate immediately. 364 * For example, {@code isAlive()} may return true for a brief period 365 * after {@code destroyForcibly()} is called. 366 * 367 * @return {@code true} if termination was successfully requested, 368 * otherwise {@code false} 369 * @throws IllegalStateException if the process is the current process 370 */ 371 boolean destroyForcibly(); 372 373 /** 374 * Tests whether the process represented by this {@code ProcessHandle} is alive. 375 * Process termination is implementation and operating system specific. 376 * The process is considered alive as long as the PID is valid. 377 * 378 * @return {@code true} if the process represented by this 379 * {@code ProcessHandle} object has not yet terminated 380 */ 381 boolean isAlive(); 382 383 /** 384 * Returns a hash code value for this ProcessHandle. 385 * The hashcode value follows the general contract for {@link Object#hashCode()}. 386 * The value is a function of the {@link #pid pid()} value and 387 * may be a function of additional information to uniquely identify the process. 388 * If two ProcessHandles are equal according to the {@link #equals(Object) equals} 389 * method, then calling the hashCode method on each of the two objects 390 * must produce the same integer result. 391 * 392 * @return a hash code value for this object 393 */ 394 @Override 395 int hashCode(); 396 397 /** 398 * Returns {@code true} if {@code other} object is non-null, is of the 399 * same implementation, and represents the same system process; 400 * otherwise it returns {@code false}. 401 * @implNote 402 * It is implementation specific whether ProcessHandles with the same PID 403 * represent the same system process. ProcessHandle implementations 404 * should contain additional information to uniquely identify the process. 405 * For example, the start time of the process could be used 406 * to determine if the PID has been re-used. 407 * The implementation of {@code equals} should return {@code true} for two 408 * ProcessHandles with the same PID unless there is information to 409 * distinguish them. 410 * 411 * @param other another object 412 * @return {@code true} if the {@code other} object is non-null, 413 * is of the same implementation class and represents 414 * the same system process; otherwise returns {@code false} 415 */ 416 @Override 417 boolean equals(Object other); 418 419 /** 420 * Compares this ProcessHandle with the specified ProcessHandle for order. 421 * The order is not specified, but is consistent with {@link Object#equals}, 422 * which returns {@code true} if and only if two instances of ProcessHandle 423 * are of the same implementation and represent the same system process. 424 * Comparison is only supported among objects of same implementation. 425 * If attempt is made to mutually compare two different implementations 426 * of {@link ProcessHandle}s, {@link ClassCastException} is thrown. 427 * 428 * @param other the ProcessHandle to be compared 429 * @return a negative integer, zero, or a positive integer as this object 430 * is less than, equal to, or greater than the specified object. 431 * @throws NullPointerException if the specified object is null 432 * @throws ClassCastException if the specified object is not of same class 433 * as this object 434 */ 435 @Override 436 int compareTo(ProcessHandle other); 437 438 }