AsyncContext (Java Servlet 4.0)

```
public interface AsyncContext
```
ServletRequestで開始された非同期操作の実行コンテキストを表すクラスです。
AsyncContextはServletRequest.startAsync()またはServletRequest.startAsync(ServletRequest, ServletResponse)の呼び出しによって作成および初期化されます。これらのメソッドを繰り返し実行すると、同じAsyncContextインスタンスが返され、適切に再初期化されます。
非同期操作がタイムアウトした場合、コンテナは次の手順を実行する必要があります。
1. 非同期操作が開始されたServletRequestに登録されているすべてのAsyncListenerインスタンスのonTimeoutメソッドを実行します。
2. すべてのリスナーがcomplete()メソッドや、いかなるdispatch()メソッドも呼び出さなかった場合はHttpServletResponse.SC_INTERNAL_SERVER_ERRORに等しいステータスコードを持つエラーディスパッチを実行します。
3. 一致するエラーページが見つからなかった場合、またはエラーページがcomplete()や、いかなるdispatch()メソッドも呼び出さなかった場合はcomplete()を呼び出します。
導入されたバージョン:

Servlet 3.0

フィールドのサマリー

フィールド
修飾子とタイプ	フィールドと説明
`static String`	`ASYNC_CONTEXT_PATH` `dispatch(String)`や`dispatch(ServletContext,String)`のターゲットで使用可能になるオリジナルのコンテキストパスを持つリクエスト属性の名前
`static String`	`ASYNC_MAPPING` `dispatch(String)`や`dispatch(ServletContext,String)`のターゲットで使用可能になるオリジナルの`HttpServletMapping`を持つリクエスト属性の名前
`static String`	`ASYNC_PATH_INFO` `dispatch(String)`や`dispatch(ServletContext,String)`のターゲットで使用可能になるオリジナルのパス情報を持つリクエスト属性の名前
`static String`	`ASYNC_QUERY_STRING` `dispatch(String)`や`dispatch(ServletContext,String)`のターゲットで使用可能になるオリジナルのクエリ文字列を持つリクエスト属性の名前
`static String`	`ASYNC_REQUEST_URI` `dispatch(String)`や`dispatch(ServletContext,String)`のターゲットで使用可能になるオリジナルのリクエストURIを持つリクエスト属性の名前
`static String`	`ASYNC_SERVLET_PATH` `dispatch(String)`や`dispatch(ServletContext,String)`のターゲットで使用可能になるオリジナルのサーブレットパスを持つリクエスト属性の名前

メソッドのサマリー

すべてのメソッドインスタンス・メソッド abstractメソッド
修飾子とタイプ	メソッドと説明
`void`	`addListener(AsyncListener listener)` 与えられた`AsyncListener`を`ServletRequest.startAsync()`メソッドのいずれかの呼び出しによって開始された最新の非同期サイクルに登録します。
`void`	`addListener(AsyncListener listener, ServletRequest servletRequest, ServletResponse servletResponse)` 与えられた`AsyncListener`を`ServletRequest.startAsync()`メソッドのいずれかの呼び出しによって開始された最新の非同期サイクルに登録します。
`void`	`complete()` このAsyncContextを初期化するために使用されたリクエストで開始された非同期操作を完了し、このAsyncContextを初期化するために使用されたレスポンスを閉じます。
`<T extends AsyncListener> T`	`createListener(Class<T> clazz)` 与えられた`AsyncListener`クラスをインスタンス化します。
`void`	`dispatch()` このAsyncContextのリクエストとレスポンスのオブジェクトをサーブレットコンテナにディスパッチします。
`void`	`dispatch(ServletContext context, String path)` このAsyncContextのリクエストとレスポンスのオブジェクトを与えられた`context`のスコープにある与えられた`path`にディスパッチします。
`void`	`dispatch(String 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(Runnable run)` コンテナがおそらく管理されたスレッドプールから取得したスレッドにディスパッチして`Runnable`を実行させます。

