パッケージ jakarta.ws.rs.sse

インターフェース SseEventSource

  • すべてのスーパーインターフェース:
    AutoCloseableSE
    public interface SseEventSource
extends AutoCloseableSE
    incoming Server-Sent Events を読み取って処理するためのクライアント。

    このクラスの SSE イベントソースインスタンスはスレッドセーフです。新しいインスタンスをビルドするには、SseEventSource.target(endpoint) ファクトリメソッドを使用して新しいイベントソースビルダーを取得します。このビルダーをさらにカスタマイズして、最終的に新しい SSE イベントソースを作成するために使用できます。

    SseEventSource が作成されると、関連する web target への open a connection に使用できます。接続を確立した後、イベントソースは受信受信イベントの処理を開始します。新しいイベントが受信されるたびに、登録されたイベントコンシューマーで Consumer<InboundSseEvent>#accept(InboundSseEvent)SE メソッドが呼び出されます。

    サポートの再接続

    SseEventSource は、最後に受信した SSE イベント id フィールド値に基づく欠落イベントの配信のネゴシエーションを含む、接続損失からの自動回復をサポートします。ただし、このフィールドがサーバーによって設定され、ネゴシエーション機能がサーバーによってサポートされている場合に限ります。接続が失われた場合、最後に受信した SSE イベント id フィールド値が、SSE エンドポイントに送信される新しい接続リクエストの一部として "Last-Event-ID" HTTP リクエストヘッダーで送信されます。このような再接続リクエストを受信すると、このネゴシエーション機能をサポートする SSE エンドポイントは、欠落したすべてのイベントを再生することが期待されます。ただし、これはベストエフォートメカニズムであり、すべてのイベントが損失なく配信されることを保証するものではないことに注意してください。すべてのイベントの受信に依存して、それに応じてクライアントアプリケーションコードを設計するべきではありません。

    デフォルトでは、SSE エンドポイントへの接続が失われると、イベントソースは SSE エンドポイントへの再接続を試みる前に 500 ミリ秒待機します。ただし、SSE エンドポイントは、送信されたイベントに特別な retry フィールド値を含めることにより、クライアント側の再試行遅延を制御できます。JAX-RS SseEventSource は、エンドポイントによって設定された受信 SSE イベント retry フィールド値を追跡し、最後に受信した retry フィールド値を再接続遅延として使用して、それに応じて再接続遅延を調整します。

    標準の接続損失障害の処理に加えて、JAX-RS SseEventSource はさまざまな HTTP レスポンスステータスコードおよびヘッダーに対して異なる動作をします。

    • 200-"text/event-stream" の "Content-Type" ヘッダー付き: これは通常の操作です。onEvent はイベントごとに呼び出されます。onComplete は、イベントがなくなると呼び出されます。onError は、処理中に回復不能なエラーが発生した場合にのみ呼び出されます。
    • 200- サポートされていない、または "Content-Type" ヘッダーが欠落している: これはエラー状態です。onError が呼び出されます。
    • 204- これは、サーバーに送信するイベントがないことを示します。onComplete のみが呼び出されます。
    • 503- "Retry-After" ヘッダーが有効な値に設定されている場合: これは、サーバーが使用できないが、クライアントは後で再接続する必要があることを示します。再接続する前にクライアントイベントソースが閉じられない限り、コンシューマーは呼び出されません（onComplete が呼び出されます）。指定された遅延の後、クライアントは自動的に再接続を試行する必要があります。これにより、新しいレスポンスが発生します。
    • 503- "Retry-After" ヘッダーが無効または欠落している: これはエラー状態です。onError が呼び出されます。
    • その他のステータスコード: これはエラー状態です。onError が呼び出されます。

    エラー条件レスポンスの場合、onError コンシューマーに渡される Throwable は、無効な Response オブジェクトを含む WebApplicationException である必要があります。

    登録されたイベントコンシューマーのいずれかで、Consumer<InboundSseEvent>#accept(InboundSseEvent)SE メソッドの呼び出しが例外をスローした場合、これはエラー状態ではないことに注意してください。onError は呼び出されず、イベント処理は停止されません。ユーザーは、イベント処理ロジックの一部として独自に例外を処理することをお勧めします。

    導入:
    2.1
    作成者:
    Marek Potociar

    • メソッドの詳細

      • register

        void register​(ConsumerSE<InboundSseEvent> onEvent)
        InboundSseEvent コンシューマーを登録します。

        特定のコンシューマーは、受信したイベントごとに 1 回呼び出されます。

        パラメーター:
        onEvent - イベントのコンシューマー。
        例外:
        IllegalArgumentExceptionSE - 提供されたパラメーターが null の場合。

      • register

        void register​(ConsumerSE<InboundSseEvent> onEvent,
              ConsumerSE<ThrowableSE> onError)
        InboundSseEvent および ThrowableSE コンシューマーを登録します。

        イベントコンシューマーは、受信したイベントごとに 1 回呼び出され、Throwable コンシューマーは、SseEventSource で検出された回復不能なエラーが発生したときに呼び出されます。

        パラメーター:
        onEvent - イベントのコンシューマー。
        onError - エラーコンシューマー。
        例外:
        IllegalArgumentExceptionSE - 提供されたパラメーターのいずれかが null の場合。

      • register

        void register​(ConsumerSE<InboundSseEvent> onEvent,
              ConsumerSE<ThrowableSE> onError,
              RunnableSE onComplete)
        InboundSseEvent および ThrowableSE コンシューマーと onComplete コールバックを登録します。

        イベントコンシューマーは、受信したイベントごとに 1 回呼び出され、Throwable コンシューマーは、SseEventSource で回復不能なエラーが発生したときに呼び出され、onComplete コールバックは、接続が成功した後、受信するイベントがなくなったときに呼び出されます。onError コールバックが呼び出された場合は、onComplete コールバックは呼び出されないことに注意してください。

        パラメーター:
        onEvent - イベントのコンシューマー。
        onError - エラーコンシューマー。
        onComplete - onComplete ハンドラー。
        例外:
        IllegalArgumentExceptionSE - 提供されたパラメーターのいずれかが null の場合。

      • target

        static SseEventSource.Builder target​(WebTarget endpoint)
        新しく準備されたイベントソースインスタンスのさまざまなアスペクトを構成および微調整する便利な方法を提供する新しい event source builder を作成します。
        パラメーター:
        endpoint - SSE ストリーミングエンドポイント。null であってはなりません。
        戻り値:
        指定された SSE ストリーミングエンドポイントを指す新しいイベントソースインスタンスのビルダー。
        例外:
        NullPointerExceptionSE - 提供された Web ターゲットが null の場合。

      • open

        void open()
        web target の基礎となる提供された SSE への接続を開き、受信 events の処理を開始します。
        例外:
        IllegalStateExceptionSE - イベントソースがすでに開かれている場合。

      • isOpen

        boolean isOpen()
        このイベントソースインスタンスがすでに opened になっていることを確認してください。
        戻り値:
        このイベントソースが開いている場合は true、それ以外の場合は false。

      • close

        default void close()
        このイベントソースを閉じます。

        このメソッドは、内部イベント処理タスクが完了するまで最大 5 秒待機します。

        次で指定:
        インターフェース AutoCloseableSE の close 

      • close

        boolean close​(long timeout,
              TimeUnitSE unit)
        このイベントソースを閉じて、内部イベント処理タスクが指定された待機時間まで完了するのを待ちます。

        このメソッドは、シャットダウンリクエスト後にイベント処理タスクの実行が完了するまで、またはタイムアウトが発生するまで、現在のスレッドが中断されるまで、どちらか早い方でブロックします。

        イベント処理タスクの待機が中断された場合、このメソッドは false を返す前にスレッドの interrupt フラグを復元します。

        パラメーター:
        timeout - 待機する最大時間。
        unit - タイムアウト引数の時間単位。
        戻り値:
        このエグゼキュータが終了した場合は true、終了前にタイムアウトが経過した場合、終了が中断された場合は false。