パッケージ jakarta.servlet

インターフェース AsyncContext

  • public interface AsyncContext
    ServletRequest で開始された非同期操作の実行コンテキストを表すクラス。

    AsyncContext は、ServletRequest.startAsync() または ServletRequest.startAsync(ServletRequest, ServletResponse) の呼び出しによって作成および初期化されます。これらのメソッドを繰り返し呼び出すと、同じ AsyncContext インスタンスが返され、必要に応じて再初期化されます。

    非同期操作がタイムアウトした場合、コンテナーは次の手順を実行する必要があります。

    1. onTimeout メソッドで、非同期操作が開始された ServletRequest に登録されているすべての AsyncListener インスタンスを呼び出します。
    2. どのリスナーも complete() または dispatch() メソッドのいずれも呼び出さない場合は、 HttpServletResponse.SC_INTERNAL_SERVER_ERROR に等しいステータスコードでエラーディスパッチを実行します。
    3. 一致するエラーページが見つからなかった場合、またはエラーページが complete() または dispatch() メソッドのいずれも呼び出さなかった場合は、complete() を呼び出します。
    導入:
    Servlet 3.0

    • メソッドの詳細

      • hasOriginalRequestAndResponse

        boolean hasOriginalRequestAndResponse()
        この AsyncContext が元のオブジェクトまたはアプリケーションでラップされたリクエストオブジェクトとレスポンスオブジェクトで初期化されたかどうかを確認します。

        この情報は、リクエストが非同期モードになった後、 送信方向に呼び出されたフィルターが、 受信の呼び出し中に追加されたリクエストやレスポンスのラッパーを、非同期操作の間保存する必要があるのか、あるいは解放する必要があるのかを判断するために使用することができます。

        戻り値:
        この AsyncContext が ServletRequest.startAsync() の呼び出しによって元のリクエストオブジェクトとレスポンスオブジェクトで初期化された場合、または ServletRequest.startAsync(ServletRequest, ServletResponse) の呼び出しによって初期化され、ServletRequest と ServletResponse のどちらの引数もアプリケーション提供のラッパーを持たない場合は true。そうでなければ偽

      • dispatch

        void dispatch()
        この AsyncContext のリクエストオブジェクトとレスポンスオブジェクトをサーブレットコンテナーにディスパッチします。

        非同期サイクルが ServletRequest.startAsync(ServletRequest, ServletResponse) で開始され、渡されたリクエストが HttpServletRequest のインスタンスである場合、ディスパッチは HttpServletRequest.getRequestURI() によって返された URI に対して行われます。それ以外の場合、ディスパッチは、コンテナーによって最後にディスパッチされたときのリクエストの URI になります。

        次のシーケンスは、これがどのように機能するかを示しています。

         
 // REQUEST dispatch to /url/A
 AsyncContext ac = request.startAsync();
 ...
 ac.dispatch(); // ASYNC dispatch to /url/A
 
 // REQUEST to /url/A
 // FORWARD dispatch to /url/B
 request.getRequestDispatcher("/url/B").forward(request,response);
 // Start async operation from within the target of the FORWARD
 // dispatch
 ac = request.startAsync();
 ...
 ac.dispatch(); // ASYNC dispatch to /url/A
 
 // REQUEST to /url/A
 // FORWARD dispatch to /url/B
 request.getRequestDispatcher("/url/B").forward(request,response);
 // Start async operation from within the target of the FORWARD
 // dispatch
 ac = request.startAsync(request,response);
 ...
 ac.dispatch(); // ASYNC dispatch to /url/B

        このメソッドは、リクエストオブジェクトとレスポンスオブジェクトをコンテナー管理スレッドに渡した直後に戻り、そのスレッドでディスパッチ操作が実行されます。startAsync を呼び出したコンテナー開始ディスパッチがコンテナーに戻る前にこのメソッドが呼び出された場合、ディスパッチ操作はコンテナー開始ディスパッチがコンテナーに戻るまで遅延されます。

        リクエストのディスパッチャー型は DispatcherType.ASYNC に設定されています。forward dispatches とは異なり、レスポンスバッファーとヘッダーはリセットされず、レスポンスがすでにコミットされている場合でもディスパッチすることは正当です。

        リクエストとレスポンスの制御はディスパッチターゲットに委譲され、ディスパッチターゲットの実行が完了すると、ServletRequest.startAsync() または ServletRequest.startAsync(ServletRequest, ServletResponse) が呼び出されない限り、レスポンスは閉じられます。

        このメソッドの実行中に発生する可能性のあるエラーまたは例外は、次のように、コンテナーによってキャッチおよび処理される必要があります。

        1. onError メソッドで、この AsyncContext が作成された ServletRequest に登録されているすべての AsyncListener インスタンスを呼び出し、キャッチされた Throwable を AsyncEvent.getThrowable() 経由で使用できるようにします。
        2. どのリスナーも complete() または dispatch() メソッドのいずれも呼び出さなかった場合は、 HttpServletResponse.SC_INTERNAL_SERVER_ERROR に等しいステータスコードでエラーディスパッチを実行し、上記の Throwable を RequestDispatcher.ERROR_EXCEPTION リクエスト属性の値。
        3. 一致するエラーページが見つからなかった場合、またはエラーページが complete() または dispatch() メソッドのいずれも呼び出さなかった場合は、complete() を呼び出します。

        非同期サイクルごとに最大 1 つの非同期ディスパッチ操作を実行できます。非同期サイクルは、ServletRequest.startAsync() メソッドの 1 つを呼び出すことによって開始されます。同じ非同期サイクル内で追加の非同期ディスパッチ操作を実行しようとすると、IllegalStateException が呼び出されます。ディスパッチされたリクエストでその後 startAsync が呼び出されると、ディスパッチメソッドまたは complete() メソッドのいずれかが呼び出される可能性があります。

        例外:
        IllegalStateExceptionSE - ディスパッチメソッドの 1 つが呼び出され、その結果のディスパッチ中に startAsync メソッドが呼び出されなかった場合、または complete() が呼び出された場合
        関連事項:
        ServletRequest.getDispatcherType()

      • dispatch

        void dispatch​(StringSE path)
        この AsyncContext のリクエストオブジェクトとレスポンスオブジェクトを指定された path にディスパッチします。

        path パラメーターは、この AsyncContext が初期化された ServletContext のスコープ内で、ServletRequest.getRequestDispatcher(String) と同じように解釈されます。

        リクエストのすべてのパス関連クエリメソッドはディスパッチターゲットを反映する必要がありますが、元のリクエスト URI、コンテキストパス、パス情報、サーブレットパス、クエリ文字列は、ASYNC_REQUEST_URI、ASYNC_CONTEXT_PATH、ASYNC_PATH_INFO、ASYNC_SERVLET_PATH、ASYNC_QUERY_STRING の属性から回復できます。リクエスト。これらの属性は、繰り返しディスパッチされている場合でも、常に元のパス要素を反映します。

        非同期サイクルごとに最大 1 つの非同期ディスパッチ操作を実行できます。非同期サイクルは、ServletRequest.startAsync() メソッドの 1 つを呼び出すことによって開始されます。同じ非同期サイクル内で追加の非同期ディスパッチ操作を実行しようとすると、IllegalStateException が呼び出されます。ディスパッチされたリクエストでその後 startAsync が呼び出されると、ディスパッチメソッドまたは complete() メソッドのいずれかが呼び出される可能性があります。

        エラー処理を含む詳細については、dispatch() を参照してください。

        パラメーター:
        path - この AsyncContext が初期化された ServletContext をスコープとするディスパッチターゲットのパス
        例外:
        IllegalStateExceptionSE - ディスパッチメソッドの 1 つが呼び出され、その結果のディスパッチ中に startAsync メソッドが呼び出されなかった場合、または complete() が呼び出された場合
        関連事項:
        ServletRequest.getDispatcherType()

      • dispatch

        void dispatch​(ServletContext context,
              StringSE path)
        この AsyncContext のリクエストオブジェクトとレスポンスオブジェクトを、指定されたコンテキストを範囲とする指定されたパスにディスパッチします。

        path パラメーターは、指定された context をスコープとすることを除いて、ServletRequest.getRequestDispatcher(String) と同じように解釈されます。

        リクエストのすべてのパス関連クエリメソッドはディスパッチターゲットを反映する必要がありますが、元のリクエスト URI、コンテキストパス、パス情報、サーブレットパス、クエリ文字列は、ASYNC_REQUEST_URI、ASYNC_CONTEXT_PATH、ASYNC_PATH_INFO、ASYNC_SERVLET_PATH、ASYNC_QUERY_STRING の属性から回復できます。リクエスト。これらの属性は、繰り返しディスパッチされている場合でも、常に元のパス要素を反映します。

        非同期サイクルごとに最大 1 つの非同期ディスパッチ操作を実行できます。非同期サイクルは、ServletRequest.startAsync() メソッドの 1 つを呼び出すことによって開始されます。同じ非同期サイクル内で追加の非同期ディスパッチ操作を実行しようとすると、IllegalStateException が呼び出されます。ディスパッチされたリクエストでその後 startAsync が呼び出されると、ディスパッチメソッドまたは complete() メソッドのいずれかが呼び出される可能性があります。

        エラー処理を含む詳細については、dispatch() を参照してください。

        パラメーター:
        context - ディスパッチターゲットの ServletContext
        path - 指定された ServletContext をスコープとするディスパッチターゲットのパス
        例外:
        IllegalStateExceptionSE - ディスパッチメソッドの 1 つが呼び出され、その結果のディスパッチ中に startAsync メソッドが呼び出されなかった場合、または complete() が呼び出された場合
        関連事項:
        ServletRequest.getDispatcherType()

      • complete

        void complete()
        この AsyncContext の初期化に使用されたリクエストで開始された非同期操作を完了し、この AsyncContext の初期化に使用されたレスポンスを閉じます。

        この AsyncContext が作成された ServletRequest に登録された型 AsyncListener のリスナーは、その onComplete メソッドで呼び出されます。

        ServletRequest.startAsync() または ServletRequest.startAsync(ServletRequest, ServletResponse) の呼び出し後、およびこのクラスの dispatch メソッドのいずれかの呼び出し前であれば、いつでもこのメソッドを呼び出すことができます。startAsync を呼び出したコンテナー開始ディスパッチがコンテナーに戻る前にこのメソッドが呼び出された場合、コンテナー開始ディスパッチがコンテナーに戻るまで呼び出しは有効になりません (AsyncListener.onComplete(AsyncEvent) の呼び出しは遅延されます)。

      • start

        void start​(RunnableSE run)
        コンテナーがスレッドをディスパッチし、おそらくマネージスレッドプールから、指定された Runnable を実行します。コンテナーは、適切なコンテキスト情報を Runnable に伝達します。
        パラメーター:
        run - 非同期ハンドラー

      • addListener

        void addListener​(AsyncListener listener,
                 ServletRequest servletRequest,
                 ServletResponse servletResponse)
        指定された AsyncListener を、ServletRequest.startAsync() メソッドの 1 つへの呼び出しによって開始された最新の非同期サイクルに登録します。

        指定された AsyncListener は、非同期サイクルが正常に完了するか、タイムアウトしてエラーが発生するか、ServletRequest.startAsync() メソッドの 1 つを介して新しい非同期サイクルが開始されると、AsyncEvent を受け取ります。

        AsyncListener インスタンスは、追加された順に通知されます。

        指定された ServletRequest オブジェクトと ServletResponse オブジェクトは、指定された AsyncEvent の getSuppliedRequest メソッドと getSuppliedResponse メソッドを介して、指定された AsyncListener で使用できるようになります。これらのオブジェクトは、AsyncEvent の配信時にそれぞれ読み取りまたは書き込みを行うべきではありません。指定された AsyncListener が登録されてから追加の折り返しが発生した可能性があるためですが、それらに関連付けられているリソースを解放するために使用される場合があります。

        パラメーター:
        listener - 登録する AsyncListener
        servletRequest - AsyncEvent に含まれる ServletRequest
        servletResponse - AsyncEvent に含まれる ServletResponse
        例外:
        IllegalStateExceptionSE - ServletRequest.startAsync() メソッドの 1 つが呼び出されたコンテナー起動のディスパッチがコンテナーに戻った後にこのメソッドが呼び出された場合

      • createListener

        <T extends AsyncListener> T createListener​(ClassSE<T> clazz)
                                    throws ServletException
        指定された AsyncListener クラスをインスタンス化します。

        返された AsyncListener インスタンスは、addListener メソッドの 1 つを呼び出して、この AsyncContext に登録する前にさらにカスタマイズできます。

        指定された AsyncListener クラスは、インスタンス化に使用されるゼロ引数コンストラクターを定義する必要があります。

        指定された clazz がマネージド Bean を表す場合、このメソッドはリソースインジェクションをサポートします。マネージド Bean とリソースインジェクションの詳細については、Jakarta EE プラットフォームと CDI の仕様を参照してください。

        このメソッドは、AsyncListener に適用可能なすべてのアノテーションをサポートします。

        型パラメーター:
        T - インスタンス化するオブジェクトのクラス
        パラメーター:
        clazz - インスタンス化する AsyncListener クラス
        戻り値:
        新しい AsyncListener インスタンス
        例外:
        ServletException - 指定された clazz のインスタンス化に失敗した場合

      • setTimeout

        void setTimeout​(long timeout)
        この AsyncContext のタイムアウト（ミリ秒単位）を設定します。

        タイムアウトは、ServletRequest.startAsync() メソッドの 1 つが呼び出されたときにコンテナーが開始したディスパッチがコンテナーに戻ると、この AsyncContext に適用されます。

        complete() メソッドもディスパッチメソッドも呼び出されない場合、タイムアウトになります。ゼロ以下のタイムアウト値は、タイムアウトがないことを示します。

        setTimeout(long) が呼び出されない場合、コンテナーのデフォルトのタイムアウトが適用されます。これは、getTimeout() の呼び出しを介して利用できます。

        デフォルト値は 30000 ms です。

        パラメーター:
        timeout - ミリ秒単位のタイムアウト
        例外:
        IllegalStateExceptionSE - ServletRequest.startAsync() メソッドの 1 つが呼び出されたコンテナー起動のディスパッチがコンテナーに戻った後にこのメソッドが呼び出された場合

      • getTimeout

        long getTimeout()
        この AsyncContext のタイムアウト（ミリ秒単位）を取得します。

        このメソッドは、非同期操作のコンテナーのデフォルトのタイムアウト、または setTimeout(long) の最新の呼び出しに渡されたタイムアウト値を返します。

        ゼロ以下のタイムアウト値は、タイムアウトがないことを示します。

        戻り値:
        ミリ秒単位のタイムアウト