2.16. RESTEasy Asynchronous Job Service
RESTEasy Asynchronous Job Service は、HTTP プロトコルに非同期動作を追加するように設計されています。HTTP は同期プロトコルですが、非同期呼び出しを認識します。HTTP 1.1 202 accepted
は、サーバーが処理応答を受信し、承認したものの、処理が完了していないことを示します。Asynchronous Job Service はこれに基づいてビルドされます。
2.16.1. 非同期ジョブサービスの有効化
Asynchronous Job Service は web.xml
ファイルで有効化します。
<context-param> <param-name>resteasy.async.job.service.enabled</param-name> <param-value>true</param-value> </context-param>
2.16.2. 非同期ジョブの設定
このセクションでは、RESTEasy を使用した非同期ジョブのクエリーパラメーターの例について説明します。
ロールベースのセキュリティーは、ポータブルに実装できないため Asynchronous Job Service とは連携しません。Asynchronous Job Service を使用する場合は、代わりに web.xml
ファイルでの XML 宣言を使用してアプリケーションセキュリティーを確立する必要があります。
GET、DELETE、および PUT メソッドは非同期的に呼び出すことができますが、これらのメソッドの HTTP 1.1 コントラクトが破損します。これらの呼び出しによってリソースが複数回呼び出されると、その状態が変更されることはありませんが、各呼び出しで新しいジョブエントリーとしてサーバーの状態が変更されます。
asynch
クエリーパラメーターは、バックグラウンドで呼び出しを実行するために使用されます。202 Accepted
応答が返されます。また、バックグラウンドメソッドの応答がある場所を指す URL が含まれる場所のヘッダーも返されます。
POST http://example.com/myservice?asynch=true
上記の例では、202 Accepted
応答を返します 。また、バックグラウンドメソッドの応答がある場所を指す URL のある場所のヘッダーも返します。以下は場所ヘッダーの例です。
HTTP/1.1 202 Accepted Location: http://example.com/asynch/jobs/3332334
URI は以下の形式になります。
/asynch/jobs/{job-id}?wait={milliseconds}|nowait=true
この URL では、GET、POST、および DELETE 操作を実行できます。
-
ジョブが完了したら、GET は応答として呼び出される JAX-RS リソースメソッドを返します。ジョブが完了していない場合、GET は
202 Accepted
応答コードを返します。GET を呼び出してもジョブは削除されないため、複数回呼び出すことができます。 - POST はジョブの応答を読み取り、完了するとジョブを削除します。
- DELETE は、ジョブキューを手動でクリーンアップするために呼び出されます。
ジョブキューが満杯になると、DELETE を呼び出すことなく、メモリーから最も古いジョブを自動的に無効にします。
GET および POST 操作では、wait
および nowait
クエリーパラメーターを使用して、最大待機時間を定義できます。wait
パラメーターが指定されていない場合、操作はデフォルトで nowait=true
に設定され、ジョブが完了しない場合には待機しません。wait
パラメーターはミリ秒単位で定義されます。
POST http://example.com/asynch/jobs/122?wait=3000
RESTEasy は、一方向のクエリーパラメーターを使用して oneway
ジョブの発生と無効化をサポートします。
POST http://example.com/myservice?oneway=true
上記の例では 202 Accepted
応答が返されますが、ジョブは作成されません。
Asynchronous Job Service の設定パラメーターは、付録の RESTEasy Asynchronous Job Service Configuration Parameters のセクションを参照してください。