- フィールドの詳細
  - ASYNC_REQUEST_URI
```
static final String ASYNC_REQUEST_URI
```
    dispatch(String)やdispatch(ServletContext,String)のターゲットで使用可能になるオリジナルのリクエストURIを持つリクエスト属性の名前
    
    関連項目:
    
    定数フィールド値
  - ASYNC_CONTEXT_PATH
```
static final String ASYNC_CONTEXT_PATH
```
    dispatch(String)やdispatch(ServletContext,String)のターゲットで使用可能になるオリジナルのコンテキストパスを持つリクエスト属性の名前
    
    関連項目:
    
    定数フィールド値
  - ASYNC_MAPPING
```
static final String ASYNC_MAPPING
```
    dispatch(String)やdispatch(ServletContext,String)のターゲットで使用可能になるオリジナルのHttpServletMappingを持つリクエスト属性の名前
    
    関連項目:
    
    定数フィールド値
  - ASYNC_PATH_INFO
```
static final String ASYNC_PATH_INFO
```
    dispatch(String)やdispatch(ServletContext,String)のターゲットで使用可能になるオリジナルのパス情報を持つリクエスト属性の名前
    
    関連項目:
    
    定数フィールド値
  - ASYNC_SERVLET_PATH
```
static final String ASYNC_SERVLET_PATH
```
    dispatch(String)やdispatch(ServletContext,String)のターゲットで使用可能になるオリジナルのサーブレットパスを持つリクエスト属性の名前
    
    関連項目:
    
    定数フィールド値
  - ASYNC_QUERY_STRING
```
static final String ASYNC_QUERY_STRING
```
    dispatch(String)やdispatch(ServletContext,String)のターゲットで使用可能になるオリジナルのクエリ文字列を持つリクエスト属性の名前
    
    関連項目:
    
    定数フィールド値
- メソッドの詳細
  - getRequest
```
ServletRequest getRequest()
```
    ServletRequest.startAsync() や ServletRequest.startAsync(ServletRequest, ServletResponse)の呼び出しによってこのAsyncContextの初期化に使用されたリクエストを取得します。
    
    戻り値:
    
    このAsyncContextの初期化に使用されたリクエスト
    
    例外:
    
    IllegalStateException - 非同期サイクルによってcomplete()やいずれかのdispatch()メソッドが呼び出されていた場合
  - getResponse
```
ServletResponse getResponse()
```
    ServletRequest.startAsync() や ServletRequest.startAsync(ServletRequest, ServletResponse)の呼び出しによってこのAsyncContextの初期化に使用されたレスポンスを取得します。
    
    戻り値:
    
    このAsyncContextの初期化に使用されたレスポンス
    
    例外:
    
    IllegalStateException - 非同期サイクルによってcomplete()やいずれかのdispatch()メソッドが呼び出されていた場合
  - hasOriginalRequestAndResponse
