すべてのスーパー・インタフェース:: AutoCloseable

既知のすべての実装クラス:: RecordingStream

public interface EventStream
extends AutoCloseable

イベントのストリームを表します。

ストリームとは一連のイベントであり、ストリームとの対話方法はアクションの登録です。 EventStreamインタフェースが実装されておらず、将来のバージョンのJDKでは完全に使用できない可能性があります。

イベントの到着時に通知を受信するには、onEvent(Consumer)メソッドを使用してアクションを登録します。特定の名前を持つイベントのストリームをフィルタするには、onEvent(String, Consumer)メソッドを使用します。

デフォルトでは、同じRecordedEventオブジェクトを使用して2つ以上の個別のイベントを表すことができます。そのオブジェクトは、同じアクションおよび他のアクションに複数回配信できます。アクションの完了後にイベント・オブジェクトを使用するには、setReuse(boolean)メソッドをfalseに設定して、イベントごとに新しいオブジェクトが割り当てられるようにします。

イベントは、バッチで配信されます。バッチが完了したときに通知を受け取るには、onFlush(Runnable)メソッドを使用してアクションを登録します。これは、Java Virtual Machine (JVM)が次のバッチを準備している間に、外部システムに対してデータを集約またはプッシュする機会です。

バッチ内のイベントは、終了時間によって時系列順にソートされます。確定イベントは、フラッシュの時点でJVMに使用可能なイベント、つまり単一バッチで1単位として配信されるイベントのセットに対してのみ維持されます。そのため、バッチ内に配信されたイベントは、以前のバッチで配信されたイベントと比較して順不同になることがありますが、同じバッチ内のイベントとは順不同になることはありません。順序付けが懸念されない場合は、setOrdered(boolean)メソッドを使用してソートを無効にできます。

登録されたアクションにイベントをディスパッチするには、ストリームを開始する必要があります。現在のスレッドで処理を開始するには、start()メソッドを呼び出します。別のスレッドでアクションを非同期に処理するには、startAsync()メソッドを呼び出します。ストリームの完了を待機するには、awaitTermination awaitTermination()またはawaitTermination(Duration)メソッドを使用します。

ストリームが終了すると、自動的にクローズされます。イベントの処理を手動で停止するには、close()メソッドを呼び出してストリームを閉じます。また、ストリームは、たとえばモニターしているJVMが終了した場合など、例外的な状況で自動的にクローズされることもあります。これらのいずれかのタイミングで通知を受信するには、onClose(Runnable)メソッドを使用してアクションを登録します。

アクションで予期しない例外が発生した場合は、エラー・ハンドラで例外を捕捉できます。エラー・ハンドラは、#onError(Runnable)メソッドを使用して登録できます。エラー・ハンドラが登録されていない場合、デフォルトの動作では、例外とそのバック・トレースが標準エラー・ストリームに出力されます。

次の例では、Flight Recorderを実行しているJVMでイベントをリスニングするためにEventStreamを使用する方法を示します

 
 try (var es = EventStream.openRepository()) {
   es.onEvent("jdk.CPULoad", event -> {
     System.out.println("CPU Load " + event.getEndTime());
     System.out.println(" Machine total: " + 100 * event.getFloat("machineTotal") + "%");
     System.out.println(" JVM User: " + 100 * event.getFloat("jvmUser") + "%");
     System.out.println(" JVM System: " + 100 * event.getFloat("jvmSystem") + "%");
     System.out.println();
   });
   es.onEvent("jdk.GarbageCollection", event -> {
     System.out.println("Garbage collection: " + event.getLong("gcId"));
     System.out.println(" Cause: " + event.getString("cause"));
     System.out.println(" Total pause: " + event.getDuration("sumOfPauses"));
     System.out.println(" Longest pause: " + event.getDuration("longestPause"));
     System.out.println();
   });
   es.start();
 }

ストリームとのレコーディングを開始するには、RecordingStreamを参照してください。

導入されたバージョン:: 14

メソッドのサマリー

