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

Web サービスの信頼性のあるメッセージングの使用

以下の節では、Web サービスの信頼性のあるメッセージングの使用方法について説明します。

Web サービスの信頼性のあるメッセージングの概要

Web サービスの信頼性のあるメッセージングとは、ある 1 つのアプリケーション サーバで実行中のアプリケーションが、別のアプリケーション サーバで実行中の Web サービスを確実に呼び出せるフレームワークです。ここでは、双方のサーバで WS-ReliableMessaging 仕様が実装されていることが前提となっています。信頼性のある、とは 2 つの Web サービス間でのメッセージの配信を保証できるということです。

WebLogic Web サービスは、WS-ReliableMessaging 仕様 (2005 年 2 月) に準拠しています。これは、別々のアプリケーション サーバで実行されている 2 つの Web サービスが、ソフトウェア コンポーネント、システム、またはネットワークに障害が発生していても、確実に通信できる方法について記述したものです。具体的には、この仕様ではソース エンドポイント (つまりクライアント Web サービス) から送り先エンドポイント (つまりオペレーションを確実に呼び出せる Web サービス) へ送信されるメッセージが、1 つまたは複数の配信保証に基づいて確実に配信されるか、そうでなければ必ずエラーが送出される、相互運用性を備えたプロトコルについて説明しています。

信頼性のある WebLogic Web サービスには、以下の配信保証が備わっています。

Web サービスの信頼性のあるメッセージングのアーキテクチャの詳細については、 WS-ReliableMessaging 仕様を参照してください。「Web サービスの信頼性のあるメッセージングの使用 : 主な手順」では、信頼性のある Web サービスおよびクライアント Web サービスを作成する方法と、それらの Web サービスがデプロイされる 2 つの WebLogic Server インスタンスをコンフィグレーションする方法について説明します。

Web サービスの信頼性のあるメッセージングをコンフィグレーションするための WS-Policy ファイルの使用

WebLogic Web サービスでは、送り先エンドポイントが Web サービスの信頼性のあるメッセージングの機能と要件を記述および公開できるようにする、WS-Policy ファイルを使用します。WS-Policy 仕様では、Web サービスのポリシーを記述して通信するための、汎用的なモデルと構文が提供されています。

これらの WS-Policy ファイルは、サポートされている WS-ReliableMessaging 仕様のバージョン、ソース エンドポイントの再送信間隔、送り先エンドポイントの確認応答間隔などの特徴が記述された、XML ファイルです。

Web サービスに追加された WS-Policy ファイルの名前は、JWS ファイル内の @Policy JWS アノテーションを使用して指定します。複数の @Policy アノテーションをグループ化するには、@Policies アノテーションを使用します。信頼性のあるメッセージングを行うには、これらのアノテーションを、クラス レベルでのみ使用します。

WebLogic Server では、ユーザ独自の WS-Policy ファイルを作成しない場合に JWS ファイルで指定できる、2 つの単純な WS-Policy ファイルが用意されています。

あらかじめパッケージ化されているこれらのファイルは変更することができません。したがって、ファイル内の値がニーズに合わない場合は、独自の WS-Policy ファイルを作成する必要があります。

WebLogic Server 付属のものを使用しない場合の、独自の WS-Policy ファイル作成の詳細については、「Web サービスの信頼性のあるメッセージングの WS-Policy ファイルの作成」を参照してください。信頼性のあるメッセージングのポリシーのアサーションに関するリファレンス情報については、「Web サービスの信頼性のあるメッセージングのポリシー アサーションに関するリファレンス」を参照してください。

DefaultReliability.xml WS-Policy ファイル

<?xml version="1.0"?>

<wsp:Policy
   xmlns:wsrm="http://schemas.xmlsoap.org/ws/2005/02/rm/policy"
   xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
   xmlns:beapolicy="http://www.bea.com/wsrm/policy"
  >

  <wsrm:RMAssertion >

    <wsrm:InactivityTimeout
        Milliseconds="600000" />
    <wsrm:BaseRetransmissionInterval
        Milliseconds="3000" />
    <wsrm:ExponentialBackoff />
    <wsrm:AcknowledgementInterval
        Milliseconds="200" />
    <beapolicy:Expires Expires="P1D" optional="true"/>
  </wsrm:RMAssertion>