```
boolean hasOriginalRequestAndResponse()
```
    このAsyncContextがオリジナルのリクエストとレスポンスのオブジェクトか、アプリケーションでラップされたリクエストとレスポンスのオブジェクトかをチェックします。
    この情報はアウトバウンド方向で実行されたフィルターによって使用され、リクエストが非同期実行モードになった後に、それらのインバウンド呼び出しの間に追加したリクエストラッパーおよび/またはレスポンスラッパーが非同期操作の間、保持される必要があるか、または解放される必要があるかどうかを判別します。
    
    戻り値:
    
    AsyncContextがServletRequest.startAsync()を呼び出してオリジナルのリクエストとレスポンスのオブジェクトで初期化されたか、 ServletRequest.startAsync(ServletRequest, ServletResponse)を呼び出してどちらの引数もアプリケーションが提供したラッパーを使用せずに初期化された場合はtrue、そうでない場合はfalse
  - 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. このAsyncContextが作成されたServletRequestに登録されているすべてのAsyncListenerインスタンスを、キャッチされたThrowableをAsyncEvent.getThrowable()を使用して利用可能にした状態でonErrorメソッドを呼び出します。
    2. リスナーがどれもcomplete()もdispatch()のいずれかも呼び出さない場合、 HttpServletResponse.SC_INTERNAL_SERVER_ERRORと等しいステータスコードでエラーディスパッチを行い、上記のThrowableをRequestDispatcher.ERROR_EXCEPTIONリクエスト属性の値として利用可能にします。
    3. 一致するエラーページが見つからない場合、もしくはエラーページがcomplete()やdispatch()メソッドのいずれも呼び出さない場合は、 complete()を呼び出します。
    ServletRequest.startAsync()メソッドの1つを呼び出すことによって開始される非同期サイクルごとに、最大で1つの非同期ディスパッチ操作を行うことができます。同じ非同期サイクル内で追加の非同期ディスパッチ操作を実行しようとするとIllegalStateExceptionが発生します。その後にstartAsyncがディスパッチされたリクエストで呼び出された場合、dispatchメソッドまたはcomplete()メソッドのいずれかが呼び出される可能性があります。
    例外:
    
    IllegalStateException - ディスパッチメソッドの1つが呼び出され、ディスパッチの結果までの間にstartAsyncメソッドが呼び出されなかった場合、またはcomplete()が呼び出された場合
    
    関連項目:
    
    ServletRequest.getDispatcherType()
  - dispatch
```
void dispatch(String path)
```
    このAsyncContextのリクエストとレスポンスのオブジェクトを与えられたpathにディスパッチします。
    pathパラメータはServletRequest.getRequestDispatcher(String)と、このAsyncContextが初期化されたServletContextのスコープにて同じ方法で解釈されます。
    リクエストのすべてのパスに関連する問合せメソッドは、ディスパッチターゲットを反映する必要がありますが、オリジナルのリクエストURIやコンテキストパス、パス情報、サーブレットパスおよび問合せ文字列はリクエスト属性のASYNC_REQUEST_URI、ASYNC_CONTEXT_PATH、ASYNC_PATH_INFO、ASYNC_SERVLET_PATH、ASYNC_QUERY_STRINGから復元できるでしょう。これらの属性はディスパッチを繰り返しても、常にオリジナルのパス要素を反映します。
    ServletRequest.startAsync()メソッドの1つを呼び出すことによって開始される非同期サイクルごとに、最大で1つの非同期ディスパッチ操作を行うことができます。同じ非同期サイクル内で追加の非同期ディスパッチ操作を実行しようとするとIllegalStateExceptionが発生します。その後にstartAsyncがディスパッチされたリクエストで呼び出された場合、dispatchメソッドまたはcomplete()メソッドのいずれかが呼び出される可能性があります。
    エラーハンドリングを含め、詳細についてはdispatch()を参照してください。
    
    パラメータ:
    
    path - このAsyncContextが初期化されたServletContextのスコープにあるディスパッチターゲットのパス
    
    例外:
    
    IllegalStateException - ディスパッチメソッドの1つが呼び出され、ディスパッチの結果までの間にstartAsyncメソッドが呼び出されなかった場合、またはcomplete()が呼び出された場合
    
    関連項目:
    
    ServletRequest.getDispatcherType()
  - dispatch
