モジュール java.base
パッケージ java.lang

インタフェースProcessHandle

すべてのスーパー・インタフェース:
Comparable<ProcessHandle>
public interface ProcessHandle
extends Comparable<ProcessHandle>
ProcessHandleは、ネイティブ・プロセスを識別して制御します。 それぞれのプロセスは、活力を監視し、子を列挙したり、プロセスに関する情報を入手したり、破壊することができます。 比較すると、現在のプロセスによってProcessインスタンスが起動され、さらにプロセスの入力、出力、およびエラー・ストリームへのアクセスが提供されます。

ネイティブ・プロセスIDは、オペレーティング・システムがプロセスに割り当てる識別番号です。 プロセスID値の範囲は、オペレーティング・システムによって異なります。 たとえば、組み込みシステムでは16ビット値を使用する場合があります。 プロセスに関するステータス情報はネイティブ・システムから取得され、非同期に変更されることがあります。プロセスは自発的に作成または終了することがあります。 プロセスが終了してプロセスIDが新しいプロセスに再利用されるまでの時間は予測できません。 競合ステータスは、プロセスのステータスをチェックし、プロセスのステータスに応じて変化する可能性があります。 ProcessHandlesを使用する場合は、基本となるプロセスの活性やアイデンティティに関する仮定を避けてください。

各ProcessHandleは、ネイティブ・システム内のプロセスを識別して制御することができます。 ProcessHandlesは、ファクトリ・メソッドcurrent()、of(long)、children()、descendants()、parent()、allProcesses()から返されます。

ProcessBuilderによって作成されたProcessインスタンスは、プロセスに関する情報を提供するProcessHandleに対して問合せできます。 ProcessHandle参照は自由に配布されるべきではありません。

onExit()から入手可能なCompletableFutureを使用すると、プロセスの終了を待つことができ、場合によっては依存するアクションを起動することができます。

ファクトリ・メソッドは、RuntimePermission("manageProcess")をチェックするSecurityManagerを使用してProcessHandlesへのアクセスを制限します。 プロセスを制御する能力もネイティブ・システムによって制限されています。ProcessHandleは、ネイティブ・アプリケーションが許可するよりもネイティブ・プロセスへのアクセスや制御を提供しません。

実装要件:
ProcessHandlesがサポートされない場合、ファクトリ・メソッドは一貫してUnsupportedOperationExceptionをスローする必要があります。 このクラスのメソッドは、オペレーティング・システムがプロセスの問合せまたは終了を許可しない場合、UnsupportedOperationExceptionをスローします。

