インタフェースEventStream

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

AutoCloseable

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

RecordingStream, RemoteRecordingStream

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(Consumer)メソッドを使用して登録できます。 エラー・ハンドラが登録されていない場合、デフォルトの動作では、例外とそのバック・トレースが標準エラー・ストリームに出力されます。

次の例では、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)	ストリームのフラッシュ後に実行するアクションを登録します。
default void	onMetadata(Consumer<MetadataEvent> 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エラーが発生した場合

openRepository

static EventStream openRepository(Path directory) throws IOException

ディスク・リポジトリからイベント・ストリームを作成します。

デフォルトでは、ストリームはFlight Recorderによりフラッシュされる次のイベントから開始されます。

信頼できるディスク・リポジトリのみを開く必要があります。

パラメータ:

directory - nullではなく、ディスク・リポジトリのロケーション

戻り値:

イベント・ストリーム(nullではない)

スロー:

IOException - ストリームを開けない場合、またはリポジトリにアクセスしようとしたときにI/Oエラーが発生した場合

openFile

static EventStream openFile(Path file) throws IOException

ファイルからイベント・ストリームを作成します。

デフォルトでは、ストリームはファイルの最初のイベントから開始されます。

信頼できるソースからの記録ファイルのみを開く必要があります。

パラメータ:

file - nullではなく、ファイルのロケーション

戻り値:

イベント・ストリーム(nullではない)

スロー:

IOException - ファイルを開くことができない場合または読取り中にI/Oエラーが発生した場合。

onMetadata

default void onMetadata(Consumer<MetadataEvent> action)

新しいメタデータがストリームに到着したときに実行するアクションを登録します。 イベントのイベント・タイプは、常に実際のイベントより前に到着します。 ストリームを開始する前に、アクションを登録する必要があります。

次の例は、新しいイベント・タイプをリスニングし、イベント・タイプ名が正規表現に一致する場合はアクションを登録し、一致するイベントが見つかった場合はカウンタを増やす方法を示しています。 汎用のonEvent(Consumer)メソッドではなく、イベント・タイプごとにアクションを使用する利点は、ストリーム実装では、関心のないイベントの読取りを回避できることです。

static long count = 0;
public static void main(String... args) throws IOException {
    Path file = Path.of(args[0]);
    String regExp = args[1];
    var pr = Pattern.compile(regExp).asMatchPredicate();
    try (var s = EventStream.openFile(file)) {
        s.setOrdered(false);
        s.onMetadata(metadata -> metadata.getAddedEventTypes()
         .stream().map(EventType::getName).filter(pr)
         .forEach(eventName -> s.onEvent(eventName, event -> count++)));
        s.start();
        System.out.println(count + " events matches " + regExp);
    }
}

実装要件:

このメソッドのデフォルト実装は空です。

パラメータ:

action - nullではなく実行

スロー:

IllegalStateException - ストリームの開始後にアクションが追加された場合

導入されたバージョン:

16

onEvent

void onEvent(Consumer<RecordedEvent> action)

ストリーム内のすべてのイベントで実行するアクションを登録します。

イベント・タイプのサブセットに対してアクションを実行するには、汎用アクションで実装される選択またはフィルタリング・メカニズムよりもパフォーマンスが高い可能性があるため、onEvent(String, Consumer)およびonMetadata(Consumer)の使用を検討してください。

パラメータ:

action - nullではなく、各RecordedEventで実行するアクション。

関連項目:

• onEvent(Consumer)
• onMetadata(Consumer)

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)処理のイベント・オブジェクトを再利用できることを指定します。

reuseが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()

アクションの処理を開始します。

アクションは、現在のスレッドで実行されます。

ストリームを停止するには、close()メソッドを使用します。

スロー:

IllegalStateException - ストリームがすでに開始されているか、閉じている場合

startAsync

void startAsync()

アクションの非同期処理を開始します。

アクションは、単一の独立したスレッドで実行されます。

ストリームを停止するには、close()メソッドを使用します。

スロー:

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()