```
void dispatch(ServletContext context,
              String path)
```
    このAsyncContextのリクエストとレスポンスのオブジェクトを与えられたcontextのスコープにある与えられたpathにディスパッチします。
    pathパラメータはServletRequest.getRequestDispatcher(String)と、与えられたcontextのスコープであることを除いて同じ方法で解釈されます。
    リクエストのすべてのパスに関連する問合せメソッドは、ディスパッチターゲットを反映する必要がありますが、オリジナルのリクエストURIやコンテキストパス、パス情報、サーブレットパスおよび問合せ文字列はリクエスト属性のASYNC_REQUEST_URI、ASYNC_CONTEXT_PATH、ASYNC_PATH_INFO、ASYNC_SERVLET_PATH、ASYNC_QUERY_STRINGから復元できるでしょう。これらの属性はディスパッチを繰り返しても、常にオリジナルのパス要素を反映します。
    ServletRequest.startAsync()メソッドの1つを呼び出すことによって開始される非同期サイクルごとに、最大で1つの非同期ディスパッチ操作を行うことができます。同じ非同期サイクル内で追加の非同期ディスパッチ操作を実行しようとするとIllegalStateExceptionが発生します。その後にstartAsyncがディスパッチされたリクエストで呼び出された場合、dispatchメソッドまたはcomplete()メソッドのいずれかが呼び出される可能性があります。
    エラーハンドリングを含め、詳細についてはdispatch()を参照してください。
    
    パラメータ:
    
    context - ディスパッチターゲットのServletContext
    
    path - 与えられたServletContextのスコープにあるディスパッチターゲットのパス
    
    例外:
    
    IllegalStateException - ディスパッチメソッドの1つが呼び出され、ディスパッチの結果までの間にstartAsyncメソッドが呼び出されなかった場合、またはcomplete()が呼び出された場合
    
    関連項目:
    
    ServletRequest.getDispatcherType()
  - complete
```
void complete()
```
    このAsyncContextを初期化するために使用されたリクエストで開始された非同期操作を完了し、このAsyncContextを初期化するために使用されたレスポンスを閉じます。
    このAsyncContextが作成されたServletRequestに登録されているAsyncListener型のリスナーはonCompleteメソッドが呼び出されます。
    ServletRequest.startAsync()またはServletRequest.startAsync(ServletRequest, ServletResponse)を呼び出した後、およびこのクラスのdispatchメソッドのうちの1つを呼び出す前ならいつでもこのメソッドを呼び出すことができます。 startAsyncを呼び出したコンテナ開始ディスパッチがコンテナに返される前にこのメソッドが呼び出されると、コンテナによって開始されたディスパッチが完了するまで、コンテナに戻された後までこのメソッドの呼び出しは何も効果を及ぼしません (し、いかなるAsyncListener.onComplete(AsyncEvent)呼び出しは遅延されます)。
  - start
```
void start(Runnable run)
```
    コンテナがおそらく管理されたスレッドプールから取得したスレッドにディスパッチしてRunnableを実行させます。コンテナは適切なコンテキスト情報をRunnableに伝えることができます。
    
    パラメータ:
    
    run - 非同期ハンドラ
  - addListener
```
void addListener(AsyncListener listener)
```
    与えられたAsyncListenerをServletRequest.startAsync()メソッドのいずれかの呼び出しによって開始された最新の非同期サイクルに登録します。
    指定されたAsyncListenerは、非同期サイクルが正常に完了したとき、タイムアウトしたとき、エラーの結果の時、 ServletRequest.startAsync()メソッドのいずれかの呼び出しによって新しい非同期サイクルが開始された時にAsyncEventを受け取ります。
    AsyncListenerインスタンスは追加された順番で通知されます。
    ServletRequest.startAsync(ServletRequest, ServletResponse)かServletRequest.startAsync()が呼びだされると、 AsyncListenerに通知された時には正しく同じリクエストとレスポンスのオブジェクトがAsyncEventから使用可能になります。
    
    パラメータ:
    
    listener - 登録されるAsyncListener
    
    例外:
    
    IllegalStateException - このメソッドがコンテナが開始したディスパッチの後、ServletRequest.startAsync()メソッドのうちの一つが呼び出された後の間、コンテナに返されるまでに呼ばれた場合
  - addListener
