Oracle® Fusion Middleware Oracle WebLogic Server JAX-RPC を使用した Web サービスの高度な機能のプログラミング 11g リリース 1 (10.3.1) B55544-01 |
|
戻る |
次へ |
以下の節では、コールバックを使用してクライアントにイベントを通知する方法について説明します。
コールバックは、何らかのイベントが発生したことを Web サービスのクライアントに通知するものです。たとえば、クライアントのリクエストの結果が用意されたとき、または、クライアントのリクエストが実行できない場合に、クライアントに通知できます。
メソッドを JWS ファイル内で (@WebMethod
アノテーションを使用して) 標準のパブリック オペレーションとしてエクスポーズした場合は、クライアントが Web サービスに SOAP メッセージを送信してオペレーションを呼び出します。一方、Web サービスにコールバックを追加する場合は、Web サービスからクライアント Web サービスに返送するメッセージを定義して、イベントが発生したことをそのメッセージでクライアントに通知します。つまり、メソッドをパブリック オペレーションとしてエクスポーズする方法とコールバックを定義する方法は、送受信の方向が逆になった対照的なプロセスです。
WebLogic Server では、呼び出し側のクライアントからの SOAP メッセージは、対象 Web サービスに自動的にルーティングされます。一方、クライアントがコールバックを受信するためには、クライアントが同じサービスを提供する環境で動作している必要があります。これは、クライアントが Web サーバ上で動作する Web サービスであることが一般的ということを意味します。クライアントがこれらの要件を満たしていない場合、通常は Web サービスからのコールバックを受信することができません。
コールバックに使用されるプロトコルおよびメッセージ形式は、現在の会話を開始したメソッドで使用されているプロトコルおよびメッセージ形式と必ず同じになります。コールバックのプロトコルやメッセージ形式をオーバーライドしようとするとエラーが送出されます。
コールバックを実装するには、以下の 3 つの Java ファイルを作成または更新する必要があります。
コールバック インタフェース : コールバック メソッドを定義する Java インタフェース ファイル。このファイルは、明示的に実装するのではなく、jwsc
Ant タスクによってこのインタフェースの実装が自動的に生成されます。この実装によって、対象 Web サービスからクライアント Web サービスにメッセージが返送されます。生成された Web サービスは、クライアント Web サービスをホストする同じ WebLogic Server にデプロイされます。
この節で示す例では、コールバック インタフェースの名前を CallbackInterface
としています。このインタフェースには、単一のコールバック メソッド、callbackOperation()
が定義されています。
対象 Web サービスを実装する JWS ファイル : 対象 Web サービスには、コールバック インタフェースで定義されたメソッドを呼び出す 1 つまたは複数の標準オペレーションが含まれます。このメソッドによって、対象 Web サービス オペレーションの呼び出し元のクライアント Web サービスにメッセージが返送されます。
例では、この Web サービスの名前が TargetService
になっており、単一の標準メソッド targetOperation()
が定義されています。
クライアント Web サービスを実装する JWS ファイル : クライアント Web サービスは、対象 Web サービスのオペレーションを呼び出します。この Web サービスには、コールバック メソッドを介して対象 Web サービスからコールバック メッセージを受け取ったときに、クライアントが実行すべき動作を指定する 1 つまたは複数のメソッドが含まれます。
例では、この Web サービスの名前が CallbackClient
になっています。この Web サービスは、コールバックを受信すると、callbackHandler()
というメソッドを自動的に呼び出します。clientOperation()
は、TargetService
を標準の方法で呼び出すメソッドです。
次の図に、メッセージの流れを示します。
ある WebLogic Server インスタンスで動作する CallbackClient
Web サービスの clientOperation()
メソッドが、TargetService
の targetOperation()
オペレーションを明示的に呼び出します。TargetService
サービスは、別の WebLogic Server インスタンスで動作していても構いません。
TargetService.targetOperation()
メソッドの実装が、コールバック サービスを実装する CallbackInterface
の callbackOperation()
オペレーションを明示的に呼び出します。コールバック サービスは、クライアント Web サービスをホストする WebLogic Server にデプロイされています。
jwsc
によって生成された CallbackInterface.callbackOperation()
メソッドの実装は、単純にメッセージを CallbackClient
Web サービスに返送します。クライアント Web サービスには、このメッセージを処理する callbackHandler()
メソッドが含まれています。
この節では、コールバックを実装するために必要な 3 つの JWS ファイル (対象 Web サービス、クライアント Web サービス、コールバック インタフェース) をプログラミングおよびコンパイルする方法について説明します。この手順では、これらの JWS ファイルをゼロから作成する方法を示しています。既存の JWS ファイルを更新する場合は、この手順をガイドとして利用してください。
Ant ベースの開発環境を設定済みであり、かつ jwsc
Ant タスクを実行して、Web サービスをデプロイするためのターゲットを追加できる、作業用の build.xml
ファイルがあることが前提となっています。詳細については、『Oracle Fusion Middleware Oracle WebLogic Server JAX-RPC を使用した Web サービス入門』を参照してください。
表 7-1 コールバックのプログラミング手順
# |
手順 | 説明 |
---|---|---|
1 |
対象 Web サービスを実装する、新しい JWS ファイルを作成するか、既存の JWS ファイルを更新する。 |
使い慣れた IDE またはテキスト エディタを使用する。「対象 Web サービスのプログラミングのガイドライン」を参照。 注意 : 対象 Web サービスを実装する JWS ファイルは、コールバック インタフェースの 1 つまたは複数のコールバック メソッドを呼び出します。(コールバック インタフェースのプログラミング手順については後述の説明を参照)。したがって、この手順に従って順番にプログラミングするのではなく、通常は 3 つの JWS ファイルを同時にプログラミングすることが推奨される。ここでは、各手順を理解しやすくするため、この順番で説明している。 |
2 |
対象の JWS ファイルを Web サービスにコンパイルする、 |
『Oracle Fusion Middleware Oracle WebLogic Server JAX-RPC を使用した Web サービス入門』の「jwsc WebLogic Web サービス Ant タスクの実行」を参照。 |
3 |
Ant ターゲットを実行して、対象 Web サービスをビルドする。 |
例 : prompt> ant build-mainService |
4 |
通常のように、対象 Web サービスをデプロイする。 |
『Oracle Fusion Middleware Oracle WebLogic Server JAX-RPC を使用した Web サービス入門』の「WebLogic Web サービスのデプロイとアンデプロイ」を参照。 |
5 |
クライアント Web サービスを実装する、新しい JWS ファイルを作成するか、既存の JWS ファイルを更新する。 |
クライアント Web サービスは、対象 Web サービスをホストするものとは別の WebLogic Server インスタンスにデプロイされていることが前提となっている。「コールバック クライアント Web サービスのプログラミングのガイドライン」を参照。 |
6 |
コールバック Web サービスを実装するコールバック JWS インタフェースを作成する。 |
|
7 |
クライアント Web サービスをビルドする |
クライアント Web サービスをビルドする |
8 |
Ant ターゲットを実行して、クライアントおよびコールバック Web サービスをビルドする。 |
例 : prompt> ant build-clientService |
9 |
通常のように、クライアント Web サービスをデプロイする。 |
『Oracle Fusion Middleware Oracle WebLogic Server JAX-RPC を使用した Web サービス入門』の「WebLogic Web サービスのデプロイとアンデプロイ」を参照。 |
次のサンプルでは、対象 Web サービスを実装する簡単な JWS ファイルを示します。太字で示された Java コードに対応するコーディングのガイドラインについては、サンプルの後の説明を参照してください。
package examples.webservices.callback; import weblogic.jws.WLHttpTransport; import weblogic.jws.Callback; import javax.jws.WebService; import javax.jws.WebMethod; @WebService(name="CallbackPortType", serviceName="TargetService", targetNamespace="http://examples.org/") @WLHttpTransport(contextPath="callback", serviceUri="TargetService", portName="TargetServicePort") /** * コールバック サービス */ public class TargetServiceImpl { @Callback CallbackInterface callback; @WebMethod public void targetOperation (String message) { callback.callbackOperation (message); } }
対象 Web サービスを実装する JWS ファイルをプログラミングする際には、以下のガイドラインに従います。ガイドラインのサンプル コードは、上述のサンプルでは太字で示されています。
必要な JWS アノテーションをインポートします。
import weblogic.jws.Callback;
@weblogic.jws.Callback
JWS アノテーションを使用して、変数がコールバックであることを指定します。つまり、アノテーション付き変数を使用して、TargetService
Web サービスのオペレーションを呼び出したクライアント Web サービスにコールバック イベントを返送できます。この変数のデータ型はコールバック インタフェース (この場合は CallbackInterface
) です。
@Callback CallbackInterface callback;
TargetService
のオペレーションを実装するメソッドでは、アノテーション付き変数を使用してコールバック インタフェースのコールバック メソッドの 1 つ (この場合は callbackOperation()
) を呼び出す。
callback.callbackOperation (message);
この節で説明した JWS アノテーションの詳細については、『Oracle Fusion Middleware Oracle WebLogic Server Web サービス リファレンス』の「JWS アノテーション リファレンス」を参照してください。
次のサンプルでは、「対象 Web サービスのプログラミングのガイドライン」で説明した対象 Web サービスを呼び出すクライアント Web サービス用の簡単な JWS ファイルを示します。太字で示された Java コードに対応するコーディングのガイドラインについては、サンプルの後の説明を参照してください。
package examples.webservices.callback; import weblogic.jws.WLHttpTransport; import weblogic.jws.ServiceClient; import weblogic.jws.CallbackMethod; import weblogic.jws.security.CallbackRolesAllowed; import weblogic.jws.security.SecurityRole; import javax.jws.WebService; import javax.jws.WebMethod; import examples.webservices.callback.CallbackPortType; import java.rmi.RemoteException; @WebService(name="CallbackClientPortType", serviceName="CallbackClientService", targetNamespace="http://examples.org/") @WLHttpTransport(contextPath="callbackClient", serviceUri="CallbackClient", portName="CallbackClientPort") public class CallbackClientImpl { @ServiceClient( wsdlLocation="http://localhost:7001/callback/TargetService?WSDL", serviceName="TargetService", portName="TargetServicePort") @CallbackRolesAllowed(@SecurityRole(role="mgr", mapToPrincipals="joe")) private CallbackPortType port; @WebMethod public void clientOperation (String message) { try { port.targetOperation(message); } catch (RemoteException e) { e.printStackTrace(); } } @CallbackMethod(target="port", operation="callbackOperation") @CallbackRolesAllowed(@SecurityRole(role="engineer", mapToPrincipals="shackell")) public void callbackHandler(String msg) { System.out.println (msg); } }
対象 Web サービスを呼び出す JWS ファイルをプログラミングする際には、以下のガイドラインに従います。ガイドラインのサンプル コードは、上述のサンプル内では太字で示されています。
必要な JWS アノテーションをインポートする。
import weblogic.jws.ServiceClient; import weblogic.jws.CallbackMethod;
コールバック メソッドの呼び出しを許可するロールを指定したい場合は、必要に応じてセキュリティ関連のアノテーションをインポートする。
import weblogic.jws.security.CallbackRolesAllowed; import weblogic.jws.security.SecurityRole;
呼び出したい対象 Web サービスのポート タイプの JAX-RPC スタブをインポートする。実際のスタブそのものは、後で jwsc
Ant タスクによって作成されます。スタブ パッケージは、<jws>
の子要素 <clientgen>
の packageName
属性によって指定され、スタブの名前は呼び出された Web サービスの WSDL によって決まります。
import examples.webservices.callback.CallbackPortType;
JWS ファイルの本文で、@ServiceClient
JWS アノテーションを使用して、呼び出したい対象 Web サービスの WSDL、名前、およびポートを指定する。このアノテーションは、プライベート変数のフィールド レベルで指定します。この変数のデータ型は、呼び出している Web サービスの JAX-RPC ポート タイプとなります。
@ServiceClient( wsdlLocation="http://localhost:7001/callback/TargetService?WSDL", serviceName="TargetService", portName="TargetServicePort") @CallbackRolesAllowed(@SecurityRole(role="mgr", mapToPrincipals="joe")) private CallbackPortType port;
このコードでは、省略可能な @CallbackRolesAllowed
アノテーションを使用して、コールバック メソッドの呼び出しを許可する @SecurityRoles
のリストを指定する方法も示されています。
@ServiceClient
アノテーションを付けた変数を使用して、対象 Web サービスのオペレーションを呼び出す。このオペレーションによって、コールバック インタフェースのコールバック メソッドが呼び出されます。
port.targetOperation(message);
コールバック サービスから受信したコールバック メッセージを処理するメソッドを作成する。このメソッドには自由に名前を付けることができます。ただし、そのシグネチャは、コールバック インタフェース内の対応するメソッドのシグネチャと完全に一致させる必要があります。
メソッドに @CallbackMethod
アノテーションを付けて、このメソッドでコールバック メッセージを処理することを指定します。target
属性を使用すると、コールバックを受信する JAX-RPC ポートの名前 (つまり、前の手順で @ServiceClient
アノテーションを付けた変数) を指定できます。operation
属性を使用すると、このメソッドで処理するコールバック メッセージを送信するコールバック インタフェース内のコールバック メソッドの名前を指定できます。
@CallbackMethod(target="port", operation="callbackOperation") @CallbackRolesAllowed(@SecurityRole(role="engineer", mapToPrincipals="shackell")) public void callbackHandler(String msg) { System.out.println (msg); }
このコードでは、省略可能な @CallbackRolesAllowed
アノテーションを使用して、この特定のコールバック メソッドの呼び出しを許可するセキュリティ ロールをさらに制限する方法も示されています。
この節で説明した JWS アノテーションの詳細については、『Oracle Fusion Middleware Oracle WebLogic Server Web サービス リファレンス』の「JWS アノテーション リファレンス」を参照してください。
コールバック インタフェースも、Web サービスを実装した JWS ファイルです。ただし、大きな違いが 1 つあります。コールバック インタフェースでは、標準の @javax.jws.WebService
アノテーションを使用して標準の Web サービスであることを指定する代わりに、WebLogic 固有の @weblogic.jws.CallbackService
を使用してコールバック サービスであることを指定します。@CallbackService
の属性は、@WebService
の属性の限定的なサブセットです。
コールバック サービスを実装する JWS ファイルをプログラミングする場合は、使用できるデータ型および JWS アノテーションについて以下の制約があります。
@weblogic.jws.CallbackService
以外の WebLogic 固有の JWS アノテーションを使用することはできない。
以下を除くすべての標準 JWS アノテーションを使用できる。
javax.jws.HandlerChain
javax.jws.soap.SOAPMessageHandler
javax.jws.soap.SOAPMessageHandlers
Holder
クラス (javax.xml.rpc.holders.Holder
インタフェースを実装するユーザ定義のデータ型) を除き、サポートされているすべてのデータ型をパラメータまたは戻り値として使用できる。
次のサンプルでは、コールバック Web サービスを実装する簡単なコールバック インタフェース ファイルを示します。まず、「対象 Web サービスのプログラミングのガイドライン」で説明した対象 Web サービスが、このインタフェースのメソッドを明示的に呼び出します。次に、jwsc
によって生成されたコールバック インタフェースの実装が、対象 Web サービスの呼び出し元のクライアント Web サービスにメッセージを自動的に返送します。クライアント Web サービスについては「コールバック クライアント Web サービスのプログラミングのガイドライン」を参照してください。太字で示された Java コードに対応するコーディングのガイドラインについては、サンプルの後の説明を参照してください。
package examples.webservices.callback; import weblogic.jws.CallbackService; import javax.jws.Oneway; import javax.jws.WebMethod; @CallbackService public interface CallbackInterface { @WebMethod @Oneway public void callbackOperation (String msg); }
コールバック Web サービスを実装する JWS インタフェース ファイルをプログラミングする際には、以下のガイドラインに従います。ガイドラインのサンプル コードは、上述のサンプルでは太字で示されています。
必要な JWS アノテーションをインポートする。
import weblogic.jws.CallbackService;
インタフェース宣言に @CallbackService
アノテーションを付けて、JWS ファイルがコールバック サービスを実装することを指定する。
@CallbackService public interface CallbackInterface {
対象 Web サービスが明示的に呼び出すメソッドを作成する。このメソッドは、対象 Web サービスの呼び出し元のクライアント サービスにメッセージを自動的に返送するメソッドです。このメソッドの実装は、Java インタフェース ファイルであるこのファイルでは提供しません。WebLogic Web サービス ランタイムによって、jwsc
Ant タスクで生成されます。
public void callbackOperation (String msg);
注意 : このサンプルのコールバック メソッドは、void を返し、@Oneway アノテーションが付けられていますが、必ずしもこのように設定する必要はありません。 |
この節で説明した JWS アノテーションの詳細については、『Oracle Fusion Middleware Oracle WebLogic Server Web サービス リファレンス』の「JWS アノテーション リファレンス」を参照してください。
クライアント Web サービスを実装する JWS ファイルに対して jwsc
Ant タスクを実行すると、以下で説明するように、コールバック Web サービスも暗黙的に生成されます。
build.xml
ファイルを更新して、対象 Web サービスを呼び出すクライアント Web サービスを生成するには、次のサンプルのような taskdefs
および build-clientService
ターゲットを追加します。詳細については、サンプルの後の説明を参照してください。
<taskdef name="jwsc" classname="weblogic.wsee.tools.anttasks.JwscTask" /> <target name="build-clientService"> <jwsc srcdir="src" destdir="${clientService-ear-dir}" > <jws file="examples/webservices/callback/CallbackClientImpl.java" > <clientgen wsdl="http://${wls.hostname}:${wls.port}/callback/TargetService?WSDL" packageName="examples.webservices.callback" serviceName="TargetService" /> </jws> </jwsc> </target>
jwsc
Ant タスクの完全なクラス名を定義するには、taskdef
Ant タスクを使用します。
クライアント Web サービスをコンパイルする jwsc
Ant タスクを更新して、<jws>
要素の <clientgen>
子要素を含めます。これにより、デプロイされた TargetService
Web サービスの JAX-RPC スタブが生成およびコンパイルされるようになります。jwsc
Ant タスクでは、これらのスタブが生成された WAR ファイルに自動的にパッケージ化されるため、即座にクライアント Web サービスからアクセスできるようになります。このようにするのは、生成されたクラスの 1 つを CallbackClientImpl
JWS ファイルでインポートして使用するためです。
対象 Web サービスの WSDL には、対象 Web サービスから呼び出されるコールバック Web サービスを表す追加の <service>
要素が含まれています。このため、jwsc
Ant タスクの <clientgen>
子要素によってコールバック Web サービスも生成およびコンパイルされ、クライアント Web サービスと同じ EAR ファイルにパッケージ化されます。