</wsp:Policy>

LongRunningReliability.xml WS-Policy ファイル

<?xml version="1.0"?>

<wsp:Policy
   xmlns:wsrm="http://schemas.xmlsoap.org/ws/2005/02/rm/policy"
   xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
   xmlns:beapolicy="http://www.bea.com/wsrm/policy"
  >

  <wsrm:RMAssertion >

    <wsrm:InactivityTimeout
        Milliseconds="86400000" />
    <wsrm:BaseRetransmissionInterval
        Milliseconds="3000" />
    <wsrm:ExponentialBackoff />
    <wsrm:AcknowledgementInterval
        Milliseconds="200" />
    <beapolicy:Expires Expires="P1M" optional="true"/>
  </wsrm:RMAssertion>

</wsp:Policy>

Web サービスの信頼性のあるメッセージングの使用 : 主な手順

WebLogic Web サービスの信頼性のあるメッセージングのコンフィグレーションには、JMS サーバやストア アンド フォワード (SAF) エージェントの作成など標準的な JMS タスクと共に、JWS ファイルへの付加的な JWS アノテーションの追加など Web サービス固有のタスクが必要です。また必要に応じて、あらかじめパッケージ化されているファイルを使用しない場合は、信頼性のある Web サービスの信頼性のあるメッセージング機能を記述した WS-Policy ファイルをユーザ側で作成します。

信頼性のある Web サービスの呼び出しに WebLogic クライアント API を使用している場合、クライアント アプリケーションは WebLogic Server 上で実行される必要があります。したがってコンフィグレーション タスクは、信頼性のある Web サービスを確実に呼び出すクライアント コードを含む Web サービスがデプロイされたソース WebLogic Server インスタンスと、信頼性のある Web サービスそのものがデプロイされた送り先 WebLogic Server インスタンスの、双方の上で実行される必要があります。

以下の手順では、信頼性のある Web サービスと、その信頼性のある Web サービスのオペレーションを確実に呼び出すクライアント Web サービスを作成する方法を説明しています。この手順では、2 つの Web サービスを実装する JWS ファイルをゼロから作成する方法を示しています。既存の JWS ファイルを更新する場合は、この手順をガイドとして利用してください。またこの手順では、ソース WebLogic Server インスタンスと送り先 WebLogic Server インスタンスのコンフィグレーション方法も示しています。

WebLogic Server インスタンスが Ant ベースの開発環境を設定して作成されており、かつ jwsc Ant タスクを実行して、生成された信頼性のある Web サービスをデプロイするためのターゲットを追加できる、作業用の build.xml ファイルがあることが前提となっています。さらに、Web サービスを確実に呼び出すクライアント Web サービスをホストする、別の WebLogic Server インスタンスを同様に設定してあることも前提となっています。詳細については、以下を参照してください。

送り先 WebLogic Server インスタンスのコンフィグレーション

信頼性のある Web サービスがデプロイされる WebLogic Server インスタンスをコンフィグレーションする際には、JMS およびストア アンド フォワード (SAF) リソースがコンフィグレーションされます。

これらのリソースは手作業でもコンフィグレーションできますが、コンフィグレーション ウィザードで、Web サービス固有の拡張テンプレートを使用して WebLogic Server ドメインを拡張することもできます。コンフィグレーション ウィザードを使用すると、必要なコンフィグレーション手順を大幅に簡略化できます。詳細については、「Web サービス機能用のドメイン コンフィグレーション」を参照してください。

リソースを手作業でコンフィグレーションしたい場合は、次に示す高度な手順に従ってください。各タスクの実行方法の詳細については、リンクが示されている Administration Console オンライン ヘルプのトピックを参照してください。

クラスタに関する考慮事項

