- All Superinterfaces:
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.
- Implementation Requirements:
- In the case where ProcessHandles cannot be supported then the factory
methods must consistently throw
UnsupportedOperationException
. The methods of this class throwUnsupportedOperationException
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. Use of identity-sensitive operations (including reference equality (==
), identity hash code, or synchronization) on these instances ofProcessHandle
may have unpredictable results and should be avoided. Useequals
orcompareTo
methods to compare ProcessHandles. - Since:
- 9
- See Also:
Process
-
Nested Class Summary
Modifier and TypeInterfaceDescriptionstatic interface
Information snapshot about the process. -
Method Summary
Modifier and TypeMethodDescriptionstatic Stream<ProcessHandle>
Returns a snapshot of all processes visible to the current process.children()
Returns a snapshot of the current direct children of the process.int
compareTo(ProcessHandle other)
Compares this ProcessHandle with the specified ProcessHandle for order.static ProcessHandle
current()
Returns a ProcessHandle for the current process.Returns a snapshot of the descendants of the process.boolean
destroy()
Requests the process to be killed.boolean
Requests the process to be killed forcibly.boolean
Returnstrue
ifother
object is non-null, is of the same implementation, and represents the same system process; otherwise it returnsfalse
.int
hashCode()
Returns a hash code value for this ProcessHandle.info()
Returns a snapshot of information about the process.boolean
isAlive()
Tests whether the process represented by thisProcessHandle
is alive.static Optional<ProcessHandle>
of(long pid)
Returns anOptional<ProcessHandle>
for an existing native process.onExit()
Returns aCompletableFuture<ProcessHandle>
for the termination of the process.parent()
Returns anOptional<ProcessHandle>
for the parent process.long
pid()
Returns the native process ID of the process.boolean
Returnstrue
if the implementation ofdestroy()
normally terminates the process.
-
Method Details
-
pid
long pid()Returns the native process ID of the process. The native process ID is an identification number that the operating system assigns to the process. The operating system may reuse the process ID after a process terminates. Useequals
orcompareTo
to compare ProcessHandles.- Returns:
- the native process ID of the process
- Throws:
UnsupportedOperationException
- if the implementation does not support this operation
-
of
Returns anOptional<ProcessHandle>
for an existing native process.- Parameters:
pid
- a native process ID- Returns:
- an
Optional<ProcessHandle>
of the PID for the process; theOptional
is empty if the process does not exist - Throws:
SecurityException
- if a security manager has been installed and it denies RuntimePermission("manageProcess")UnsupportedOperationException
- if the implementation does not support this operation
-
current
Returns a ProcessHandle for the current process. The ProcessHandle cannot be used to destroy the current process, useSystem.exit
instead.- Returns:
- a ProcessHandle for the current process
- Throws:
SecurityException
- if a security manager has been installed and it denies RuntimePermission("manageProcess")UnsupportedOperationException
- if the implementation does not support this operation
-
parent
Optional<ProcessHandle> parent()Returns anOptional<ProcessHandle>
for the parent process. Note that Processes in a zombie state usually don't have a parent.- Returns:
- an
Optional<ProcessHandle>
of the parent process; theOptional
is empty if the child process does not have a parent or if the parent is not available, possibly due to operating system limitations - Throws:
SecurityException
- if a security manager has been installed and it denies RuntimePermission("manageProcess")
-
children
Stream<ProcessHandle> children()Returns a snapshot of the current direct children of the process. Theparent()
of a direct child process is the process. Typically, a process that isnot alive
has no children.Note that processes are created and terminate asynchronously. There is no guarantee that a process is
alive
.- Returns:
- a sequential Stream of ProcessHandles for processes that are direct children of the process
- Throws:
SecurityException
- if a security manager has been installed and it denies RuntimePermission("manageProcess")
-
descendants
Stream<ProcessHandle> descendants()Returns a snapshot of the descendants of the process. The descendants of a process are the children of the process plus the descendants of those children, recursively. Typically, a process that isnot alive
has no children.Note that processes are created and terminate asynchronously. There is no guarantee that a process is
alive
.- Returns:
- a sequential Stream of ProcessHandles for processes that are descendants of the process
- Throws:
SecurityException
- if a security manager has been installed and it denies RuntimePermission("manageProcess")
-
allProcesses
Returns a snapshot of all processes visible to the current process.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.
- Returns:
- a Stream of ProcessHandles for all processes
- Throws:
SecurityException
- if a security manager has been installed and it denies RuntimePermission("manageProcess")UnsupportedOperationException
- if the implementation does not support this operation
-
info
ProcessHandle.Info info()Returns a snapshot of information about the process.A
ProcessHandle.Info
instance has accessor methods that return information about the process if it is available.- Returns:
- a snapshot of information about the process, always non-null
-
onExit
CompletableFuture<ProcessHandle> onExit()Returns aCompletableFuture<ProcessHandle>
for the termination of the process. TheCompletableFuture
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 iscompleted
regardless of the exit status of the process. TheonExit
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 isdone
or towait
for it to terminate.Cancelling
the CompleteableFuture does not affect the Process.- API Note:
- The process may be observed to have terminated with
isAlive()
before the ComputableFuture is completed and dependent actions are invoked. - Returns:
- a new
CompletableFuture<ProcessHandle>
for the ProcessHandle - Throws:
IllegalStateException
- if the process is the current process
-
supportsNormalTermination
boolean supportsNormalTermination()Returnstrue
if the implementation ofdestroy()
normally terminates the process. Returnsfalse
if the implementation ofdestroy
forcibly and immediately terminates the process. -
destroy
boolean destroy()Requests the process to be killed. Whether the process represented by thisProcessHandle
object isnormally 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
fromonExit()
iscompleted
when the process has terminated.Note: The process may not terminate immediately. For example,
isAlive()
may return true for a brief period afterdestroy()
is called.- Returns:
true
if termination was successfully requested, otherwisefalse
- Throws:
IllegalStateException
- if the process is the current process
-
destroyForcibly
boolean destroyForcibly()Requests the process to be killed forcibly. The process represented by thisProcessHandle
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
fromonExit()
iscompleted
when the process has terminated.Note: The process may not terminate immediately. For example,
isAlive()
may return true for a brief period afterdestroyForcibly()
is called.- Returns:
true
if termination was successfully requested, otherwisefalse
- Throws:
IllegalStateException
- if the process is the current process
-
isAlive
boolean isAlive()Tests whether the process represented by thisProcessHandle
is alive. Process termination is implementation and operating system specific. The process is considered alive as long as the PID is valid.- Returns:
true
if the process represented by thisProcessHandle
object has not yet terminated
-
hashCode
int hashCode()Returns a hash code value for this ProcessHandle. The hashcode value follows the general contract forObject.hashCode()
. The value is a function of thepid()
value and may be a function of additional information to uniquely identify the process. If two ProcessHandles are equal according to theequals
method, then calling the hashCode method on each of the two objects must produce the same integer result.- Overrides:
hashCode
in classObject
- Returns:
- a hash code value for this object
- See Also:
Object.equals(java.lang.Object)
,System.identityHashCode(java.lang.Object)
-
equals
Returnstrue
ifother
object is non-null, is of the same implementation, and represents the same system process; otherwise it returnsfalse
.- Overrides:
equals
in classObject
- Implementation Note:
- It is implementation specific whether ProcessHandles with the same PID
represent the same system process. ProcessHandle implementations
should contain additional information to uniquely identify the process.
For example, the start time of the process could be used
to determine if the PID has been re-used.
The implementation of
equals
should returntrue
for two ProcessHandles with the same PID unless there is information to distinguish them. - Parameters:
other
- another object- Returns:
true
if theother
object is non-null, is of the same implementation class and represents the same system process; otherwise returnsfalse
- See Also:
Object.hashCode()
,HashMap
-
compareTo
Compares this ProcessHandle with the specified ProcessHandle for order. The order is not specified, but is consistent withObject.equals(java.lang.Object)
, which returnstrue
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 ofProcessHandle
s,ClassCastException
is thrown.- Specified by:
compareTo
in interfaceComparable<ProcessHandle>
- Parameters:
other
- the ProcessHandle to be compared- Returns:
- a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.
- Throws:
NullPointerException
- if the specified object is nullClassCastException
- if the specified object is not of same class as this object
-