7 コールバックによるクライアントへのイベントの通知

この章では、WebLogic Java API for XML-based RPC (JAX-RPC) Webサービスでコールバックを使用してクライアントにイベントを通知する方法について説明します。

この章では、以下のトピックについて説明します。

• コールバックの概要

• コールバックの実装の概要と用語

• コールバックのプログラミング: 主な手順

• ターゲットWebサービスのプログラミングのガイドライン

• コールバック・クライアントWebサービスのプログラミングのガイドライン

• コールバック・インタフェースのプログラミングのガイドライン

• クライアントWebサービスのbuild.xmlファイルの更新

コールバックの概要

コールバックは、なんらかのイベントが発生したことを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を標準の方法で呼び出すメソッドです。

次の図に、メッセージの流れを示します。

図message_flow.gifの説明

1. あるWebLogic Serverインスタンスで動作するCallbackClient WebサービスのclientOperation()メソッドが、TargetServiceのtargetOperation()操作を明示的に呼び出します。TargetServiceサービスは、別のWebLogic Serverインスタンスで動作していてもかまいません。

2. TargetService.targetOperation()メソッドの実装が、コールバック・サービスを実装するCallbackInterfaceのcallbackOperation()操作を明示的に呼び出します。コールバック・サービスは、クライアントWebサービスをホストするWebLogic Serverにデプロイされています。

3. jwscによって生成されたCallbackInterface.callbackOperation()メソッドの実装は、単純にメッセージをCallbackClient Webサービスに返送します。クライアントWebサービスには、このメッセージを処理するcallbackHandler()メソッドが含まれています。

コールバックのプログラミング: 主な手順

この項の手順では、コールバックを実装するために必要な3つのJWSファイル(ターゲットWebサービス、クライアントWebサービス、コールバック・インタフェース)をプログラミングおよびコンパイルする方法について説明します。この手順では、これらのJWSファイルをゼロから作成する方法を示しています。既存のJWSファイルを更新する場合は、この手順をガイドとして利用してください。

Antベースの開発環境を設定済であり、かつjwsc Antタスクを実行してWebサービスをデプロイするためのターゲットを追加できる、作業用のbuild.xmlファイルがあることが前提となっています。詳細は、『Oracle WebLogic Server JAX-RPC Webサービス・スタート・ガイド』を参照してください。

表7-1 コールバックのプログラミング手順

#	手順	説明
1	ターゲットWebサービスを実装する、新しいJWSファイルを作成するか、既存のJWSファイルを更新します。	使い慣れたIDEまたはテキスト・エディタを使用します。「ターゲットWebサービスのプログラミングのガイドライン」を参照してください。 注意: ターゲットWebサービスを実装するJWSファイルは、コールバック・インタフェースの1つ以上のコールバック・メソッドを呼び出します。(コールバック・インタフェースのプログラミング手順については後述の説明を参照してください。)したがって、この手順に従って順番にプログラミングするのではなく、3つのJWSファイルを同時にプログラミングすることをお薦めします。ここでは、各手順を理解しやすくするため、この順番で説明しています。
2	build.xmlファイルを更新して、ターゲットJWSファイルをWebサービスにコンパイルするjwsc Antタスクの呼出しを含めます。	『Oracle WebLogic Server JAX-RPC Webサービス・スタート・ガイド』のjwsc WebLogic WebサービスAntタスクの実行に関する項を参照してください。
3	Antターゲットを実行して、ターゲットWebサービスをビルドします。	例: prompt> ant build-mainService
4	ターゲットWebサービスを通常どおりデプロイします。	『Oracle WebLogic Server JAX-RPC Webサービス・スタート・ガイド』のWebLogic Webサービスのデプロイとアンデプロイに関する項を参照してください。
5	クライアントWebサービスを実装する、新しいJWSファイルを作成するか、既存のJWSファイルを更新します。	クライアントWebサービスは、ターゲットWebサービスをホストするものとは別のWebLogic Serverインスタンスにデプロイされていることが前提となっています。「コールバック・クライアントWebサービスのプログラミングのガイドライン」を参照してください。
6	コールバックWebサービスを実装するコールバックJWSインタフェースを作成します。	「コールバック・インタフェースのプログラミングのガイドライン」を参照してください。
7	クライアントWebサービスをビルドするbuild.xmlファイルを更新します。	クライアントWebサービスをビルドするjwsc Antタスクでは、コールバックWebサービスもコールバック・インタフェース・ファイルから暗黙的に生成されます。「クライアントWebサービスのbuild.xmlファイルの更新」を参照してください。
8	Antターゲットを実行して、クライアントおよびコールバックWebサービスをビルドします。	例: prompt> ant build-clientService
9	クライアントWebサービスを通常どおりデプロイします。	『Oracle WebLogic Server JAX-RPC Webサービス・スタート・ガイド』のWebLogic Webサービスのデプロイとアンデプロイに関する項を参照してください。

ターゲット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")

/**
 * callback service
 */

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);
  

この項で説明したWebLogic固有のJWSアノテーションの詳細は、『Oracle WebLogic Server WebLogic Webサービス・リファレンス』のJWSアノテーション・リファレンスの項を参照してください。

コールバック・クライアントWebサービスのプログラミングのガイドライン

次のサンプルでは、「ターゲット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アノテーションを使用して、この特定のコールバック・メソッドの呼出しを許可するセキュリティ・ロールをさらに制限する方法も示されています。

この項で説明したWebLogic固有のJWSアノテーションの詳細は、『Oracle WebLogic Server WebLogic 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アノテーションが付けられていますが、必ずしもこのように設定する必要はありません。

  
  

この項で説明したWebLogic固有のJWSアノテーションの詳細は、『Oracle WebLogic Server WebLogic Webサービス・リファレンス』のJWSアノテーション・リファレンスの項を参照してください。

クライアントWebサービスのbuild.xmlファイルの更新

クライアント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ファイルにパッケージ化されます。