```
void addListener(AsyncListener listener,
                 ServletRequest servletRequest,
                 ServletResponse servletResponse)
```
    与えられたAsyncListenerをServletRequest.startAsync()メソッドのいずれかの呼び出しによって開始された最新の非同期サイクルに登録します。
    指定されたAsyncListenerは、非同期サイクルが正常に完了したとき、タイムアウトしたとき、エラーの結果の時、 ServletRequest.startAsync()メソッドのいずれかの呼び出しによって新しい非同期サイクルが開始された時にAsyncEventを受け取ります。
    AsyncListenerインスタンスは追加された順番で通知されます。
    与えられたServletRequestとServletResponseのオブジェクトは、与えられたAsyncListenerに届けられたAsyncEvent内の各々getSuppliedRequestメソッドとgetSuppliedResponseメソッドを使用することで AsyncListenerで使用できるようになります。これらのオブジェクトは与えられたAsyncListenerが登録されてから追加でのラッピングが発生する可能性があるだけではなく、それらに関連したリソースの開放のために使用される可能性もあるため、AsyncEventが配信された時点では読み書きしないでください。
    
    パラメータ:
    
    listener - 登録されるAsyncListener
    
    servletRequest - AsyncEventに含まれるようになるServletRequest
    
    servletResponse - AsyncEventに含まれるようになるServletResponse
    
    例外:
    
    IllegalStateException - このメソッドがコンテナが開始したディスパッチの後、ServletRequest.startAsync()メソッドのうちの一つが呼び出された後の間、コンテナに返されるまでに呼ばれた場合
  - createListener
```
<T extends AsyncListener> T createListener(Class<T> clazz)
                                    throws ServletException
```
    与えられたAsyncListenerクラスをインスタンス化します。
    返されたAsyncListenerのインスタンスはaddListenerメソッドのうちの一つを利用してこのAsyncContextに登録する前に、さらにカスタマイズすることもできます。
    指定されたAsyncListenerはインスタンス化するために使用される引数のないコンストラクタが定義されている必要があります。
    このメソッドは指定されたclazzがマネージドビーンを表す場合、リソースインジェクションをサポートします。マネージドビーンとリソースインジェクションについての詳細はJava EEプラットフォームとJSR 299の仕様を参照してください。
    このメソッドは、AsyncListenerに適用可能なアノテーションをすべてサポートします。
    
    型パラメータ:
    
    T - インスタンス化されるオブジェクトのクラス
    
    パラメータ:
    
    clazz - インスタンス化されるAsyncListenerクラス
    
    戻り値:
    
    新しいAsyncListenerのインスタンス
    
    例外:
    
    ServletException - 指定されたclazzのインスタンス化に失敗した場合
  - setTimeout
```
void setTimeout(long timeout)
```
    このAsyncContextのタイムアウト時間を(ミリ秒単位で)設定します。
    タイムアウトはこのAscyncContextがひとたびコンテナが開始したディスパッチがServletRequest.startAsync()メソッドのうちが呼び出されコンテナに返されるまでの間に適用されます。
    complete()メソッドも、いかなるディスパッチメソッドも呼び出されない場合、タイムアウトします。 0以下のタイムアウト値は、タイムアウトがないことを示します。
    setTimeout(long)が呼び出されてない場合、コンテナのデフォルトのタイムアウトとしてgetTimeout()の呼び出しによって使用可能な値が適用されます。
    デフォルト値は30000ミリ秒です。
    
    パラメータ:
    
    timeout - ミリ秒単位のタイムアウト時間
    
    例外:
    
    IllegalStateException - このメソッドがコンテナが開始したディスパッチの後、ServletRequest.startAsync()メソッドのうちの一つが呼び出された後の間、コンテナに返されるまでに呼ばれた場合
  - getTimeout
```
long getTimeout()
```
    このAsyncContextタイムアウト時間を(ミリ秒単位で)取得します。
    このメソッドは、コンテナのデフォルトの非同期操作のタイムアウト値、またはsetTimeout(long)の直近の呼び出しに渡されたタイムアウト値を返します。
    0以下のタイムアウト値はタイムアウトしないことを表します。
    
    戻り値:
    
    ミリ秒単位のタイムアウト時間

Copyright © 1999-2017, Oracle and/or its affiliates. All Rights Reserved. Use is subject to license terms. Portions Copyright © 1999-2002 The Apache Software Foundation. Portions Copyright © 2017- @megascus. Translated by @megascus.

インタフェース 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