クラスタ内で Web サービスの信頼性のあるメッセージング機能を使用する場合は、以下の作業を行う必要があります。

ソース WebLogic Server インスタンスのコンフィグレーション

クライアント Web サービスがデプロイされる WebLogic Server インスタンスをコンフィグレーションする際には、JMS およびストア アンド フォワード (SAF) リソースがコンフィグレーションされます。

これらのリソースは手作業でもコンフィグレーションできますが、コンフィグレーション ウィザードで、Web サービス固有の拡張テンプレートを使用して WebLogic Server ドメインを拡張することもできます。コンフィグレーション ウィザードを使用すると、必要なコンフィグレーション手順を大幅に簡略化できます。詳細については、「Web サービス機能用のドメイン コンフィグレーション」を参照してください。

リソースを手作業でコンフィグレーションしたい場合は、次に示す高度な手順に従ってください。各タスクの実行方法の詳細については、リンクが示されている Administration Console オンライン ヘルプのトピックを参照してください。

Web サービスの信頼性のあるメッセージングの WS-Policy ファイルの作成

WS-Policy ファイルは、WS-Policy 仕様に準拠するポリシー アサーションを含む XML ファイルです。この場合には、WS-Policy ファイルに Web サービスの信頼性のあるメッセージング ポリシーのアサーションが含まれています。

WebLogic Server に含まれる 2 つのデフォルトの信頼性のあるメッセージング WS-Policy ファイルのうち一方を使用できます。これらのファイルは、ほとんどの場合に適合しています。しかし、これらのファイルは変更ができないので、ニーズに合わない場合は独自のファイルを作成することが必要です。付属の WS-Policy ファイルについては、「Web サービスの信頼性のあるメッセージングをコンフィグレーションするための WS-Policy ファイルの使用」を参照してください。この節のこれ以降では、ユーザ独自の WS-Policy ファイルの作成方法について説明します。

WS-Policy ファイルのルート要素は <Policy> です。Web サービスの信頼性のあるメッセージング ポリシーのアサーションを使用するには、これに以下のネームスペース宣言が含まれていることが必要です。

<wsp:Policy
   xmlns:wsrm="http://schemas.xmlsoap.org/ws/2005/02/rm"
   xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
   xmlns:beapolicy="http://www.bea.com/wsrm/policy">

Web サービスの信頼性のあるメッセージング ポリシーのアサーションはすべて、<wsrm:RMAssertion> 要素の内部でラップします。wsrm: ネームスペースを使用するアサーションは、WS-ReliableMessaging 仕様で定義される標準的なアサーションです。beapolicy: ネームスペースを使用するアサーションは、WebLogic 固有のものです。詳細については、「Web サービスの信頼性のあるメッセージングのポリシー アサーションに関するリファレンス」を参照してください。

Web サービスの信頼性のあるメッセージングのアサーションは、すべて任意指定なので、デフォルト値が不適切なものだけを設定します。アサーションの指定順序は重要です。以下のアサーションを指定できますが、WS-Policy ファイルでは以下の一覧の順序どおりに指定する必要があります。

次の例では、簡単な Web サービスの信頼性のあるメッセージングの WS-Policy ファイルを示します。

<?xml version="1.0"?>

<wsp:Policy
   xmlns:wsrm="http://schemas.xmlsoap.org/ws/2005/02/rm/policy"
   xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
   xmlns:beapolicy="http://www.bea.com/wsrm/policy"
  >

 <wsrm:RMAssertion >

   <wsrm:InactivityTimeout
      Milliseconds="600000" />
   <wsrm:BaseRetransmissionInterval
      Milliseconds="500" />
   <wsrm:ExponentialBackoff />
   <wsrm:AcknowledgementInterval
      Milliseconds="2000" />

 </wsrm:RMAssertion>

</wsp:Policy>

信頼性のある JWS ファイルに関するプログラミングのガイドライン

この節では、信頼性のある Web サービスを実装する JWS ファイルの作成方法を説明します。

信頼性のある Web サービスを実装する JWS ファイルでは、次の JWS アノテーションが使用されます。

