AsyncContext (Jakarta EE 8 Specification API)

```
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

フィールドサマリー

フィールド
修飾子と型	フィールドと説明
`static StringSE`	`ASYNC_CONTEXT_PATH` `dispatch(String)` または `dispatch(ServletContext,String)` のターゲットが元のコンテキストパスを使用できるようにするリクエスト属性の名前
`static StringSE`	`ASYNC_MAPPING` 元の `HttpServletMapping` が `dispatch(String)` または `dispatch(ServletContext,String)` のターゲットで使用可能になるリクエスト属性の名前
`static StringSE`	`ASYNC_PATH_INFO` `dispatch(String)` または `dispatch(ServletContext,String)` のターゲットが元のパス情報を使用できるようにするリクエスト属性の名前
`static StringSE`	`ASYNC_QUERY_STRING` 元のクエリ文字列が `dispatch(String)` または `dispatch(ServletContext,String)` のターゲットで使用可能になるリクエスト属性の名前
`static StringSE`	`ASYNC_REQUEST_URI` `dispatch(String)` または `dispatch(ServletContext,String)` のターゲットが元のリクエスト URI を使用できるようにするリクエスト属性の名前
`static StringSE`	`ASYNC_SERVLET_PATH` `dispatch(String)` または `dispatch(ServletContext,String)` のターゲットが元のサーブレットパスを使用できるようにするリクエスト属性の名前

メソッドのサマリー

すべてのメソッドインスタンスメソッド抽象メソッド
修飾子と型	メソッドと説明
`void`	`addListener(AsyncListener listener)` 指定された `AsyncListener` を、`ServletRequest.startAsync()` メソッドの 1 つへの呼び出しによって開始された最新の非同期サイクルに登録します。
`void`	`addListener(AsyncListener listener, ServletRequest servletRequest, ServletResponse servletResponse)` 指定された `AsyncListener` を、`ServletRequest.startAsync()` メソッドの 1 つへの呼び出しによって開始された最新の非同期サイクルに登録します。
`void`	`complete()` この AsyncContext の初期化に使用されたリクエストで開始された非同期操作を完了し、この AsyncContext の初期化に使用されたレスポンスを閉じます。
`<T extends AsyncListener> T`	`createListener(ClassSE<T> clazz)` 指定された `AsyncListener` クラスをインスタンス化します。
`void`	`dispatch()` この AsyncContext のリクエストオブジェクトとレスポンスオブジェクトをサーブレットコンテナーにディスパッチします。
`void`	`dispatch(ServletContext context, StringSE path)` この AsyncContext のリクエストオブジェクトとレスポンスオブジェクトを、指定された`コンテキスト`を範囲とする指定された`パス`にディスパッチします。
`void`	`dispatch(StringSE path)` この AsyncContext のリクエストオブジェクトとレスポンスオブジェクトを指定された `path` にディスパッチします。
`ServletRequest`	`getRequest()` `ServletRequest.startAsync()` または `ServletRequest.startAsync(ServletRequest, ServletResponse)` を呼び出して、この AsyncContext を初期化するために使用されたリクエストを取得します。
`ServletResponse`	`getResponse()` `ServletRequest.startAsync()` または `ServletRequest.startAsync(ServletRequest, ServletResponse)` を呼び出して、この AsyncContext を初期化するために使用されたレスポンスを取得します。
`long`	`getTimeout()` この AsyncContext のタイムアウト（ミリ秒単位）を取得します。
`boolean`	`hasOriginalRequestAndResponse()` この AsyncContext が元のオブジェクトまたはアプリケーションでラップされたリクエストオブジェクトとレスポンスオブジェクトで初期化されたかどうかを確認します。
`void`	`setTimeout(long timeout)` この AsyncContext のタイムアウト（ミリ秒単位）を設定します。
`void`	`start(RunnableSE run)` コンテナーにスレッドをディスパッチし、管理されたスレッドプールからスレッドをディスパッチして、指定された `Runnable` を実行します。

- フィールドの詳細
  - ASYNC_REQUEST_URI
```
static final StringSE ASYNC_REQUEST_URI
```
    dispatch(String) または dispatch(ServletContext,String) のターゲットが元のリクエスト URI を使用できるようにするリクエスト属性の名前
    関連事項:
    定数フィールド値
  - ASYNC_CONTEXT_PATH
```
static final StringSE ASYNC_CONTEXT_PATH
```
    dispatch(String) または dispatch(ServletContext,String) のターゲットが元のコンテキストパスを使用できるようにするリクエスト属性の名前
    関連事項:
    定数フィールド値
  - ASYNC_MAPPING
```
static final StringSE ASYNC_MAPPING
```
    元の HttpServletMapping が dispatch(String) または dispatch(ServletContext,String) のターゲットで使用可能になるリクエスト属性の名前
    関連事項:
    定数フィールド値
  - ASYNC_PATH_INFO
```
static final StringSE ASYNC_PATH_INFO
```
    dispatch(String) または dispatch(ServletContext,String) のターゲットが元のパス情報を使用できるようにするリクエスト属性の名前
    関連事項:
    定数フィールド値
  - ASYNC_SERVLET_PATH
```
static final StringSE ASYNC_SERVLET_PATH
```
    dispatch(String) または dispatch(ServletContext,String) のターゲットが元のサーブレットパスを使用できるようにするリクエスト属性の名前
    関連事項:
    定数フィールド値
  - ASYNC_QUERY_STRING
```
static final StringSE ASYNC_QUERY_STRING
```
    元のクエリ文字列が dispatch(String) または dispatch(ServletContext,String) のターゲットで使用可能になるリクエスト属性の名前
    関連事項:
    定数フィールド値
- メソッドの詳細
  - getRequest
```
ServletRequest getRequest()
```
    ServletRequest.startAsync() または ServletRequest.startAsync(ServletRequest, ServletResponse) を呼び出して、この AsyncContext を初期化するために使用されたリクエストを取得します。
    戻り値:
    この AsyncContext の初期化に使用されたリクエスト
    例外:
    IllegalStateExceptionSE - complete() または dispatch() メソッドのいずれかが非同期サイクルで呼び出された場合
  - getResponse
```
ServletResponse getResponse()
```
    ServletRequest.startAsync() または ServletRequest.startAsync(ServletRequest, ServletResponse) を呼び出して、この AsyncContext を初期化するために使用されたレスポンスを取得します。
    戻り値:
    この AsyncContext を初期化するために使用されたレスポンス
    例外:
    IllegalStateExceptionSE - complete() または dispatch() メソッドのいずれかが非同期サイクルで呼び出された場合
  - 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)
```
    指定された AsyncListener を、ServletRequest.startAsync() メソッドの 1 つへの呼び出しによって開始された最新の非同期サイクルに登録します。
    指定された AsyncListener は、非同期サイクルが正常に完了するか、タイムアウトしてエラーが発生するか、ServletRequest.startAsync() メソッドの 1 つを介して新しい非同期サイクルが開始されると、AsyncEvent を受け取ります。
    AsyncListener インスタンスは、追加された順に通知されます。
    ServletRequest.startAsync(ServletRequest, ServletResponse) または ServletRequest.startAsync() が呼び出された場合、AsyncListener が通知されたときに、AsyncEvent からまったく同じリクエストおよびレスポンスオブジェクトを使用できます。
    パラメーター:
    listener - 登録する AsyncListener
    例外:
    IllegalStateExceptionSE - ServletRequest.startAsync() メソッドの 1 つが呼び出されたコンテナー起動のディスパッチがコンテナーに戻った後にこのメソッドが呼び出された場合
  - 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 が Managed Bean を表す場合、リソース注入をサポートします。マネージド Bean およびリソースインジェクションの詳細については、Java EE プラットフォームおよび JSR 299 仕様を参照してください。
    このメソッドは、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) の最新の呼び出しに渡されたタイムアウト値を返します。
    ゼロ以下のタイムアウト値は、タイムアウトがないことを示します。
    戻り値:
    ミリ秒単位のタイムアウト

インターフェース AsyncContext

フィールドサマリー

メソッドのサマリー

フィールドの詳細

ASYNC_REQUEST_URI

ASYNC_CONTEXT_PATH

ASYNC_MAPPING

ASYNC_PATH_INFO

ASYNC_SERVLET_PATH

ASYNC_QUERY_STRING

メソッドの詳細

getRequest

getResponse

hasOriginalRequestAndResponse

dispatch

dispatch

dispatch

complete

start

addListener

addListener

createListener

setTimeout

getTimeout