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

インターフェース AsyncResponse

  • public interface AsyncResponse
    非同期サーバー側レスポンス処理の手段を提供する注入可能な JAX-RS 非同期レスポンス。

    @Suspended アノテーションを使用して、AsyncResponse の新しいインスタンスを resource or sub-resource method パラメーターに挿入できます。

    各非同期レスポンスインスタンスは、実行中のリクエストにバインドされ、リクエスト処理結果を非同期で提供したり、中断されたクライアント接続を操作したりするために使用できます。使用可能な操作は次のとおりです。
    • 一時停止状態データの更新 (タイムアウト値、レスポンス ..。)
    • 中断されたリクエスト処理を再開する
    • 中断されたリクエスト処理をキャンセルする

    次の例は、非同期 HTTP リクエスト処理のための AsyncResponse の使用を示しています。

     @Path("/messages/next")
 public class MessagingResource {
     private static final BlockingQueue<AsyncResponse> suspended = new ArrayBlockingQueue<AsyncResponse>(5);

     @GET
     public void readMessage(@Suspended AsyncResponse ar) throws InterruptedException {
         suspended.put(ar);
     }

     @POST
     public String postMessage(final String message) throws InterruptedException {
         final AsyncResponse ar = suspended.take();
         ar.resume(message); // resumes the processing of one GET request
         return "Message sent";
     }
 }

    非同期レスポンスが正のタイムアウト値で中断され、タイムアウトになる前に明示的に再開されなかった場合、レスポンスに正のタイムアウト値が設定されていれば、指定されたタイムアウトしきい値に達すると処理が再開されます。

    デフォルトでは、タイムアウトした非同期レスポンスは、HTTP 503 (Service unavailable) エラーレスポンスステータスコードが設定されている WebApplicationException で再開されます。このデフォルトの動作は、カスタム time-out handler の setting によってオーバーライドされる場合があります。

    導入:
    2.0
    作成者:
    Marek Potociar

    • フィールドサマリー

      フィールド  
      修飾子と型 フィールド 説明
      static longNO_TIMEOUT
      サスペンドタイムアウト値を指定しない定数。

    • メソッドのサマリー

      すべてのメソッド   インスタンスメソッド   抽象メソッド  
      修飾子と型 メソッド 説明
      booleancancel()
      中断されたリクエスト処理をキャンセルします。
      booleancancel​(int retryAfter)
      中断されたリクエスト処理をキャンセルします。
      booleancancel​(DateSE retryAfter)
      中断されたリクエスト処理をキャンセルします。
      booleanisCancelled()
      非同期レスポンスインスタンスがキャンセルされているかどうかを確認します。
      booleanisDone()
      この非同期レスポンスインスタンスが属するリクエストの処理が終了したかどうかを確認します。
      booleanisSuspended()
      非同期レスポンスインスタンスが一時停止状態かどうかを確認します。
      CollectionSE<ClassSE<?>>register​(ClassSE<?> callback)
      実装されたコールバックインターフェースに基づいて非同期レスポンスのライフサイクルイベントを受信するために、非同期処理ライフサイクルコールバッククラスを登録します。
      MapSE<ClassSE<?>,​CollectionSE<ClassSE<?>>>register​(ClassSE<?> callback, ClassSE<?>... callbacks)
      非同期処理ライフサイクルコールバッククラスを登録して、実装されたコールバックインターフェースに基づいて非同期レスポンスのライフサイクルイベントを受信します。
      CollectionSE<ClassSE<?>>register​(ObjectSE callback)
      実装されたコールバックインターフェースに基づいて非同期レスポンスのライフサイクルイベントを受信するために、非同期処理ライフサイクルコールバックインスタンスを登録します。
      MapSE<ClassSE<?>,​CollectionSE<ClassSE<?>>>register​(ObjectSE callback, ObjectSE... callbacks)
      実装されたコールバックインターフェースに基づいて非同期レスポンスのライフサイクルイベントを受信するために、非同期処理ライフサイクルコールバックインスタンスを登録します。
      booleanresume​(ObjectSE response)
      提供されたレスポンスデータを使用して、中断されたリクエスト処理を再開します。
      booleanresume​(ThrowableSE response)
      提供されたスロー可能オブジェクトを使用して、中断されたリクエスト処理を再開します。
      booleansetTimeout​(long time, TimeUnitSE unit)
      サスペンドタイムアウトを設定 / 更新します。
      voidsetTimeoutHandler​(TimeoutHandler handler)
      中断された非同期レスポンスのタイムアウトハンドラーを設定 / 置換します。

    • フィールドの詳細

      • NO_TIMEOUT

        static final long NO_TIMEOUT
        サスペンドタイムアウト値を指定しない定数。
        関連事項:
        定数フィールド値

    • メソッドの詳細

      • resume

        boolean resume​(ObjectSE response)
        提供されたレスポンスデータを使用して、中断されたリクエスト処理を再開します。提供されるレスポンスデータは、JAX-RS resource method から返すことができる任意の Java 型にすることができます。

        このメソッドが成功するには、非同期レスポンスがまだ suspended 状態である必要があります。

        このメソッドを実行することにより、リクエストは正常に完了するか、エラーで完了することが保証されます。JAX-RS ランタイムによるデータ処理は、JAX-RS リソースによって同期的に返されるレスポンスデータの場合と同じパスに従いますが、マッピングされていない例外が JAX-RS ランタイムによって再スローされず、ホスティング I によって処理される点が異なります。/O コンテナー。代わりに、マップされていない例外は、コンテナー固有のコールバックメカニズムを介してホスティング I/O コンテナーに伝播されます。コンテナーの実装によっては、伝播されたマップされていない例外により、通常、エラーステータスがクライアントに送信されたり、接続が閉じられたりします。

        パラメーター:
        response - 中断されたリクエストにレスポンスして返送されるデータ。
        戻り値:
        true リクエスト処理が再開された場合、リクエスト処理が suspended ではなく再開できなかった場合に false を返します。
        関連事項:
        resume(Throwable)

      • resume

        boolean resume​(ThrowableSE response)
        提供されたスロー可能オブジェクトを使用して、中断されたリクエスト処理を再開します。提供されたスロー可能オブジェクトには、JAX-RS resource method によってスローされた例外と同じルールが適用されます。

        このメソッドを実行することにより、リクエストは正常に完了するか、エラーで完了することが保証されます。JAX-RS ランタイムによるスロー可能な処理は、JAX-RS リソースによって同期的に返されるレスポンスデータの場合と同じパスに従いますが、マッピングされていない例外が JAX-RS ランタイムによって再スローされてホスティング I によって処理されない点が異なります。/O コンテナー。代わりに、マップされていない例外は、コンテナー固有のコールバックメカニズムを介してホスティング I/O コンテナーに伝播されます。コンテナーの実装によっては、伝播されたマップされていない例外により、通常、エラーステータスがクライアントに送信されたり、接続が閉じられたりします。

        パラメーター:
        response - 一時停止されたリクエストに応じて発生する例外。
        戻り値:
        レスポンスが再開された場合は true、レスポンスが suspended でなく、再開できなかった場合は false を返します。
        関連事項:
        resume(Object)

      • cancel

        boolean cancel()
        中断されたリクエスト処理をキャンセルします。

        このメソッドを使用してリクエスト処理がキャンセルされた場合、JAX-RS 実装は、HTTP 503 (Service unavailable) エラーレスポンスを返送することにより、リクエスト処理がキャンセルされたことをクライアントに示さなければなりません。

        cancel(...) メソッドを複数回呼び出してリクエスト処理をキャンセルすると、リクエスト処理を 1 回だけキャンセルするのと同じ効果があります。すでにキャンセルまたは再開された非同期レスポンスインスタンスで cancel(...) メソッドを呼び出しても効果はなく、リクエストが以前にキャンセルされている場合は、true を返すときにメソッド呼び出しは無視されます。それ以外の場合、リクエストが定期的に再開された場合（resume(...) method を使用）、またはタイムアウトのために再開された場合、メソッドは false を返します。

        戻り値:
        リクエスト処理がキャンセルされた場合は true、リクエスト処理が suspended でなく、キャンセルできず、まだ cancelled でない場合は、false を返します。
        関連事項:
        cancel(int), cancel(java.util.Date)

      • cancel

        boolean cancel​(int retryAfter)
        中断されたリクエスト処理をキャンセルします。

        このメソッドを使用してリクエスト処理がキャンセルされた場合、JAX-RS 実装は、メソッドパラメーターで指定された値に設定された Retry-After ヘッダーを含む HTTP 503 (Service unavailable) エラーレスポンスを返送することにより、リクエスト処理がキャンセルされたことをクライアントに示さなければなりません。

        cancel(...) メソッドを複数回呼び出してリクエスト処理をキャンセルすると、リクエスト処理を 1 回だけキャンセルするのと同じ効果があります。すでにキャンセルまたは再開された非同期レスポンスインスタンスで cancel(...) メソッドを呼び出しても効果はなく、リクエストが以前にキャンセルされている場合は、true を返すときにメソッド呼び出しは無視されます。それ以外の場合、リクエストが定期的に再開された場合（resume(...) method を使用）、またはタイムアウトのために再開された場合、メソッドは false を返します。

        パラメーター:
        retryAfter - レスポンスがクライアントに送信されてから秒数の 10 進数で、リクエスト元のクライアントがサービスを利用できないと予想される期間を示します。
        戻り値:
        リクエスト処理がキャンセルされた場合は true、リクエスト処理が suspended でなく、キャンセルできず、まだ cancelled でない場合は、false を返します。
        関連事項:
        cancel(), cancel(java.util.Date)

      • cancel

        boolean cancel​(DateSE retryAfter)
        中断されたリクエスト処理をキャンセルします。

        このメソッドを使用してリクエスト処理がキャンセルされた場合、JAX-RS 実装は、メソッドパラメーターで指定された値に設定された Retry-After ヘッダーを含む HTTP 503 (Service unavailable) エラーレスポンスを返送することにより、リクエスト処理がキャンセルされたことをクライアントに示さなければなりません。

        cancel(...) メソッドを複数回呼び出してリクエスト処理をキャンセルすると、リクエスト処理を 1 回だけキャンセルするのと同じ効果があります。すでにキャンセルまたは再開された非同期レスポンスインスタンスで cancel(...) メソッドを呼び出しても効果はなく、リクエストが以前にキャンセルされている場合は、true を返すときにメソッド呼び出しは無視されます。それ以外の場合、リクエストが定期的に再開された場合（resume(...) method を使用）、またはタイムアウトのために再開された場合、メソッドは false を返します。

        パラメーター:
        retryAfter - リクエスト元のクライアントがサービスを利用できないと予想される期間を示す日付。
        戻り値:
        リクエスト処理がキャンセルされた場合は true、リクエスト処理が suspended でなく、キャンセルできず、まだ cancelled でない場合は、false を返します。
        関連事項:
        cancel(), cancel(int)

      • isSuspended

        boolean isSuspended()
        非同期レスポンスインスタンスが一時停止状態にあるかどうかを確認します。この非同期レスポンスがまだ中断されていて、まだ処理が完了していない場合（レスポンスを再開またはキャンセルすることにより）、メソッドは true を返します。
        戻り値:
        この非同期レスポンスがサスペンド状態の場合は true、それ以外の場合は false。
        関連事項:
        isCancelled(), isDone()

      • isCancelled

        boolean isCancelled()
        非同期レスポンスインスタンスがキャンセルされているかどうかを確認します。この非同期レスポンスが完了する前にキャンセルされた場合、メソッドは true を返します。
        戻り値:
        このタスクが完了する前にキャンセルされた場合は true。
        関連事項:
        isSuspended(), isDone()

      • isDone

        boolean isDone()
        この非同期レスポンスインスタンスが属するリクエストの処理が終了したかどうかを確認します。この非同期レスポンスがバインドされているリクエストの処理が終了すると、メソッドは true を返します。

        リクエスト処理は、通常の終了、一時停止のタイムアウト、キャンセルが原因で終了する場合があります。これらすべての場合、このメソッドは true を返します。

        戻り値:
        この実行コンテキストが処理を終了した場合は true。
        関連事項:
        isSuspended(), isCancelled()

      • setTimeout

        boolean setTimeout​(long time,
                   TimeUnitSE unit)
        サスペンドタイムアウトを設定 / 更新します。

        新しいサスペンドタイムアウト値は、以前に指定されたタイムアウト値を上書きします。このメソッドが成功するには、非同期レスポンスが suspended 状態のままである必要があります。

        パラメーター:
        time - 与えられた時間 unit のタイムアウト値を一時停止します。値が 0 以下の場合、コンテキストは無期限に中断されます。
        unit - タイムアウト値の時間単位を一時停止します。
        戻り値:
        中断タイムアウトが設定されている場合は true、リクエスト処理が suspended 状態でない場合は false を返します。

      • setTimeoutHandler

        void setTimeoutHandler​(TimeoutHandler handler)
        中断された非同期レスポンスのタイムアウトハンドラーを設定 / 置換します。

        タイムアウトハンドラーは、この非同期レスポンスの一時停止期間がタイムアウトしたときに呼び出されます。タイムアウトハンドラーのロールは、いずれかの方法でタイムアウト状況を解決することです。

        • 中断されたレスポンスを再開する
        • 一時停止されたレスポンスをキャンセルする
        • 新しいサスペンドタイムアウトを設定してサスペンド期間を延長する

        レスポンスが indefinitely で中断された場合、タイムアウトハンドラーが呼び出されない可能性があることに注意してください。

        パラメーター:
        handler - レスポンスタイムアウトハンドラー。

      • register

        CollectionSE<ClassSE<?>> register​(ClassSE<?> callback)
        実装されたコールバックインターフェースに基づいて非同期レスポンスのライフサイクルイベントを受信するために、非同期処理ライフサイクルコールバッククラスを登録します。
        パラメーター:
        callback - コールバッククラス。
        戻り値:
        登録されたコールバックインターフェースのコレクション。コールバッククラスが認識されたコールバックインターフェースを実装していない場合、返されるコレクションは空になります。
        例外:
        NullPointerExceptionSE - コールバッククラスが null の場合。

      • register

        MapSE<ClassSE<?>,​CollectionSE<ClassSE<?>>> register​(ClassSE<?> callback,
                                                  ClassSE<?>... callbacks)
        非同期処理ライフサイクルコールバッククラスを登録して、実装されたコールバックインターフェースに基づいて非同期レスポンスのライフサイクルイベントを受信します。
        パラメーター:
        callback - コールバッククラス。
        callbacks - 追加のコールバッククラス。
        戻り値:
        登録されたクラスのマップと、各クラスに登録されたコールバックインターフェース。コールバッククラスが認識されたコールバックインターフェースを実装していない場合、クラスに登録されているインターフェースの関連コレクションは空になります。
        例外:
        NullPointerExceptionSE - コールバッククラスのいずれかが null の場合。

      • register

        CollectionSE<ClassSE<?>> register​(ObjectSE callback)
        実装されたコールバックインターフェースに基づいて非同期レスポンスのライフサイクルイベントを受信するために、非同期処理ライフサイクルコールバックインスタンスを登録します。
        パラメーター:
        callback - 認識されたコールバックインターフェースの 1 つ以上を実装するコールバックインスタンス。
        戻り値:
        登録されたコールバックインターフェースのコレクション。コールバッククラスが認識されたコールバックインターフェースを実装していない場合、返されるコレクションは空になります。
        例外:
        NullPointerExceptionSE - コールバックインスタンスが null の場合。

      • register

        MapSE<ClassSE<?>,​CollectionSE<ClassSE<?>>> register​(ObjectSE callback,
                                                  ObjectSE... callbacks)
        実装されたコールバックインターフェースに基づいて非同期レスポンスのライフサイクルイベントを受信するために、非同期処理ライフサイクルコールバックインスタンスを登録します。
        パラメーター:
        callback - コールバックインスタンス。
        callbacks - 追加のコールバックインスタンス。
        戻り値:
        登録されたクラスのマップと、各クラスに登録されたコールバックインターフェース。コールバッククラスが認識されたコールバックインターフェースを実装していない場合、クラスに登録されているインターフェースの関連コレクションは空になります。
        例外:
        NullPointerExceptionSE - コールバックインスタンスのいずれかが null の場合。