ProcessHandle interface in Java

java.lang.ProcessHandle

ProcessHandle identifies and provides control of native processes. Each individual process can be monitored for liveness, list its children, get information about the process or destroy it. By comparison, Process instances were started by the current process and provided 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.

Superinterfaces:

Comparable<ProcessHandle>

Declaration

public interface ProcessHandle 
          extends Comparable<ProcessHandle> {

    long pid();

    public static Optional<ProcessHandle> of(long pid) {
        return ProcessHandleImpl.get(pid);
    }

    public static ProcessHandle current() {
        return ProcessHandleImpl.current();
    }

    Optional<ProcessHandle> parent();

    Stream<ProcessHandle> children();

    Stream<ProcessHandle> descendants();

    static Stream<ProcessHandle> allProcesses() {
        return ProcessHandleImpl.children(0);
    }

    Info info();

    public interface Info {

        public Optional<String> command();

        public Optional<String> commandLine();

        public Optional<String[]> arguments();

        /**
         * Returns the start time of the process.
         *
         * @return an {@code Optional<Instant>} of the start time of the process
         */
        public Optional<Instant> startInstant();

        public Optional<Duration> totalCpuDuration();

        public Optional<String> user();
    }

    CompletableFuture<ProcessHandle> onExit();

    boolean supportsNormalTermination();

    boolean destroy();

    boolean destroyForcibly();

    boolean isAlive();

    @Override
    int hashCode();

    @Override
    boolean equals(Object other);

    @Override
    int compareTo(ProcessHandle other);

}

Methods

1. pid()

long java.lang.ProcessHandle.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.

Returns: the native process ID of the process.

Throws:

1. UnsupportedOperationException - if the implementation does not support this operation.

2. of(long pid)

Optional<ProcessHandle> java.lang.ProcessHandle.of(long pid)

Returns an Optional<ProcessHandle> for an existing native process.

Parameters: pid a native process ID.

Returns: an Optional<ProcessHandle> of the PID for the process; the Optional is empty if the process does not exist.

Throws:

1. SecurityException - if a security manager has been installed and it denies RuntimePermission("manageProcess").

2. UnsupportedOperationException - if the implementation does not support this operation.

3. current()

ProcessHandle java.lang.ProcessHandle.current()

Returns a ProcessHandle for the current process. The ProcessHandle cannot be used to destroy the current process, use System.exit instead.

Returns: a ProcessHandle for the current process.

Throws:

1. SecurityException - if a security manager has been installed and it denies RuntimePermission("manageProcess").

2. UnsupportedOperationException - if the implementation does not support this operation.

4. parent()

Optional<ProcessHandle> java.lang.ProcessHandle.parent()

Returns an Optional<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; 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 limitations.

Throws:

1. SecurityException - if a security manager has been installed and it denies RuntimePermission("manageProcess").

5. children()

Stream<ProcessHandle> java.lang.ProcessHandle.children()

Returns a snapshot of the current direct children of the process. The parent of a direct child process is a process.

Typically, a process that is not alive has no children.

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

Throws:

1. SecurityException - if a security manager has been installed and it denies RuntimePermission("manageProcess").

6. descendants()

Stream<ProcessHandle> java.lang.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 is not alive has no children.

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

Throws:

1. SecurityException - if a security manager has been installed and it denies RuntimePermission("manageProcess").

7. allProcesses()

Stream<ProcessHandle> java.lang.ProcessHandle.allProcesses()

Returns a snapshot of all processes visible to the current process.

Returns: a Stream of ProcessHandles for all processes.

Throws:

1. SecurityException - if a security manager has been installed and it denies RuntimePermission("manageProcess").

2. UnsupportedOperationException - if the implementation does not support this operation.

8. info()

Info java.lang.ProcessHandle.info()

Returns a snapshot of information about the process.

A ProcessHandle.Info instance has access or methods that return information about the process if it is available.

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

9. command()

Optional<String> java.lang.ProcessHandle.Info.command()

Returns the executable pathname of the process.

Returns: an Optional<String> of the executable pathname of the process.

10. commandLine()

Optional<String> java.lang.ProcessHandle.Info.commandLine()

Returns the command line of the process.

Returns: an Optional<String> of the command line of the process.

11. arguments()

Optional<String[]> java.lang.ProcessHandle.Info.arguments()

Returns an array of Strings of the arguments of the process.

Returns: an Optional<String[]> of the arguments of the process.

12. startInstant()

Optional<Instant> java.lang.ProcessHandle.Info.startInstant()

Returns the start time of the process.

Returns: an Optional<Instant> of the start time of the process.

13. totalCpuDuration()

Optional<Duration> java.lang.ProcessHandle.Info.totalCpuDuration()

Returns the total CPU time accumulated in the process.

Returns: an Optional<Duration> for the accumulated total CPU time.

14. user()

Optional<String> java.lang.ProcessHandle.Info.user()

Return the user of the process.

Returns: an Optional<String> for the user of the process.

15. onExit()

CompletableFuture<ProcessHandle> java.lang.ProcessHandle.onExit()

Returns a CompletableFuture<ProcessHandle> for the termination of the process.

Returns: a new CompletableFuture<ProcessHandle> for the ProcessHandle.

Throws:

1. IllegalStateException - if the process is the current process.

16. supportsNormalTermination()

boolean java.lang.ProcessHandle.supportsNormalTermination()

Returns true if the implementation of destroy normally terminates the process.

Returns false if the implementation of destroy forcibly and immediately terminates the process.

Returns: true if the implementation of destroy normally terminates the process; otherwise, destroy forcibly terminates the process.

17. destroy()

boolean java.lang.ProcessHandle.destroy()

Requests the process to be killed. Whether the process represented by this ProcessHandle object is normally terminated or not is the implementation dependent.

Returns: true if the termination was successfully requested, otherwise false.

Throws:

1. IllegalStateException - if the process is the current process.

18. destroyForcibly()

boolean java.lang.ProcessHandle.destroyForcibly()

Requests the process to be killed forcibly. The process represented by this 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.

Returns: true if the termination was successfully requested, otherwise false.

Throws:

1. IllegalStateException - if the process is the current process.

19. isAlive()

boolean java.lang.ProcessHandle.isAlive()

Tests whether the process represented by this ProcessHandle 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 this ProcessHandle object has not yet been terminated.

20. hashCode()

int java.lang.ProcessHandle.hashCode()

Returns a hash code value for this ProcessHandle.

Returns: a hash code value for this object

21. equals(Object other)

boolean java.lang.ProcessHandle.equals(Object other)

Returns true if another object is non-null, is of the same implementation, and represents the same system process; otherwise, it returns false.

Parameters: other another object.

Returns: true if the other object is non-null, is of the same implementation class, and represents the same system process; otherwise returns false.

22. compareTo(ProcessHandle other)

int java.lang.ProcessHandle.compareTo(ProcessHandle other)

Compares this ProcessHandle with the specified ProcessHandle for order. The order is not specified, but is consistent with Object.equals, which returns true if and only if two instances of ProcessHandleare of the same implementation and represent the same system process.

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:

1. NullPointerException - if the specified object is null.

2. ClassCastException - if the specified object is not of the same class as this object.