次のサンプルでは、信頼性のある Web サービスを実装する簡単な JWS ファイルを示します。太字で示された Java コードに対応するコーディングのガイドラインについては、サンプルの後の説明を参照してください。

package examples.webservices.reliable;

import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.jws.Oneway;

import weblogic.jws.WLHttpTransport;

import weblogic.jws.ReliabilityBuffer;
import weblogic.jws.BufferQueue;
import weblogic.jws.Policy;

/**
 * 簡単な信頼性のある Web サービス
 */

@WebService(name="ReliableHelloWorldPortType",
              serviceName="ReliableHelloWorldService")

@WLHttpTransport(contextPath="ReliableHelloWorld",
      serviceUri="ReliableHelloWorld",
      portName="ReliableHelloWorldServicePort")

@Policy(uri="ReliableHelloWorldPolicy.xml",
          direction=Policy.Direction.both,
          attachToWsdl=true)

@BufferQueue(name="webservices.reliable.queue")

public class ReliableHelloWorldImpl {

  @WebMethod()
  @Oneway()
  @ReliabilityBuffer(retryCount=10, retryDelay="10 seconds")

  public void helloWorld(String input) {
    System.out.println(" Hello World " + input);

  }
}

このサンプルでは、ReliableHelloWorldPolicy.xml ファイルがクラス レベルで Web サービスに追加されています。つまり、ポリシー ファイルは Web サービスのすべてのパブリック オペレーションに適用されます。ポリシー ファイルは、リクエスト Web サービス メッセージ (信頼性のあるメッセージング機能によって要求される) のみに適用され、WSDL ファイルに追加されます。

WebLogic Server が、Web サービスの信頼性のあるメッセージングを有効化するために内部で使用する JMS キューの JNDI 名は、@BufferQueue アノテーションで指定されているように、webservices.reliable.queue です。

helloWorld() メソッドは、@WebMethod と @Oneway、どちらの JWS アノテーションでもマークされています。これは、このメソッドが helloWorld というパブリック オペレーションであるということです。@Policy アノテーションがあるために、オペレーションを確実に呼び出すことができます。@ReliabilityBuffer アノテーションに記述されているとおり、Web サービスのランタイムでは、最大で 10 回、10 秒間隔で、信頼性のあるメッセージをサービスに配信しようとします。たとえば、トランザクションがロールバックされる場合や、コミットしない場合などには、メッセージの再配信が必要となることがあります。

@Policy アノテーションの使用

信頼性のあるメッセージングのアサーションが含まれる WS-Policy ファイルを Web サービスに追加するよう指定するには、JWS ファイルで @Policy アノテーションを使用します。

独自に記述する代わりに使用できる、WebLogic Server で用意されている 2 つの WS-Policy ファイル (DefaultReliability.xml および LongRunningReliability.xml) については、「Web サービスの信頼性のあるメッセージングをコンフィグレーションするための WS-Policy ファイルの使用」を参照してください。

@Policy アノテーションを Web サービスの信頼性のあるメッセージングに使用する場合、以下の要件を満たしている必要があります。

uri 属性を使用して、ポリシー ファイルのビルド時の場所を以下のように指定します。

また、@Policy アノテーションの attachToWsd 属性を設定して、ポリシー ファイルを Web サービスのパブリック規約が記述された WSDL ファイルに付加するかどうかを指定することもできます。通常は、クライアント アプリケーションで Web サービスの信頼性のあるメッセージング機能が認識されるよう、パブリックなものとしてポリシーを公開します。そのため、この属性のデフォルト値は true です。

@Oneway アノテーションの使用

信頼性のある Web サービスのオペレーションを同期的に呼び出す (すなわち、非同期の要求と応答機能を使用しない) 場合は、実装メソッドに @Oneway アノテーションを付けて、そのメソッドが一方向のものであることを指定する必要があります。つまり、メソッドは値を返すことができず、明示的に void を返すことになります。

