WebLogic Web サービス プログラマーズ ガイド (応用編)

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

以下の節では、コールバックを使用してクライアントにイベントを通知する方法について説明します。

コールバックの概要

コールバックは、何らかのイベントが発生したことを Web サービスのクライアントに通知するものです。たとえば、クライアントのリクエストの結果が用意されたとき、または、クライアントのリクエストが実行できない場合に、クライアントに通知できます。

メソッドを JWS ファイル内で (@WebMethod アノテーションを使用して) 標準のパブリック オペレーションとしてエクスポーズした場合は、クライアントが Web サービスに SOAP メッセージを送信してオペレーションを呼び出します。一方、Web サービスにコールバックを追加する場合は、Web サービスからクライアント Web サービスに返送するメッセージを定義して、イベントが発生したことをそのメッセージでクライアントに通知します。つまり、メソッドをパブリック オペレーションとしてエクスポーズする方法とコールバックを定義する方法は、送受信の方向が逆になった対照的なプロセスです。

WebLogic Server では、呼び出し側のクライアントからの SOAP メッセージは、対象 Web サービスに自動的にルーティングされます。一方、クライアントがコールバックを受信するためには、クライアントが同じサービスを提供する環境で動作している必要があります。これは、クライアントが Web サーバ上で動作する Web サービスであることが一般的ということを意味します。クライアントがこれらの要件を満たしていない場合、通常は Web サービスからのコールバックを受信することができません。

コールバックに使用されるプロトコルおよびメッセージ形式は、現在の会話を開始したメソッドで使用されているプロトコルおよびメッセージ形式と必ず同じになります。コールバックのプロトコルやメッセージ形式をオーバーライドしようとするとエラーが送出されます。

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

コールバックを実装するには、以下の 3 つの Java ファイルを作成または更新する必要があります。

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

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

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

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

対象 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 ファイルをプログラミングする際には、以下のガイドラインに従います。ガイドラインのサンプル コードは、上述のサンプルでは太字で示されています。

この節で説明した WebLogic 固有の JWS アノテーションの詳細については、「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 ファイルをプログラミングする際には、以下のガイドラインに従います。ガイドラインのサンプル コードは、上述のサンプル内では太字で示されています。

この節で説明した WebLogic 固有の JWS アノテーションの詳細については、「JWS アノテーション リファレンス」を参照してください。

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

コールバック インタフェースも、Web サービスを実装した JWS ファイルです。ただし、大きな違いが 1 つあります。コールバック インタフェースでは、標準の @javax.jws.WebService アノテーションを使用して標準の Web サービスであることを指定する代わりに、WebLogic 固有の @weblogic.jws.CallbackService を使用してコールバック サービスであることを指定します。@CallbackService の属性は、@WebService の属性の限定的なサブセットです。

コールバック サービスを実装する JWS ファイルをプログラミングする場合は、使用できるデータ型および JWS アノテーションについて以下の制約があります。

次のサンプルでは、コールバック 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 インタフェース ファイルをプログラミングする際には、以下のガイドラインに従います。ガイドラインのサンプル コードは、上述のサンプルでは太字で示されています。

この節で説明した WebLogic 固有の JWS アノテーションの詳細については、「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 ファイルにパッケージ化されます。