修飾子と型	メソッド	説明
`void`	`awaitTermination()`	すべてのアクションが完了するか、ストリームがクローズされるか、現在のスレッドが中断されるまで、いずれか早いほうで発生します。
`void`	`awaitTermination(Duration timeout)`	すべてのアクションが完了するか、ストリームがクローズされるか、タイムアウトが発生するか、現在のスレッドが中断されるまで、いずれか先に発生するまでブロックします。
`void`	`close()`	このストリームに関連付けられているすべてのリソースを解放します。
`void`	`onClose(Runnable action)`	ストリームが閉じられたときに実行するアクションを登録します。
`void`	`onError(Consumer<Throwable> action)`	例外が発生した場合に実行するアクションを登録します。
`void`	`onEvent(String eventName, Consumer<RecordedEvent> action)`	名前と一致するすべてのイベントに対して実行するアクションを登録します。
`void`	`onEvent(Consumer<RecordedEvent> action)`	ストリーム内のすべてのイベントで実行するアクションを登録します。
`void`	`onFlush(Runnable action)`	ストリームのフラッシュ後に実行するアクションを登録します。
`static EventStream`	`openFile(Path file)`	ファイルからイベント・ストリームを作成します。
`static EventStream`	`openRepository()`	現行のJava Virtual Machine (JVM)のリポジトリからストリームを作成します。
`static EventStream`	`openRepository(Path directory)`	ディスク・リポジトリからイベント・ストリームを作成します。
`boolean`	`remove(Object action)`	アクションを登録解除します。
`void`	`setEndTime(Instant endTime)`	ストリームの終了時間を指定します。
`void`	`setOrdered(boolean ordered)`	イベントがストリームにコミットされた時間でソートされて、時系列順にイベントが到着することを指定します。
`void`	`setReuse(boolean reuse)`	`onEvent(Consumer)`処理のイベント・オブジェクトを再利用できることを指定します。
`void`	`setStartTime(Instant startTime)`	ストリームの開始時間を指定します。
`void`	`start()`	アクションの開始処理。
`void`	`startAsync()`	アクションの非同期処理を開始します。

メソッドの詳細
- openRepository
  
  static EventStream openRepository() throws IOException
  
  現行のJava Virtual Machine (JVM)のリポジトリからストリームを作成します。
  デフォルトでは、ストリームはFlight Recorderによりフラッシュされる次のイベントから開始されます。
  
  戻り値:
  
  イベント・ストリーム(nullではない)
  
  例外:
  
  IOException - ストリームを開けない場合、またはリポジトリにアクセスしようとしたときにI/Oエラーが発生した場合
  
  SecurityException - セキュリティ・マネージャが存在し、呼び出し元にFlightRecorderPermission("accessFlightRecorder")がない場合
- openRepository
  
  static EventStream openRepository(Path directory) throws IOException
  
  ディスク・リポジトリからイベント・ストリームを作成します。
  デフォルトでは、ストリームはFlight Recorderによりフラッシュされる次のイベントから開始されます。
  
  パラメータ:
  
  directory - nullではなく、ディスク・リポジトリのロケーション
  
  戻り値:
  
  イベント・ストリーム(nullではない)
  
  例外:
  
  IOException - ストリームを開けない場合、またはリポジトリにアクセスしようとしたときにI/Oエラーが発生した場合
  
  SecurityException - セキュリティ・マネージャが存在し、checkReadメソッドがディレクトリへの読取りアクセスを拒否するか、ディレクトリ内のファイルを拒否する場合。
- openFile
  
  static EventStream openFile(Path file) throws IOException
  
  ファイルからイベント・ストリームを作成します。
  デフォルトでは、ストリームはファイルの最初のイベントから開始されます。
  
  パラメータ:
  
  file - nullではなく、ファイルのロケーション
  
  戻り値:
  
  イベント・ストリーム(nullではない)
  
  例外:
  
  IOException - ファイルを開くことができない場合または読取り中にI/Oエラーが発生した場合。
  
  SecurityException - セキュリティ・マネージャが存在し、そのcheckReadメソッドがファイルへの読取りアクセスを拒否した場合
- onEvent
  
  void onEvent(Consumer<RecordedEvent> action)
  
  ストリーム内のすべてのイベントで実行するアクションを登録します。
  
  パラメータ:
  
  action - nullではなく、各RecordedEventで実行するアクション。
- onEvent
  
  void onEvent(String eventName, Consumer<RecordedEvent> action)
  
  名前と一致するすべてのイベントに対して実行するアクションを登録します。
  
  パラメータ:
  
  eventName - イベントの名前(null以外)
  
  action - nullではなく、イベント名と一致する各RecordedEventに対して実行するアクション
- onFlush
  
  void onFlush(Runnable action)
  
  ストリームのフラッシュ後に実行するアクションを登録します。
  
  パラメータ:
  
  action - ストリームのフラッシュ後に実行するアクション。nullではありません
