Интерфейс ProcessHandle

Все суперинтерфейсы:: Comparable<ProcessHandle>

public interface ProcessHandle
extends Comparable<ProcessHandle>

ProcessHandle идентифицирует и предоставляет управление нативными процессами. Каждый отдельный процесс можно отслеживать на предмет активности, перечислять его дочерние процессы, получать информацию о процессе или уничтожить его. В сравнении, экземпляры Process были запущены текущим процессом и дополнительно предоставляют доступ к потокам ввода, вывода и ошибок процесса.

Идентификатор нативного процесса — это номер, присваиваемый процессу операционной системой. Диапазон значений идентификатора процесса зависит от операционной системы. Например, встроенная система может использовать 16-битовое значение. Информация о состоянии процесса извлекается из нативной системы и может изменяться асинхронно; процессы могут создаваться или завершаться спонтанно. Время между завершением процесса и повторным использованием идентификатора процесса для нового процесса непредсказуемо. Может существовать проблема гонки при проверке состояния процесса и выполнении действий. При использовании ProcessHandles не делайте предположений об активности или идентичности основного процесса.

Каждый ProcessHandle идентифицирует и позволяет управлять процессом в нативной системе. ProcessHandles возвращаются из методов-фабрик current(), of(long), children(), descendants(), parent() и allProcesses().

Экземпляры Process, созданные с помощью ProcessBuilder, можно запросить для получения ProcessHandle, который предоставляет информацию о процессе. Ссылки на ProcessHandle не должны свободно распространяться.

CompletableFuture, доступный из onExit(), можно использовать для ожидания завершения процесса и, возможно, запуска зависимых действий.

Методы-фабрики ограничивают доступ к ProcessHandles, используя SecurityManager для проверки RuntimePermission("manageProcess"). Возможность управления процессами также ограничена нативной системой; ProcessHandle не предоставляет больше доступа или контроля над нативным процессом, чем разрешено нативным приложением.

Требования к реализации:: В случае, если ProcessHandles не поддерживаются, методы-фабрики должны последовательно выбрасывать UnsupportedOperationException. Методы этого класса выбрасывают UnsupportedOperationException, если операционная система не разрешает запрос или завершение процесса.
Статические методы-фабрики ProcessHandle возвращают экземпляры, которые являются базовыми значениями, неизменяемыми и потокобезопасными. Использование операций, чувствительных к идентификатору (включая равенство ссылок (==), хэш-код по идентификатору или синхронизация) для этих экземпляров ProcessHandle может привести к непредсказуемым результатам и следует избегать. Используйте методы equals или compareTo для сравнения ProcessHandles.
С:: 9
См. также:: Process

Вложенные классы

Модификатор и тип	Интерфейс	Описание
`static interface`	`ProcessHandle.Info`	Снимок информации о процессе.

Методы

Модификатор и тип	Метод	Описание
`static Stream<ProcessHandle>`	`allProcesses()`	Возвращает снимок всех процессов, видимых текущему процессу.
`Stream<ProcessHandle>`	`children()`	Возвращает снимок прямых дочерних процессов.
`int`	`compareTo(ProcessHandle other)`	Сравнивает этот ProcessHandle с указанным ProcessHandle для определения порядка.
`static ProcessHandle`	`current()`	Возвращает ProcessHandle для текущего процесса.
`Stream<ProcessHandle>`	`descendants()`	Возвращает снимок потомков процесса.
`boolean`	`destroy()`	Запрашивает завершение процесса.
`boolean`	`destroyForcibly()`	Запрашивает принудительное завершение процесса.
`boolean`	`equals(Object other)`	Возвращает `true`, если объект `other` не равен null, имеет ту же реализацию и представляет тот же системный процесс; в противном случае возвращает `false`.
`int`	`hashCode()`	Возвращает значение хэш-кода для этого ProcessHandle.
`ProcessHandle.Info`	`info()`	Возвращает снимок информации о процессе.
`boolean`	`isAlive()`	Проверяет, жив ли процесс, представленный этим `ProcessHandle`.
`static Optional<ProcessHandle>`	`of(long pid)`	Возвращает `Optional<ProcessHandle>` для существующего нативного процесса.
`CompletableFuture<ProcessHandle>`	`onExit()`	Возвращает `CompletableFuture<ProcessHandle>` для завершения процесса.
`Optional<ProcessHandle>`	`parent()`	Возвращает `Optional<ProcessHandle>` для родительского процесса.
`long`	`pid()`	Возвращает нативный идентификатор процесса.
`boolean`	`supportsNormalTermination()`	Возвращает `true`, если реализация `destroy()` обычно завершает процесс.