反対に、メソッドに @Oneway アノテーションが付いていなければ、非同期の要求と応答機能を使用して呼び出す必要があります。オペレーションの呼び出し方法がわからない場合は、同期と非同期の 2 種類のオペレーションを作成することを検討してください。

「非同期の要求と応答を使用した Web サービスの呼び出し」および「非同期機能の併用」を参照してください。

@BufferQueue アノテーションの使用

信頼性のあるメッセージを内部に格納するために WebLogic Server が使用する JMS キューの JNDI 名を指定するには、@BufferQueue アノテーションを使用します。JNDI 名は、「送り先 WebLogic Server インスタンスのコンフィグレーション」の手順 4 で JMS キューを作成した際にコンフィグレーションしたものです。

@BufferQueue アノテーションは、省略可能です。これを JWS ファイルで指定しなければ、WebLogic Server は weblogic.wsee.DefaultQueue の JNDI 名を持つキューを使用します。ただし、それでもこの JNDI 名を持つ JMS キューを Administration Console で明示的に作成する必要はあります。

@ReliabilityBuffer アノテーションの使用

このアノテーションは、WebLogic Server による JMS キューから Web サービス実装へのメッセージ配信試行回数 (デフォルトでは 3 回)、およびサーバが待機すべき再試行間隔 (デフォルトでは 5 秒) の指定に使用します。

再試行回数の指定には retryCount 属性を、待機時間の指定には retryDelay 属性を使用します。retryDelay 属性の形式としては、数字の後に以下の文字列のうち 1 つを続けます。

たとえば、再試行回数を 20、再試行の遅延を 2 日と指定するには、次の構文を使用します。

@ReliabilityBuffer(retryCount=20, retryDelay="2 days")

信頼性のある Web サービスを呼び出す JWS ファイルに関するプログラミングのガイドライン

WebLogic クライアント API を使用している場合は、信頼性のある Web サービスを Web サービス内から呼び出す必要があります。スタンドアロンのクライアント アプリケーションからは呼び出せません。

次の例では、「信頼性のある JWS ファイルに関するプログラミングのガイドライン」で説明した、サービスから信頼性のあるオペレーションを呼び出す Web サービス用の簡単な JWS ファイルを示します。太字で示された Java コードに対応するコーディングのガイドラインについては、サンプルの後の説明を参照してください。

package examples.webservices.reliable;

import java.rmi.RemoteException;

import javax.jws.WebMethod;
import javax.jws.WebService;

import weblogic.jws.WLHttpTransport;
import weblogic.jws.ServiceClient;
import weblogic.jws.ReliabilityErrorHandler;

import examples.webservices.reliable.ReliableHelloWorldPortType;

import weblogic.wsee.reliability.ReliabilityErrorContext;
import weblogic.wsee.reliability.ReliableDeliveryException;

@WebService(name="ReliableClientPortType",
            serviceName="ReliableClientService")

@WLHttpTransport(contextPath="ReliableClient",
                 serviceUri="ReliableClient",
                 portName="ReliableClientServicePort")

public class ReliableClientImpl
{

  @ServiceClient(
     serviceName="ReliableHelloWorldService",
     portName="ReliableHelloWorldServicePort")

  private ReliableHelloWorldPortType port;