- onError
  
  void onError(Consumer<Throwable> action)
  
  例外が発生した場合に実行するアクションを登録します。
  アクションが登録されていない場合、例外スタック・トレースは標準エラーに出力されます。
  アクションを登録すると、デフォルトの動作がオーバーライドされます。複数のアクションが登録されている場合は、登録順に実行されます。
  このメソッド自体が例外をスローすると、結果として生じる動作は未定義です。
  
  パラメータ:
  
  action - nullではなく例外が発生した場合に実行するアクション
- onClose
  
  void onClose(Runnable action)
  
  ストリームが閉じられたときに実行するアクションを登録します。
  ストリームがすでにクローズされている場合は、現在のスレッド内でただちにアクションが実行されます。
  
  パラメータ:
  
  action - ストリームが閉じられた後に実行するアクション。nullはクローズされません
  
  関連項目:
  
  close()
- close
  
  void close()
  
  このストリームに関連付けられているすべてのリソースを解放します。
  すでに閉じられているストリームを閉じても、何の影響もありません。
  
  定義:
  
  close、インタフェース: AutoCloseable
- remove
  
  boolean remove(Object action)
  
  アクションを登録解除します。
  アクションが複数回登録されている場合、すべてのインスタンスが登録解除されます。
  
  パラメータ:
  
  action - 登録解除する処理(nullではない)
  
  戻り値:
  
  アクションが登録解除された場合はtrue、登録されていない場合はfalse
  
  関連項目:
  
  onEvent(Consumer), onEvent(String, Consumer), onFlush(Runnable), onClose(Runnable), onError(Consumer)
- setReuse
  
  void setReuse(boolean reuse)
  
  onEvent(Consumer)処理のイベント・オブジェクトを再利用できることを指定します。
  再利用を {@code trueに設定する場合は、アクションの完了後にイベント・オブジェクトへの参照を保持しないようにしてください。
  
  パラメータ:
  
  reuse - イベント・オブジェクトを再利用できる場合はtrue、それ以外の場合はfalse
- setOrdered
  
  void setOrdered(boolean ordered)
  
  イベントがストリームにコミットされた時間でソートされて、時系列順にイベントが到着することを指定します。
  
  パラメータ:
  
  ordered - イベント・オブジェクトが#onEvent(Consumer)に日付順に着信した場合
- setStartTime
  
  void setStartTime(Instant startTime)
  
  ストリームの開始時間を指定します。
  開始時間は、ストリームの開始前に設定する必要があります
  
  パラメータ:
  
  startTime - 開始時間(nullではない)
  
  例外:
  
  IllegalStateException - ストリームがすでに開始されている場合
  
  関連項目:
  
  start(), startAsync()
- setEndTime
  
  void setEndTime(Instant endTime)
  
  ストリームの終了時間を指定します。
  終了時間は、ストリームの開始前に設定する必要があります。
  最後に、ストリームはクローズされます。
  
  パラメータ:
  
  endTime - 終了時間(nullではない)
  
  例外:
  
  IllegalStateException - ストリームがすでに開始されている場合
  
  関連項目:
  
  start(), startAsync()
- start
  
  void start()
  
  アクションの開始処理。
  アクションは、現在のスレッドで実行されます。
  
  例外:
  
  IllegalStateException - ストリームがすでに開始されているか、閉じている場合
- startAsync
  
  void startAsync()
  
  アクションの非同期処理を開始します。
  アクションは、単一の独立したスレッドで実行されます。
  
  例外:
  
  IllegalStateException - ストリームがすでに開始されているか、閉じている場合
- awaitTermination
  
  void awaitTermination(Duration timeout) throws InterruptedException
  
  すべてのアクションが完了するか、ストリームがクローズされるか、タイムアウトが発生するか、現在のスレッドが中断されるまで、いずれか先に発生するまでブロックします。
  
  パラメータ:
  
  timeout - nullではなく最大待機時間
  
  例外:
  
  IllegalArgumentException - timeoutが負の値の場合
  
  InterruptedException - 待機中に割込みが発生した場合
  
  関連項目:
  
  start(), startAsync(), Thread.interrupt()
- awaitTermination
  
  void awaitTermination() throws InterruptedException
  
  すべてのアクションが完了するか、ストリームがクローズされるか、現在のスレッドが中断されるまで、いずれか早いほうで発生します。
  
  例外:
  
  InterruptedException - 待機中に割込みが発生した場合
  
  関連項目:
  
  start(), startAsync(), Thread.interrupt()

インタフェースEventStream

メソッドのサマリー

メソッドの詳細