ProcessHandle静的ファクトリ・メソッドは、value-based、不変でスレッド・セーフなインスタンスを返します。 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)
    otherオブジェクトが非nullで、同じ実装であり、同じシステム・プロセスを表す場合は、trueを返します; それ以外の場合は、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()
    プロセスのネイティブ・プロセスIDを返します。
    boolean supportsNormalTermination()
    destroy()の実装が正常にプロセスを終了する場合は、trueを返します。

  • メソッドの詳細

    • pid

      long pid()
      プロセスのネイティブ・プロセスIDを返します。 ネイティブ・プロセスIDは、オペレーティング・システムがプロセスに割り当てる識別番号です。 オペレーティング・システムは、プロセスが終了した後にプロセスIDを再利用することがあります。 equalsまたはcompareToを使用してProcessHandlesを比較してください。
      戻り値:
      プロセスのネイティブ・プロセスID
      例外:
      UnsupportedOperationException - 実装がこの操作をサポートしていない場合

    • of

      static Optional<ProcessHandle> of​(long pid)
      既存のネイティブ・プロセスのOptional<ProcessHandle>を返します。
      パラメータ:
      pid - ネイティブ・プロセスID
      戻り値:
      プロセスのPIDのOptional<ProcessHandle>。プロセスが存在しない場合、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のプロセスには子プロセスがありません。

      プロセスは非同期で作成され、終了することに注意してください。 プロセスが生存している保証はありません。

      戻り値:
      プロセスの直接の子プロセスであるプロセスの一連のProcessHandle
      例外:
      SecurityException - セキュリティ・マネージャがインストールされていて、RuntimePermission("manageProcess")を拒否した場合

    • descendants

      Stream<ProcessHandle> descendants()
      プロセスの子孫のスナップショットを返します。 プロセスの子孫は、再帰的にプロセスの子と子の子孫です。 通常、生存していないプロセスには子がありません。

      プロセスは非同期で作成され、終了することに注意してください。 プロセスが生存している保証はありません。

      戻り値:
      プロセスの子孫であるプロセスのProcessHandlesの連続ストリーム
      例外:
      SecurityException - セキュリティ・マネージャがインストールされていて、RuntimePermission("manageProcess")を拒否した場合

    • allProcesses

      static Stream<ProcessHandle> allProcesses()
      現在のプロセスから見えるすべてのプロセスのスナップショットを返します。

      プロセスは非同期で作成され、終了することに注意してください。 ストリーム内のプロセスが生存している、またはスナップショットの開始以降に他のプロセスが作成されていないという保証はありません。

      戻り値:
      すべてのプロセスのProcessHandleのストリーム
      例外:
      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かどうかを確認するために使用できます。 CompleteableFutureの取消しはプロセスに影響を与えません。

      APIのノート:
      プロセスは、ComputableFutureが完了し、従属アクションが呼び出される前にisAlive()で終了したことが観察されることがあります。
      戻り値:
      ProcessHandle用の新しいCompletableFuture<ProcessHandle>
      例外:
      IllegalStateException - プロセスが現在のプロセスである場合

    • supportsNormalTermination

      boolean supportsNormalTermination()
      destroy()の実装が正常にプロセスを終了する場合は、trueを返します。 destroyの実装が強制的かつ即座にプロセスを終了する場合は、falseを返します。
      戻り値:
      true destroy()の実装が正常にプロセスを終了する場合。そうでなければ、destroy()はプロセスを強制終了

    • destroy

      boolean destroy()
      プロセスを強制終了するようにリクエストします。 このProcessHandleオブジェクトによって表されるプロセスがnormally terminatedであるかどうかは、実装に依存します。 強制的なプロセス破壊は、プロセスの即時終了として定義されますが、正常終了は、プロセスが正常に終了することを可能にします。 プロセスが生存していない場合、何も実行されません。 オペレーティング・システムのアクセス制御によって、プロセスが強制終了されないことがあります。

      プロセスが終了すると、onExit()からのCompletableFutureはcompletedになります。

      ノート: プロセスはすぐに終了しないことがあります。 たとえば、isAlive()は、destroy()が呼び出された後、短期間trueを返します。

      戻り値:
      終了が正常にリクエストされた場合はtrue、そうでない場合はfalse
      例外:
      IllegalStateException - プロセスが現在のプロセスである場合

    • destroyForcibly

      boolean destroyForcibly()
      プロセスを強制的に強制終了するようにリクエストします。 このProcessHandleオブジェクトによって表されるプロセスは、強制終了されます。 強制的なプロセス破壊は、プロセスの即時終了として定義されますが、正常終了は、プロセスが正常に終了することを可能にします。 プロセスが生存していない場合、何も実行されません。 オペレーティング・システムのアクセス制御によって、プロセスが強制終了されないことがあります。

      プロセスが終了すると、onExit()からのCompletableFutureはcompletedになります。

      ノート: プロセスはすぐに終了しないことがあります。 たとえば、isAlive()は、destroyForcibly()が呼び出された後、短期間trueを返します。

      戻り値:
      終了が正常にリクエストされた場合はtrue、そうでない場合はfalse
      例外:
      IllegalStateException - プロセスが現在のプロセスである場合

    • isAlive

      boolean isAlive()
      このProcessHandleが表すプロセスが生存しているかどうかをテストします。 プロセスの終了は実装とオペレーティング・システム固有です。 このプロセスは、PIDが有効である限り、生きているとみなされます。
      戻り値:
      このProcessHandleオブジェクトによって表されるプロセスがまだ終了していない場合はtrue

    • hashCode

      int hashCode()
      このProcessHandleのハッシュ・コード値を返します。 hashcode値は、Object.hashCode()の一般規約に従います。 値はpid()値の関数であり、プロセスを一意的に識別するための追加情報の関数である場合があります。 equalsメソッドに従って2つのProcessHandleが等しい場合、2つのオブジェクトのそれぞれでhashCodeメソッドを呼び出すと、同じ整数結果が生成されなければなりません。
      オーバーライド:
      hashCode 、クラス:  Object
      戻り値:
      このオブジェクトのハッシュ・コード値
      関連項目:
      Object.equals(java.lang.Object), System.identityHashCode(java.lang.Object)

    • equals

      boolean equals​(Object other)
      otherオブジェクトが非nullで、同じ実装であり、同じシステム・プロセスを表す場合は、trueを返します; それ以外の場合は、falseを返します。
      オーバーライド:
      equals 、クラス:  Object
      実装上のノート:
      同じPIDを持つProcessHandleが同じシステム・プロセスを表すかどうかは実装固有です。 ProcessHandleの実装には、プロセスを一意に識別するための追加情報が含まれている必要があります。 例えば、プロセスの開始時間を使用して、PIDが再使用されたかどうかを判定することができます。 equalsの実装は、それらを区別する情報がない限り、同じPIDを持つ2つのProcessHandleのtrueを返すべきです。
      パラメータ:
      other - 別のオブジェクト
      戻り値:
      true otherオブジェクトがnullでない場合、同じ実装クラスであり、同じシステム・プロセスを表します。それ以外の場合はfalseを返します。
      関連項目:
      Object.hashCode()、HashMap

    • compareTo

      int compareTo​(ProcessHandle other)
      このProcessHandleと指定したオーダーのProcessHandleを比較します。 順序は指定されていませんが、Object.equals(java.lang.Object)と一貫しています。これは、ProcessHandleの2つのインスタンスが同じ実装で、同じシステム・プロセスを表す場合にのみtrueを返します。 比較は、同じ実装のオブジェクト間でのみサポートされます。 ProcessHandleの2つの異なる実装を相互に比較しようとすると、ClassCastExceptionがスローされます。
      定義:
      インタフェースComparable<ProcessHandle>内のcompareTo
      パラメータ:
      other - 比較されるProcessHandle
      戻り値:
      このオブジェクトが指定されたオブジェクトより小さい場合は負の整数、等しい場合はゼロ、大きい場合は正の整数
      例外:
      NullPointerException - 指定されたオブジェクトがnullの場合
      ClassCastException - 指定されたオブジェクトがこのオブジェクトと同じクラスでない場合