Методы

pid

long pid()

Возвращает идентификатор процесса (PID) процесса. Идентификатор процесса — это число, присваиваемое операционной системой процессу. Операционная система может повторно использовать идентификатор процесса после завершения работы процесса. Для сравнения ProcessHandle используйте equals или compareTo.

Возвращает:: идентификатор процесса (PID) процесса
Исключение:: UnsupportedOperationException - если реализация не поддерживает эту операцию

of

static Optional<ProcessHandle> of(long pid)

Возвращает Optional<ProcessHandle> для существующего процесса.

Параметры:: pid - идентификатор процесса (PID)
Возвращает:: объект Optional<ProcessHandle> для PID процесса; объект Optional пуст, если процесс не существует
Исключение:: SecurityException - если установлен менеджер безопасности, и он отклоняет RuntimePermission("manageProcess"); UnsupportedOperationException - если реализация не поддерживает эту операцию

current

static ProcessHandle current()

Возвращает ProcessHandle для текущего процесса. ProcessHandle нельзя использовать для уничтожения текущего процесса, используйте System.exit вместо этого.

Возвращает:: ProcessHandle для текущего процесса
Исключение:: SecurityException - если установлен менеджер безопасности, и он отклоняет RuntimePermission("manageProcess"); UnsupportedOperationException - если реализация не поддерживает эту операцию

parent

Optional<ProcessHandle> parent()

Возвращает Optional<ProcessHandle> для родительского процесса. Обратите внимание, что процессы в состоянии «зомби» обычно не имеют родителя.

Возвращает:: объект Optional<ProcessHandle> родительского процесса; объект Optional пуст, если у дочернего процесса нет родителя или родитель недоступен, возможно, из-за ограничений операционной системы
Исключение:: SecurityException - если установлен менеджер безопасности, и он отклоняет RuntimePermission("manageProcess")

children

Stream<ProcessHandle> children()

Возвращает снимок текущих непосредственных дочерних процессов. parent() непосредственного дочернего процесса — это процесс. Обычно у процесса, который not alive, нет дочерних процессов.

Обратите внимание, что процессы создаются и завершаются асинхронно. Нет гарантии, что процесс alive.

Возвращает:: последовательный поток ProcessHandle для процессов, являющихся непосредственными дочерними процессами
Исключение:: SecurityException - если установлен менеджер безопасности, и он отклоняет RuntimePermission("manageProcess")

descendants

Stream<ProcessHandle> descendants()

Возвращает снимок потомков процесса. Потомки процесса — это дочерние процессы, плюс потомки этих дочерних процессов рекурсивно. Обычно у процесса, который not alive, нет дочерних процессов.

Обратите внимание, что процессы создаются и завершаются асинхронно. Нет гарантии, что процесс alive.

Возвращает:: последовательный поток ProcessHandles для процессов, являющихся потомками процесса
Исключение:: SecurityException - если установлен менеджер безопасности, и он отклоняет RuntimePermission("manageProcess")

allProcesses

static Stream<ProcessHandle> allProcesses()

Возвращает снимок всех процессов, видимых текущему процессу.

Обратите внимание, что процессы создаются и завершаются асинхронно. Нет гарантии, что процесс в потоке жив, или что другие процессы не были созданы с момента создания снимка.

Возвращает:: поток ProcessHandles для всех процессов
Исключение:: SecurityException - если установлен менеджер безопасности, и он отклоняет RuntimePermission("manageProcess"); UnsupportedOperationException - если реализация не поддерживает эту операцию

info

ProcessHandle.Info info()

Возвращает снимок информации о процессе.

Объект ProcessHandle.Info имеет методы доступа, которые возвращают информацию о процессе, если она доступна.

Возвращает:: снимок информации о процессе, всегда не null

onExit

CompletableFuture<ProcessHandle> onExit()

Возвращает объект CompletableFuture<ProcessHandle> для завершения процесса. CompletableFuture предоставляет возможность вызывать зависимые функции или действия, которые могут выполняться синхронно или асинхронно при завершении процесса. После завершения процесса CompletableFuture completed, независимо от кода завершения процесса. Метод onExit может вызываться несколько раз для запуска независимых действий при завершении процесса.

Вызов onExit().get() ожидает завершения процесса и возвращает ProcessHandle. Future можно использовать для проверки, done ли процесс, или для wait завершения. Cancelling CompletableFuture не влияет на процесс.

Примечание API:: Процесс может быть отмечен как завершенный с помощью isAlive() до завершения ComputableFuture и вызова зависимых действий.
Возвращает:: новый CompletableFuture<ProcessHandle> для ProcessHandle
Исключение:: IllegalStateException - если процесс — текущий процесс

