Interface ProcessHandle

All Superinterfaces:
Comparable<ProcessHandle>
public interfaceProcessHandleextendsComparable<ProcessHandle>
ProcessHandle identifies and provides control of native processes. Eachindividual process can be monitored for liveness, list its children,get information about the process or destroy it.By comparison,Process instances were startedby the current process and additionally provide access to the processinput, output, and error streams.

The native process ID is an identification number that theoperating 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 systemand may change asynchronously; processes may be created or terminatespontaneously.The time between when a process terminates and the process idis reused for a new process is unpredictable.Race conditions can exist between checking the status of a process andacting upon it. When using ProcessHandles avoid assumptionsabout the liveness or identity of the underlying process.

Each ProcessHandle identifies and allows control of a process in the nativesystem. ProcessHandles are returned from the factory methodscurrent(),of(long),children(),descendants(),parent() andallProcesses().

TheProcess instances created byProcessBuilder can be queriedfor a ProcessHandle that provides information about the Process.ProcessHandle references should not be freely distributed.

ACompletableFuture available fromonExit()can be used to wait for process termination, and possibly trigger dependentactions.

The ability to control processes may be restricted by the native system,ProcessHandle provides no more access to, or control over, the native processthan would be allowed by a native application.

Implementation Requirements:
In the case where ProcessHandles cannot be supported then the factorymethods must consistently throwUnsupportedOperationException.The methods of this class throwUnsupportedOperationExceptionif the operating system does not allow access to query or kill a process.

TheProcessHandle static factory methods return instances that arevalue-based,immutable and thread-safe. Programmers should treat instances that areequal as interchangeable and should notuse instances for synchronization, or unpredictable behavior may occur.For example, in a future release, synchronization may fail.Use theequals orcompareTo methodsto compare ProcessHandles.

Since:
9
See Also:

  • Method Details

    • pid

      long pid()
      Returns the native process ID of the process. The native process ID is anidentification 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

      static Optional<ProcessHandle> of(long pid)
      Returns anOptional<ProcessHandle> for an existing native process.
      Parameters:
      pid - a native process ID
      Returns:
      anOptional<ProcessHandle> of the PID for the process; theOptional is empty if the process does not exist
      Throws:
      UnsupportedOperationException - if the implementation does not support this operation

    • current

      static ProcessHandle current()
      Returns a ProcessHandle for the current process. The ProcessHandle cannot beused to destroy the current process, useSystem.exit instead.
      Returns:
      a ProcessHandle for the current process
      Throws:
      UnsupportedOperationException - if the implementation does not support this operation

    • parent

      Returns anOptional<ProcessHandle> for the parent process.Note that Processes in a zombie state usually don't have a parent.
      Returns:
      anOptional<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

    • 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 isalive.

      Returns:
      a sequential Stream of ProcessHandles for processes that are direct children of the process

    • descendants

      Stream<ProcessHandle> descendants()
      Returns a snapshot of the descendants of the process.The descendants of a process are the children of the processplus 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 isalive.

      Returns:
      a sequential Stream of ProcessHandles for processes that are descendants of the process

    • allProcesses

      static Stream<ProcessHandle> allProcesses()
      Returns a snapshot of all processes visible to the current process.

      Note that processes are created and terminate asynchronously. Thereis no guarantee that a process in the stream is alive or that no otherprocesses may have been created since the inception of the snapshot.

      Returns:
      a Stream of ProcessHandles for all processes
      Throws:
      UnsupportedOperationException - if the implementation does not support this operation

    • info

      Returns a snapshot of information about the process.

      AProcessHandle.Info instance has accessor methods that returninformation about the process if it is available.

      Returns:
      a snapshot of information about the process, always non-null

    • onExit

      Returns aCompletableFuture<ProcessHandle> for the terminationof the process.TheCompletableFuture provides the abilityto trigger dependent functions or actions that may be run synchronouslyor asynchronously upon process termination.When the process has terminated the CompletableFuture iscompleted regardlessof the exit status of the process.TheonExit method can be called multiple times to invokeindependent actions when the process exits.

      CallingonExit().get() waits for the process to terminate and returnsthe ProcessHandle. The future can be used to check if the process isdone or towait for it to terminate.CancellingtheCompletableFuture does not affect the Process.

      API Note:
      The process may be observed to have terminated withisAlive()before theCompletableFuture is completed and dependent actions are invoked.
      Returns:
      a newCompletableFuture<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 ofdestroyforcibly and immediately terminates the process.
      Returns:
      true if the implementation ofdestroy() normally terminates the process; otherwise,destroy() forcibly terminates the process

    • destroy

      boolean destroy()
      Requests the process to be killed.Whether the process represented by thisProcessHandle object isnormally terminated or not isimplementation dependent.Forcible process destruction is defined as the immediate termination of theprocess, 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 processfrom being killed.

      TheCompletableFuture fromonExit() iscompletedwhen the process has terminated.

      Note: The process may not terminate immediately.For example,isAlive() may return true for a brief periodafterdestroy() 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 isforcibly terminated.Forcible process destruction is defined as the immediate termination of theprocess, 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 processfrom being killed.

      TheCompletableFuture fromonExit() iscompletedwhen the process has terminated.

      Note: The process may not terminate immediately.For example,isAlive() may return true for a brief periodafterdestroyForcibly() 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 andmay be a function of additional information to uniquely identify the process.If two ProcessHandles are equal according to theequalsmethod, then calling the hashCode method on each of the two objectsmust produce the same integer result.
      Overrides:
      hashCode in class Object
      Returns:
      a hash code value for this object
      See Also:

    • equals

      boolean equals(Object other)
      Returnstrue ifother object is non-null, is of thesame implementation, and represents the same system process;otherwise it returnsfalse.
      Overrides:
      equals in class Object
      Implementation Note:
      It is implementation specific whether ProcessHandles with the same PIDrepresent the same system process. ProcessHandle implementationsshould contain additional information to uniquely identify the process.For example, the start time of the process could be usedto determine if the PID has been re-used.The implementation ofequals should returntrue for twoProcessHandles with the same PID unless there is information todistinguish 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:

    • compareTo

      int compareTo(ProcessHandle other)
      Compares this ProcessHandle with the specified ProcessHandle for order.The order is not specified, but is consistent withObject.equals(Object),which returnstrue if and only if two instances of ProcessHandleare 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 implementationsofProcessHandles,ClassCastException is thrown.
      Specified by:
      compareTo in interface Comparable<ProcessHandle>
      Parameters:
      other - the ProcessHandle to be compared
      Returns:
      a negative integer, zero, or a positive integer as this objectis less than, equal to, or greater than the specified object.
      Throws:
      NullPointerException - if the specified object is null
      ClassCastException - if the specified object is not of same class as this object