インターフェース AsyncContext

メソッドの詳細

• 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
   
   

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

  • ServletRequest.startAsync() または ServletRequest.startAsync(ServletRequest, ServletResponse) が呼び出される Servlet.service(ServletRequest, ServletResponse)
  • ReadListener.onDataAvailable()
  • ReadListener.onAllDataRead()
  • WriteListener.onWritePossible()

  このメソッドが呼び出されたときに出力ストリームがノンブロッキングモードである場合、出力ストリームは ServletOutputStream#close に従って閉じられ、進行中のノンブロッキング書き込みが完了するまでディスパッチ操作は遅延されます。

  リクエストのディスパッチャー型は 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) の呼び出し後、このクラスのディスパッチメソッドの 1 つを呼び出す前であれば、いつでもこのメソッドを呼び出すことができます。コンテナーによって開始されたディスパッチ中にこのメソッドが呼び出された場合、その呼び出しは、コンテナーによって開始されたディスパッチがコンテナーに戻るまで有効になりません (必要なリスナー呼び出しを含む)。
  注: コンテナーによって開始されたディスパッチには、次の呼び出しが含まれます。

  • ServletRequest.startAsync() または ServletRequest.startAsync(ServletRequest, ServletResponse) が呼び出される Servlet.service(ServletRequest, ServletResponse)
  • ReadListener.onDataAvailable()
  • ReadListener.onAllDataRead()
  • WriteListener.onWritePossible()

  このメソッドが呼び出されたときに出力ストリームがノンブロッキングモードである場合、出力ストリームは ServletOutputStream#close に従って閉じられ、完了するためのこの呼び出しは、進行中のメソッドが完了するまで有効になりません (そして、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 がマネージド 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) の最新の呼び出しに渡されたタイムアウト値を返します。

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

  戻り値:

  ミリ秒単位のタイムアウト