Oracle® Fusion Middleware Oracle Infrastructure Webサービス・コンセプト・ガイド 11g リリース1(11.1.1) B61390-01 |
|
前 |
次 |
JAX-WS仕様では、同期メソッドの非同期コールを可能にする非同期クライアントAPIを提供しています。この章では、非同期Webサービスの概念の概要を示し、非同期Webサービスを開発および構成する方法について説明します。
Webサービスを同期的に起動した場合、起動側のクライアント・アプリケーションは、レスポンスが戻るのを待機してから処理を続行する必要があります。このようなWebサービスの起動方法は、レスポンスが即時に戻るような場合には適しています。しかし、リクエスト処理が遅延する場合もあるため、クライアント・アプリケーションは先に処理を続行し、後でレスポンスを処理するほうが効率的なことも少なくありません。Webサービスを非同期的にコールすれば、クライアントはその処理を間断なく続行でき、非同期レスポンスが戻されたときに通知を受けることができます。
次の各項で、非同期メッセージ・フローのダイアグラムをいくつか示し、クライアント側から見た全体像を示します。また、非同期メッセージが互いにどのように関連しているかを説明します。
注意: 単一のリクエスト・キューを使用した場合、パフォーマンスは高くなる可能性はありますが、リクエスト・キューとレスポンス・キューを使用した場合よりも信頼性が低くなります。単一のリクエスト・キューを使用するのではなく、「リクエスト・キューおよびレスポンス・キューを使用した非同期Webサービス」で説明されているように、リクエスト・キューとレスポンス・キューを使用することをお薦めします。 |
このシナリオでは、リクエストとレスポンスの両方の処理を実行する単一のメッセージドリブンBean(MDB)がリクエスト・キューに関連付けられています。
次の図は、単一のリクエスト・キューを使用した非同期メソッド・コールのフローを示しています。
前出の図に示されたフローについて次に説明します。
クライアントが非同期メソッドをコールします。
非同期Webサービスがリクエストを受信して、それをリクエスト・キューに格納します。
非同期Webサービスは受信確認をクライアントに送信します。
リクエスト・キューのMDBリスナーがメッセージを受信し、リクエストの処理を開始します。
リクエストMDBは、Webサービス実装の必須メソッドをコールします。
Webサービス実装がレスポンスを返します。
リクエストMDBがコールバック・クライアントとなり、コールバック・サービスにレスポンスを返します。
コールバック・サービスは受信確認メッセージを返します。
リクエストMDBは確認メッセージをリクエスト・キューに返して、プロセスを終了します。
このシナリオでは、コールバック・サービスへの接続(ステップ7)に問題がある場合、レスポンスは送信されません。後でリクエストが再試行される場合は、ステップ4からフローが再開し、再びWebサービス実装がコールされます(ステップ5)。このような動作は、アプリケーション・ロジックやトランザクション制御処理によっては望ましくないことがあります。次のシナリオでは、レスポンスが別のレスポンス・キューに格納されるため、最初にコールバック・サービスが使用可能になっていなくても、Webサービス実装を再びコールする必要がありません。
このシナリオでは、2つのMDBを使用し、それぞれがリクエスト処理とレスポンス処理を行います。このシナリオでは、ビジネス・ロジックの実行をレスポンスの返却と分離することにより、「単一のリクエスト・キューを使用した非同期Webサービス」で説明されている単一キューのモデルよりもエラー・リカバリを向上させています。
次の図は、単一のリクエスト・キューを使用した非同期メソッド・コールのフローを示しています。
前出の図に示されたフローについて次に説明します。
クライアントが非同期メソッドをコールします。
非同期Webサービスがリクエストを受信して、それをリクエスト・キューに格納します。
非同期Webサービスは受信確認をクライアントに送信します。
リクエスト・キューのMDBリスナーがメッセージを受信し、リクエストの処理を開始します。
リクエストMDBは、Webサービス実装の必須メソッドをコールします。
Webサービス実装がレスポンスを返します。
リクエストMDBがレスポンスをレスポンス・キューに保存します。
リクエストMDBはリクエスト・キューに確認を送信して、プロセスを終了します。
レスポンス・キューのonMessageリスナーがレスポンスの処理を開始します。
レスポンスMDBがコールバック・クライアントとなり、コールバック・サービスにレスポンスを返します。
コールバック・サービスは受信確認メッセージを返します。
レスポンスMDBは確認メッセージをレスポンス・キューに返して、シーケンスを終了します。
クライアントから見ると、非同期メソッド・コールは次の図のように2つの一方向メッセージ交換で構成されています。
前出の図に示したように、クライアントは非同期コールを開始する前に、非同期Webサービスからのレスポンスをリスニングするためのコールバック・サービスをデプロイする必要があります。
メッセージのフローは次のとおりです。
クライアントが非同期メソッドをコールします。
非同期Webサービスがリクエストを受信し、開始クライアントに確認メッセージを送信して、リクエストの処理を開始します。
リクエストの処理が完了すると、非同期Webサービスがクライアントとなり、コールバック・サービスにレスポンスを返します。
コールバック・サービスは確認メッセージを非同期Webサービスに送信します。
注意: メッセージ相関はSOAランタイムによって自動的に処理されます。この項の説明は参考情報です。 |
コールバック・サービスはレスポンスの受信時に、レスポンスと元のリクエストを相互に関連付ける必要があります。これは、SOAランタイムによってWS-Addressingを介して自動的に行われます。
クライアントは、SOAPヘッダーのWS-Addressing部分に次の2つのフィールドを設定します。
ReplyToアドレス: コールバック・サービスのアドレス。
MessageID: リクエストを識別する一意のID。たとえば、UUIDなどです。
コールバック・クライアントは、WS-AddressingヘッダーのrelatesToIdフィールド内の初期リクエストに対応するMessageIdを送信します。コールバック・サービスでレスポンス処理に追加データが必要となる場合、クライアントはMessageIDおよび必要なデータをデータ・ストアに保存する必要があります。
ADF Business Componentの非同期Webサービス・メソッドの開発とデプロイは、短時間で簡単に行うことができます。詳細は、Oracle Application Development Frameworkの開発者ガイドの非同期Webサービス・メソッドの生成方法に関する項を参照してください。
次の各項で、非同期Webサービスの実装方法を詳しく説明します。一部は参考情報です。
oracle.webservices.annotations.async.AsyncWebService注釈を使用して、JAX-WS Webサービスを非同期Webサービスとして宣言できます。
次の例は、非同期Webサービスのごく単純なPOJOを示しています。
import oracle.webservices.annotations.PortableWebService import oracle.webservices.annotations.async.AsyncWebService @PortableWebService @AsyncWebService public class HelloService { public String hello(String name) { return “Hi “ + name; } }
非同期Webサービスに対して生成されたWSDLには、2つのportTypeとして定義された2つの一方向操作が含まれています(非同期操作用とコールバック操作用)。
例:
<wsdl:portType name="HelloService"> <wsdl:operation name="hello"> <wsdl:input message="tns:helloInput" xmlns:ns1="http://www.w3.org/2006/05/addressing/wsdl" ns1:Action=""/> </wsdl:operation> </wsdl:portType> <wsdl:portType name="HelloServiceResponse"> <wsdl:operation name="helloResponse"> <wsdl:input message="tns:helloOutput" xmlns:ns1="http://www.w3.org/2006/05/addressing/wsdl" ns1:Action=""/> </wsdl:operation> </wsdl:portType>
非同期Webサービスをデプロイする前に、リクエストおよびレスポンスを格納するためのキューを構成する必要があります。
次の各項で説明するように、このプロセスは、クラスタ・ドメインか非クラスタ・ドメインのどちらを使用しているかによって異なります。
クラスタ・ドメインの場合は、2つのJMS共通分散宛先(UDD)を作成する必要があります。デフォルト・キューをクラスタ環境に追加する際は、オフラインWLSTスクリプトを使用できます。
このスクリプトは次の場所にあります。
<MW_HOME>/oracle_common/webservices/bin/jrfws-async-createUDDs.py
このスクリプトの実行例を次に示します。
java -classpath <some_path>/weblogic.jar weblogic.WLST ./jrfws-async-createUDDs.py -domain_home <domain> -cluster <cluster>
非クラスタ・ドメインの場合、oracle.jrf.ws.async_template_11.1.1.jarというWebLogicドメイン拡張テンプレートの一部として、1組のデフォルトのWebLogic JMSキューが用意されています。この拡張テンプレートに含まれているデフォルトのJMSキューは、次のとおりです。
リクエスト・キュー: oracle.j2ee.ws.server.async.DefaultRequestQueue
レスポンス・キュー: oracle.j2ee.ws.server.async.DefaultResponseQueue
基本ドメインの一部として用意されているデフォルトのJMS接続ファクトリであるweblogic.jms.XAConnectionFactoryが、デフォルトで使用されます。
デフォルトのキューを使用するには、Fusion Middleware構成ウィザードを使用してドメインを作成または拡張するときに、「Oracle JRF Webサービスの非同期サービス」を選択します。詳細は、「構成ウィザードを使用したドメインの作成」を参照してください。
注意: JMSモジュール(JRFWSAsyncJmsModule)にはドメイン内の非クラスタ・サーバーを明示的にターゲットとして指定する必要があります。 |
デフォルトのWebLogic JMSキューが要件を満たしていない場合は、次の手順を実行できます。
Oracle WebLogic ServerのJMSのプログラミングに関する項の説明に従って、リクエスト・キューとレスポンス・キューを手動で構成します。
次の注釈を使用して、これらのキューをアプリケーション・コードに追加します。
リクエスト・キュー: oracle.webservices.annotations.async.AsyncWebServiceQueue
詳細は、「@AsyncWebServiceQueue注釈」を参照してください。
レスポンス・キュー: oracle.webservices.annotations.async.ResponseQueue
詳細は、「@AsyncWebServiceResponseQueue注釈」を参照してください。
リクエスト・キューとレスポンス・キューを構成する(手順1)ためのベスト・プラクティスを次に挙げます。
クラスタ内のキューを高可用性およびフェイルオーバーのために構成します。
WebLogic Serverごとに単一のJMSサーバーとWebLogic永続ストアを構成し、ターゲットとしてサーバーのデフォルトの移行可能ターゲットを指定します。
JMSサーバーに対して必要な割当て制限を構成します。
メモリー不足によるエラーを回避するため、各JMSサーバーに対してメッセージの最大割当て制限を構成することをお薦めします。目安として、各メッセージ・ヘッダーは約512バイトを消費するため、最大割当て制限をメッセージ500,000件にすると、約250MBのメモリーが必要になります。環境で使用可能なメモリー・リソースを考慮して、それに応じた割当て制限を設定してください。
単一のJMSシステム・モジュールを構成し、ターゲットとしてクラスタを指定します。
JMSシステム・モジュールに対して、次の手順を実行します。
単一のサブデプロイメントを構成し、各JMSサーバーを割り当てます。
必要な共通分散宛先を構成し、(前述の)拡張的なサブデプロイメントのターゲット指定を使用してターゲットを定義します。
カスタムの接続ファクトリを構成します。トランザクションが有効になっている場合、接続ファクトリが有効であればトランザクションをサポートする必要があります。WebLogic JMSには、トランザクションをサポートするためのweblogic.jms.XAConnectionFactory
接続ファクトリがデフォルトで用意されています。
次のようにして、JMSキューの配信失敗パラメータを構成します。
「再配信遅延のオーバーライド」の値を900000ミリ秒に設定します。つまり、メッセージ・コンシューマまたは接続ファクトリで指定されている再配信遅延に関係なく、15分間待機した後にロールバックまたはリカバリされたメッセージが再配信されます。
「再配信の制限」の値を100に設定します。この値は、キューに定義されているエラー宛先にメッセージが移されるまでに許可される再配信試行回数を示します。
「有効期限ポリシー」の値を「リダイレクト」に設定します。これにより、期限切れのメッセージは現在の場所からキューに定義されているエラー宛先に移されます。これが有効になっている場合は、対応するエラー宛先が構成されていることを確認してください。
注意: JMS配信失敗パラメータに関連する構成は、WebLogic Server管理コンソールを使用して変更できます(Oracle WebLogic ServerのJMSの構成および管理に関する項を参照)。 |
次の表に定義されている注釈を使用して、コールバック・サービス(portType)の特性をカスタマイズできます。これらの注釈は、oracle.webservices.annotations.asyncパッケージに含まれています。
表4-1 コールバック・サービスの構成に使用される注釈
注釈 | 説明 |
---|---|
@CallbackMethod |
コールバックportType内の対応する操作のWSDLエンティティの名前をカスタマイズし、メソッドが同期か非同期かを設定します。詳細は、「@CallbackMethod注釈」を参照してください。 |
@CallbackProperties |
コールバック・サービスをコールするときにメッセージ・コンテキスト内で必須となるプロパティを指定します。詳細は、「@CallbackProperties注釈」を参照してください。 |
@CallbackProperty |
コールバック・サービスをコールするときにメッセージ・コンテキスト内で必須となる単一のプロパティを指定します。詳細は、「@CallbackProperty注釈」を参照してください。 |
@ResponseWebService |
レスポンスWebサービス・ポート情報をカスタマイズします。詳細は、「@ResponseWebService注釈」を参照してください。 |
次の2種類のクライアントが非同期Webサービスをコールできます。
SOA/BPELクライアント: このプロセスは、他の非同期BPELクライアントをコールするプロセスと同じです。詳細は、『Oracle Fusion Middleware Oracle SOA Suite開発者ガイド』のBPELプロセスからの非同期Webサービスの起動に関する項を参照してください。
WebLogic Java EE(JEE)JAX-WSクライアント: JDeveloperのWebサービス・プロキシの作成ウィザードを使用して、「非同期として生成」オプションを選択すると、非同期プロキシが生成されます。このウィザードを使用してWebサービス・クライアントを作成する方法の詳細は、JDeveloperのオンライン・ヘルプのWebサービス・プロキシの作成に関する項を参照してください。
次の各項で、非同期クライアントおよび生成されるコールバック・サービスの例を示し、実施する必要のある更新について説明します。
注意: 次の各項で説明するステップは、WebLogic JEE JAX-WSクライアントに適用されるものです。SOA/BPELクライアントには適用されません。 |
次の例は、非同期Webサービスをサポートするために生成されるクライアント・コードを示しています。太字で示されているように、クライアント・コードではアウトバウンド・ヘッダー内に2つのフィールドを設定する必要があります。
ReplyToアドレス: コールバック・サービスのアドレス。
MessageID: リクエストを識別する一意のID。たとえば、UUIDなどです。
ほとんどの場合は生成されたクライアント・コードに含まれるメッセージIDのUUIDで間に合いますが、このUUIDを更新することもできます。コールバック・サービスを指し示すようにReplyToアドレスを更新する必要があります。
例4-1 非同期クライアント・コードの更新
package async.jrf; import com.sun.xml.ws.api.addressing.AddressingVersion; import com.sun.xml.ws.api.addressing.WSEndpointReference; import com.sun.xml.ws.developer.WSBindingProvider; import com.sun.xml.ws.message.StringHeader; import java.util.UUID; import javax.xml.ws.WebServiceRef; // !THE CHANGES MADE TO THIS FILE WILL BE DESTROYED IF REGENERATED! // This source file is generated by Oracle tools // Contents may be subject to change // For reporting problems, use the following // Version = Oracle WebServices (11.1.1.0.0, build 090303.0200.48673) public class HelloServicePortClient { @WebServiceRef private static HelloServiceService helloServiceService; private static final AddressingVersion WS_ADDR_VER = AddressingVersion.W3C; public static void main(String [] args) { helloServiceService = new HelloServiceService(); HelloService helloService = helloServiceService.getHelloServicePort(); // Get the request context to set the outgoing addressing properties WSBindingProvider wsbp = (WSBindingProvider)helloService; WSEndpointReference repl new WSEndpointReference( "http://<replace with the URL of the callback service>", WS_ADDR_VER); String uuid = "uuid:" + UUID.randomUUID(); wsbp.setOutboundHeaders( new StringHeader(WS_ADDR_VER.messageIDTag, uuid), replyTo.createHeader(WS_ADDR_VER.replyToTag)); // Add your code to call the desired methods. } }
次の例は、コールバック・サービス・コードを示しています。太字で示されたコードは、クライアントからMessageIDとして送信されたメッセージ・ヘッダーからrelatesToIDを抽出する方法を示しています。
レスポンスを処理してコールバック・サービスをWebサービスとしてデプロイするためのコードを実装する必要があります。デプロイした後は、コールバック・サービスのURLをreplyToフィールドとしてクライアント・コードに追加します。
package async.jrf; import com.sun.xml.ws.api.addressing.AddressingVersion; import com.sun.xml.ws.api.message.Header; import com.sun.xml.ws.api.message.HeaderList; import com.sun.xml.ws.developer.JAXWSProperties; import javax.annotation.Resource; import javax.jws.Oneway; import javax.jws.WebMethod; import javax.jws.WebParam; import javax.jws.WebService; import javax.jws.soap.SOAPBinding; import javax.jws.soap.SOAPBinding.Style; import javax.xml.bind.annotation.XmlSeeAlso; import javax.xml.ws.Action; import javax.xml.ws.RequestWrapper; import javax.xml.ws.WebServiceContext; import javax.xml.ws.soap.Addressing; // !THE CHANGES MADE TO THIS FILE WILL BE DESTROYED IF REGENERATED! // This source file is generated by Oracle tools // Contents may be subject to change // For reporting problems, use the following // Version = Oracle WebServices (11.1.1.0.0, build 090303.0200.48673) @WebService(targetNamespace="http://jrf.async/", name="HelloServiceResponse") @XmlSeeAlso( { async.jrf.ObjectFactory.class }) @SOAPBinding(style=Style.DOCUMENT) @Addressing(enabled=true, required=true) public class HelloServiceResponseImpl { @Resource private WebServiceContext wsContext; private static final AddressingVersion WS_ADDR_VER = AddressingVersion.W3C; @WebMethod @Action(input="") @RequestWrapper(localName="helloResponse",targetNamespace="http://jrf.async/", className="async.jrf.HelloResponse") @Oneway public void helloResponse(@WebParam(targetNamespace="", name="return") String _return) { // Use the sample code to extract the relatesTo id for correlation and then add your rest of the logic System.out.println("Received the asynchronous reply"); // get the messageId to correlate this reply with the original request HeaderList headerList = (HeaderList)wsContext.getMessageContext().get(JAXWSProperties.INBOUND_HEADER_LIST_PROPERTY); Header realtesToheader = headerList.get(WS_ADDR_VER.relatesToTag, true); String relatesToMessageId = realtesToheader.getStringContent(); System.out.println("RelatesTo message id: " + relatesToMessageId); // Add your implementation here. } }
ポリシーは次の非同期コンポーネントにアタッチできます。
非同期Webサービスをコールするクライアント(「非同期Webサービス・クライアントへのポリシーのアタッチ」を参照)。
非同期Webサービス(「非同期Webサービスおよびコールバック・サービスへのポリシーのアタッチ」を参照)。
非同期コールバック・クライアント(「コールバック・クライアントへのポリシーのアタッチ」を参照)。
非同期コールバック・サービス(「非同期Webサービスおよびコールバック・サービスへのポリシーのアタッチ」を参照)。
非同期Webサービスとクライアント・ポリシーは互いに適合している必要があります。同様に、非同期コールバック・クライアントとコールバック・サービス・ポリシーも互いに適合している必要があります。
ポリシーをコンポーネントにアタッチするには、次のいずれかの方法を使用できます。
設計時に注釈を使用。
実行時にEnterprise Managerを使用。
次の各項で、それぞれの方法について詳しく説明します。
注意: oracle/wsaddr_policy を再び非同期Webサービスまたはクライアントにアタッチする必要はありません。oracle/wsaddr_policy ポリシーはデフォルトですべての非同期Webサービスおよびクライアントにアタッチされ、WSDLで通知されます。これは、非同期Webサービスの処理で必要となるためです。しかし、Enterprise Manager Fusion Middleware Controlにはポリシーがアタッチされていることは反映されないため、ポリシーをアタッチする際の使用可能なポリシー・リストではこのポリシーが選択可能になっています(Web Servicesのセキュリティおよび管理者ガイドのWebサービスへのポリシーのアタッチに関する項を参照)。 |
設計時には、次の方法を使用してポリシーをアタッチできます。
SOA/BPELクライアントの場合、SOAコンポジット・エディタを使用してポリシーをアタッチできます(『Oracle Fusion Middleware Oracle SOA Suite開発者ガイド』のポリシーの管理に関する項を参照)。
WebLogic Java EE JAX-WSクライアントの場合、JDeveloperでWebサービス・プロキシの作成ウィザードを使用してポリシーをアタッチできます。このウィザードを使用してWebサービス・クライアントを作成する方法の詳細は、JDeveloperのオンライン・ヘルプのWebサービス・プロキシの作成に関する項を参照してください。
実行時には、Enterprise Managerを使用してポリシーを各クライアント・タイプにアタッチできます(Web Servicesのセキュリティおよび管理者ガイドのWebサービス・クライアントへのポリシーのアタッチに関する項を参照)。
設計時には、ポリシーを非同期Webサービスおよびコールバック・サービスにアタッチするために、表4-2に定義されているいずれかの注釈を使用できます。これらの注釈は、oracle.webservices.annotationsパッケージに含まれています。
表4-2 ポリシーをWebサービスにアタッチするための注釈
注釈 | 説明 |
---|---|
@AddressingPolicy |
WS-AddressingポリシーをWebサービスにアタッチします。詳細は、「@AddressingPolicy注釈」を参照してください。 |
@ManagementPolicy |
管理ポリシーをWebサービスにアタッチします。詳細は、「@ManagementPolicy注釈」を参照してください。 |
@MtomPolicy |
MTOMポリシーをWebサービスにアタッチします。詳細は、「@MtomPolicy注釈」を参照してください。 |
@ReliabilityPolicy |
信頼性のあるメッセージング・ポリシーをWebサービスにアタッチします。詳細は、「@ReliabilityPolicy注釈」を参照してください。 |
@SecurityPolicies |
@SecurityPolicy注釈の配列を指定します。複数のWS-Policyファイルをクラスにアタッチする場合は、この注釈を使用します。詳細は、「@SecurityPolicies注釈」を参照してください。 |
@SecurityPolicy |
セキュリティ・ポリシーをWebサービスにアタッチします。詳細は、「@SecurityPolicy注釈」を参照してください。 |
実行時には、Enterprise Managerを使用してポリシーを非同期Webサービスおよびコールバック・サービスにアタッチできます(Web Servicesのセキュリティおよび管理者ガイドのWebサービス・クライアントへのポリシーのアタッチに関する項を参照)。
メッセージ保護ポリシーを非同期Webサービスおよびコールバック・サービスにアタッチする際には、次のガイドラインを使用してください。
コールバック・サービスにメッセージ保護ポリシーを適用する場合は、非同期リクエストにもそのメッセージ保護ポリシーを適用する必要があります。そうしない場合、非同期クライアントの公開暗号化証明書が見つからないことを示すエラーが実行時に返されます。
非同期リクエストにメッセージ保護ポリシーを適用する場合は、コールバック・サービスに同じポリシーを適用する必要はありません。
非同期Webサービスにメッセージ保護ポリシーを適用する場合は、クライアント・キーストア内のクライアント公開暗号化証明書を構成する必要があります。
注意: コールバック・クライアントにアタッチしたポリシーは、非同期WebサービスWSDLで通知されます。 |
設計時には、ポリシーを非同期コールバック・クライアントにアタッチするために、表4-3に定義されている注釈のいずれかを使用できます。これらの注釈は、oracle.webservices.annotations.asyncパッケージに含まれています。
表4-3 ポリシーをコールバック・クライアントにアタッチするための注釈
注釈 | 説明 |
---|---|
@CallbackManagementPolicy |
管理ポリシーを、コールバック・サービスに接続される非同期Webサービスのコールバック・クライアントにアタッチします。デフォルトではいずれの管理ポリシーもアタッチされません。詳細は、「@CallbackManagementPolicy注釈」を参照してください。 |
@CallbackMtomPolicy |
MTOMポリシーを、コールバック・サービスに接続される非同期Webサービスのコールバック・クライアントにアタッチします。デフォルトではいずれのMTOMポリシーもアタッチされません。詳細は、「@CallbackMtomPolicy注釈」を参照してください。 |
@CallbackSecurityPolicy |
1つ以上のセキュリティ・ポリシーを、コールバック・サービスに接続される非同期Webサービスのコールバック・クライアントにアタッチします。デフォルトではいずれのセキュリティ・ポリシーもアタッチされません。詳細は、「@CallbackSecurityPolicy注釈」を参照してください。 |
実行時には、Enterprise Managerを使用してポリシーを非同期コールバック・クライアントにアタッチできます(Web Servicesのセキュリティおよび管理者ガイドのWebサービス・クライアントへのポリシーのアタッチに関する項を参照)。