  @WebMethod
  public void callHelloWorld(String input, String serviceUrl)
     throws RemoteException {

    port.helloWorld(input);

    System.out.println(" Invoked the ReliableHelloWorld.helloWorld operation reliably."

  }

  @ReliabilityErrorHandler(target="port")
  public void onReliableMessageDeliveryError(ReliabilityErrorContext ctx) {

    ReliableDeliveryException fault = ctx.getFault();
    String message = null;
    if (fault != null) {
      message = ctx.getFault().getMessage();
    }
    String operation = ctx.getOperationName();
    System.out.println("Reliable operation " + operation + " may have not invoked.The error message is " + message);
  }

}

信頼性のある Web サービスを呼び出す JWS ファイルをプログラミングする際には、以下のガイドラインに従います。ガイドラインのサンプル コードは、上述のサンプル内では太字で示されています。

クライアント Web サービスをプログラミングする際は、以下の点に注意してください。

WsrmUtils ユーティリティ クラス

WebLogic Server には、Web サービスの信頼性のあるメッセージング機能で使用するユーティリティ クラスが用意されています。このクラスを使用すると、オプションのコンフィグレーション、シーケンス ID の取得、信頼性のあるシーケンスの終了、といった一般的なタスクを実行できます。これらのタスクには、信頼性のある Web サービス内で実行するものと、信頼性のある Web サービスを呼び出す Web サービス内で実行するものがあります。

詳細については、weblogic.wsee.reliability.WsrmUtils を参照してください。

信頼性のある Web サービスのクライアント用 build.xml ファイルの更新

build.xml を更新して、信頼性のある Web サービスのオペレーションを呼び出す JWS ファイルを生成するには、次のような taskdefs および build-reliable-client ターゲットを追加します。詳細については、サンプルの後の説明を参照してください。

<taskdef name="jwsc"
    classname="weblogic.wsee.tools.anttasks.JwscTask" />

<target name="build-reliable-client">

    <jwsc
        enableAsyncService="true"
        srcdir="src"
        destdir="${client-ear-dir}" >

        <jws file="examples/webservices/reliable/ReliableClientImpl.java">

          <clientgen
            wsdl="http://${wls.destination.host}:${wls.destination.port}/ReliableHelloWorld/ReliableHelloWorld?WSDL"
            packageName="examples.webservices.reliable"/>

        </jws>

    </jwsc>

</target>

jwsc Ant タスクの完全なクラス名を定義するには、taskdef Ant タスクを使用します。

クライアント Web サービスをコンパイルする jwsc Ant タスクを更新して、<jws> 要素の <clientgen> 子要素を含めます。これにより、デプロイされた ReliableHelloWorld Web サービスの JAX-RPC スタブが生成およびコンパイルされるようになります。jwsc Ant タスクでは、これらのスタブが生成された WAR ファイルに自動的にパッケージ化されるため、即座にクライアント Web サービスからアクセスできるようになります。このようにするのは、生成されたクラスの 1 つを ReliableClientImpl JWS ファイルでインポートして使用するためです。

信頼性のある Web サービスを再デプロイする際にクライアント側で考慮すべき事項

WebLogic Server では、プロダクションの再デプロイメントがサポートされています。つまり、信頼性のある WebLogic Web サービスの更新後の新しいバージョンを、同じ Web サービスの古いバージョンと並行してデプロイできます。

WebLogic Server では、新しいクライアントのリクエストのみが新しいバージョンに転送されるように、クライアント接続が自動的に管理されます。再デプロイメント時にすでに Web サービスに接続していたクライアントは、作業が完了するまで古いバージョンのサービスを使用し続けます。作業が完了した時点で、自動的に古い Web サービスが廃止されます。クライアントが信頼性のある Web サービスに接続されている場合は、既存の信頼性のあるメッセージ シーケンスがクライアントによって明示的に終了されるか、またはタイムアウトになったときに、そのクライアントの作業が完了したと見なされます。

プロダクションの再デプロイメントと Web サービス クライアントの詳細については、「Web サービスを再デプロイする際にクライアント側で考慮すべき事項」を参照してください。

信頼性のあるメッセージングとプロキシ サーバの使用

信頼性のある Web サービスを呼び出すクライアント アプリケーションでは、直接オペレーションを呼び出すのではなく、プロキシ サーバを使用することがあります。プロキシを使用する理由としては、ファイアウォールの存在や、呼び出された Web サービスのクラスタへのデプロイメントなどがあります。

この場合、呼び出された Web サービスをホストする WebLogic Server インスタンスは、プロキシ サーバのアドレスとポートでコンフィグレーションされる必要があります。Web サービスがクラスタにデプロイされている場合は、そのクラスタ内のすべてのサーバをコンフィグレーションすることが必要です。

各サーバ インスタンスについて、以下の手順を実行します。