supportsNormalTermination

boolean supportsNormalTermination()

Возвращает true если реализация destroy() нормально завершает процесс. Возвращает false если реализация destroy принудительно и немедленно завершает процесс.

Возвращает:: true если реализация destroy() нормально завершает процесс; в противном случае destroy() принудительно завершает процесс

destroy

boolean destroy()

Запрашивает завершение процесса. Является ли процесс, представленный этим объектом ProcessHandle, normally terminated или нет, зависит от реализации. Принудительное завершение процесса определено как немедленное завершение процесса, в то время как нормальное завершение позволяет процессу завершиться корректно. Если процесс не активен, никаких действий не предпринимается. Контроли доступа операционной системы могут предотвратить завершение процесса.

CompletableFuture из onExit() completed при завершении процесса.

Примечание: процесс может не завершиться немедленно. Например, isAlive() может возвращать true в течение короткого периода после вызова destroy().

Возвращает:: true если запрос на завершение был успешно выполнен, в противном случае false
Исключение:: IllegalStateException - если процесс — текущий процесс

destroyForcibly

boolean destroyForcibly()

Запрашивает принудительное завершение процесса. Процесс, представленный этим объектом ProcessHandle, завершается принудительно. Принудительное завершение процесса определено как немедленное завершение процесса, в то время как нормальное завершение позволяет процессу завершиться корректно. Если процесс не активен, никаких действий не предпринимается. Контроли доступа операционной системы могут предотвратить завершение процесса.

CompletableFuture из onExit() completed при завершении процесса.

Примечание: процесс может не завершиться немедленно. Например, isAlive() может возвращать true в течение короткого периода после вызова destroyForcibly().

Возвращает:: true если запрос на завершение был успешно выполнен, в противном случае false
Исключение:: IllegalStateException - если процесс — текущий процесс

isAlive

boolean isAlive()

Проверяет, жив ли процесс, представленный этим ProcessHandle. Завершение процесса зависит от реализации и операционной системы. Процесс считается активным, пока PID действителен.

Возвращает:: true если процесс, представленный этим объектом ProcessHandle, еще не завершен

hashCode

int hashCode()

Возвращает хэш-код для данного ProcessHandle. Хэш-код следует общему соглашению для Object.hashCode(). Значение является функцией значения pid() и может быть функцией дополнительной информации для уникальной идентификации процесса. Если два ProcessHandle равны в соответствии с методом equals, то вызов метода hashCode для каждого из двух объектов должен давать одинаковый целочисленный результат.

Переопределяет:: hashCode в классе Object
Возвращает:: хэш-код для этого объекта
См. также:: Object.equals(java.lang.Object), System.identityHashCode(java.lang.Object)

equals

boolean equals(Object other)

Возвращает true если объект other не null, имеет ту же реализацию и представляет тот же системный процесс; в противном случае возвращает false.

Переопределяет:: equals в классе Object
Примечание реализации:: Реализация определяет, представляют ли ProcessHandles с одинаковым PID один и тот же системный процесс. Реализации ProcessHandle должны содержать дополнительную информацию для уникальной идентификации процесса. Например, время запуска процесса можно использовать для определения, был ли PID повторно использован. Реализация equals должна возвращать true для двух ProcessHandles с одинаковым PID, если нет информации для их различения.
Параметры:: other - другой объект
Возвращает:: true если объект other не null, относится к тому же классу реализации и представляет тот же системный процесс; в противном случае возвращает false
См. также:: Object.hashCode(), HashMap

compareTo

int compareTo(ProcessHandle other)

Сравнивает этот ProcessHandle с указанным ProcessHandle для определения порядка. Порядок не определён, но согласуется с Object.equals(java.lang.Object), который возвращает true тогда и только тогда, когда два экземпляра ProcessHandle имеют одинаковую реализацию и представляют один и тот же системный процесс. Сравнение поддерживается только для объектов одной реализации. Если попытка взаимного сравнения двух разных реализаций ProcessHandle приводит к исключению ClassCastException.

Задано:: compareTo в интерфейсе Comparable<ProcessHandle>
Параметры:: other - сравниваемый ProcessHandle
Возвращает:: отрицательное целое число, ноль или положительное целое число, если этот объект меньше, равен или больше указанного объекта соответственно.
Исключения:: NullPointerException - если указанный объект null; ClassCastException - если указанный объект не принадлежит тому же классу, что и этот объект

© 1993, 2020, 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/11/docs/api/java.base/java/lang/ProcessHandle.html