Comparable<ProcessHandle>public interface ProcessHandle extends Comparable<ProcessHandle>
Process instances were started by the current process and additionally provide access to the process input, output, and error streams. The native process ID is an identification number that the operating system assigns to the process. The range for process id values is dependent on the operating system. For example, an embedded system might use a 16-bit value. Status information about a process is retrieved from the native system and may change asynchronously; processes may be created or terminate spontaneously. The time between when a process terminates and the process id is reused for a new process is unpredictable. Race conditions can exist between checking the status of a process and acting upon it. When using ProcessHandles avoid assumptions about the liveness or identity of the underlying process.
Each ProcessHandle identifies and allows control of a process in the native system. ProcessHandles are returned from the factory methods current(), of(long), children(), descendants(), parent() and allProcesses().
The Process instances created by ProcessBuilder can be queried for a ProcessHandle that provides information about the Process. ProcessHandle references should not be freely distributed.
A CompletableFuture available from onExit() can be used to wait for process termination, and possibly trigger dependent actions.
The factory methods limit access to ProcessHandles using the SecurityManager checking the RuntimePermission("manageProcess"). The ability to control processes is also restricted by the native system, ProcessHandle provides no more access to, or control over, the native process than would be allowed by a native application.
UnsupportedOperationException. The methods of this class throw UnsupportedOperationException if the operating system does not allow access to query or kill a process. The ProcessHandle static factory methods return instances that are value-based, immutable and thread-safe. Programmers should treat instances that are equal as interchangeable and should not use instances for synchronization, or unpredictable behavior may occur. For example, in a future release, synchronization may fail. Use the equals or compareTo methods to compare ProcessHandles.
| Modifier and Type | Interface | Description |
|---|---|---|
static interface |
ProcessHandle.Info |
Information snapshot about the process. |
| Modifier and Type | Method | Description |
|---|---|---|
static Stream |
allProcesses() |
Returns a snapshot of all processes visible to the current process. |
Stream |
children() |
Returns a snapshot of the current direct children of the process. |
int |
compareTo |
Compares this ProcessHandle with the specified ProcessHandle for order. |
static ProcessHandle |
current() |
Returns a ProcessHandle for the current process. |
Stream |
descendants() |
Returns a snapshot of the descendants of the process. |
boolean |
destroy() |
Requests the process to be killed. |
boolean |
destroyForcibly() |
Requests the process to be killed forcibly. |
boolean |
equals |
Returns true if other object is non-null, is of the same implementation, and represents the same system process; otherwise it returns false. |
int |
hashCode() |
Returns a hash code value for this ProcessHandle. |
ProcessHandle.Info |
info() |
Returns a snapshot of information about the process. |
boolean |
isAlive() |
Tests whether the process represented by this ProcessHandle is alive. |
static Optional |
of |
Returns an Optional<ProcessHandle> for an existing native process. |
CompletableFuture |
onExit() |
Returns a CompletableFuture<ProcessHandle> for the termination of the process. |
Optional |
parent() |
Returns an Optional<ProcessHandle> for the parent process. |
long |
pid() |
Returns the native process ID of the process. |
boolean |
supportsNormalTermination() |
Returns true if the implementation of destroy() normally terminates the process. |
long pid()
equals or compareTo to compare ProcessHandles.UnsupportedOperationException - if the implementation does not support this operationstatic Optional<ProcessHandle> of(long pid)
Optional<ProcessHandle> for an existing native process.pid - a native process IDOptional<ProcessHandle> of the PID for the process; the Optional is empty if the process does not existSecurityException - if a security manager has been installed and it denies RuntimePermission("manageProcess")UnsupportedOperationException - if the implementation does not support this operationstatic ProcessHandle current()
System.exit instead.SecurityException - if a security manager has been installed and it denies RuntimePermission("manageProcess")UnsupportedOperationException - if the implementation does not support this operationOptional<ProcessHandle> parent()
Optional<ProcessHandle> for the parent process. Note that Processes in a zombie state usually don't have a parent.Optional<ProcessHandle> of the parent process; the Optional is empty if the child process does not have a parent or if the parent is not available, possibly due to operating system limitationsSecurityException - if a security manager has been installed and it denies RuntimePermission("manageProcess")Stream<ProcessHandle> children()
parent() of a direct child process is the process. Typically, a process that is not alive has no children. Note that processes are created and terminate asynchronously. There is no guarantee that a process is alive.
SecurityException - if a security manager has been installed and it denies RuntimePermission("manageProcess")Stream<ProcessHandle> descendants()
not alive has no children. Note that processes are created and terminate asynchronously. There is no guarantee that a process is alive.
SecurityException - if a security manager has been installed and it denies RuntimePermission("manageProcess")static Stream<ProcessHandle> allProcesses()
Note that processes are created and terminate asynchronously. There is no guarantee that a process in the stream is alive or that no other processes may have been created since the inception of the snapshot.
SecurityException - if a security manager has been installed and it denies RuntimePermission("manageProcess")UnsupportedOperationException - if the implementation does not support this operationProcessHandle.Info info()
A ProcessHandle.Info instance has accessor methods that return information about the process if it is available.
CompletableFuture<ProcessHandle> onExit()
CompletableFuture<ProcessHandle> for the termination of the process. The CompletableFuture provides the ability to trigger dependent functions or actions that may be run synchronously or asynchronously upon process termination. When the process has terminated the CompletableFuture is completed regardless of the exit status of the process. The onExit method can be called multiple times to invoke independent actions when the process exits. Calling onExit().get() waits for the process to terminate and returns the ProcessHandle. The future can be used to check if the process is done or to wait for it to terminate. Cancelling the CompleteableFuture does not affect the Process.
isAlive() before the ComputableFuture is completed and dependent actions are invoked.CompletableFuture<ProcessHandle> for the ProcessHandleIllegalStateException - if the process is the current processboolean supportsNormalTermination()
true if the implementation of destroy() normally terminates the process. Returns false if the implementation of destroy forcibly and immediately terminates the process.boolean destroy()
ProcessHandle object is normally terminated or not is implementation dependent. Forcible process destruction is defined as the immediate termination of the process, whereas normal termination allows the process to shut down cleanly. If the process is not alive, no action is taken. The operating system access controls may prevent the process from being killed. The CompletableFuture from onExit() is completed when the process has terminated.
Note: The process may not terminate immediately. For example, isAlive() may return true for a brief period after destroy() is called.
true if termination was successfully requested, otherwise false
IllegalStateException - if the process is the current processboolean destroyForcibly()
ProcessHandle object is forcibly terminated. Forcible process destruction is defined as the immediate termination of the process, whereas normal termination allows the process to shut down cleanly. If the process is not alive, no action is taken. The operating system access controls may prevent the process from being killed. The CompletableFuture from onExit() is completed when the process has terminated.
Note: The process may not terminate immediately. For example, isAlive() may return true for a brief period after destroyForcibly() is called.
true if termination was successfully requested, otherwise false
IllegalStateException - if the process is the current processboolean isAlive()
ProcessHandle is alive. Process termination is implementation and operating system specific. The process is considered alive as long as the PID is valid.true if the process represented by this ProcessHandle object has not yet terminatedint hashCode()
Object.hashCode(). The value is a function of the pid() value and may be a function of additional information to uniquely identify the process. If two ProcessHandles are equal according to the equals method, then calling the hashCode method on each of the two objects must produce the same integer result.boolean equals(Object other)
true if other object is non-null, is of the same implementation, and represents the same system process; otherwise it returns false.equals in class Object
equals should return true for two ProcessHandles with the same PID unless there is information to distinguish them.other - another objecttrue if the other object is non-null, is of the same implementation class and represents the same system process; otherwise returns false
int compareTo(ProcessHandle other)
Object.equals(java.lang.Object), which returns true if and only if two instances of ProcessHandle are of the same implementation and represent the same system process. Comparison is only supported among objects of same implementation. If attempt is made to mutually compare two different implementations of ProcessHandles, ClassCastException is thrown.compareTo in interface Comparable<ProcessHandle>
other - the ProcessHandle to be comparedNullPointerException - if the specified object is nullClassCastException - if the specified object is not of same class as this object
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/ProcessHandle.html