WebLogic Web サービス プログラマーズ ガイド

高度な JWS プログラミング : JMS 転送および SOAP メッセージ ハンドラ

以下の節では、下記の高度な JWS プログラミング トピックに関する情報を提供します。

接続プロトコルとしての JMS 転送の使用

通常、クライアント アプリケーションから WebLogic Web サービスを呼び出すときは、接続プロトコルとして HTTP/S が使用されます。しかし、クライアント アプリケーションが転送に JMS を使用するように WebLogic Web サービスをコンフィグレーションすることもできます。JWS アノテーションか、後の節で説明する jwsc Ant タスクの子要素のどちらかを使用して、転送をコンフィグレーションします。

WebLogic Web サービスで、接続転送に JMS を使用するようにコンフィグレーションを行った場合、Web サービスの生成済み WSDL における対応するポートに対して指定されたエンドポイント アドレスの URL では、http:// ではなく jms:// が使用されます。JMS エンドポイントのアドレスの例を次に示します。

jms://myHost:7001/transports/JMSTransport?URI=JMSTransportQueue

URL の URI=JMSTransportQueue セクションでは、JMS 転送機能用にコンフィグレーションされた JMS キューを指定しています。HTTP を使用して Web サービスを呼び出すことはできませんが、HTTP を使用してその Web サービスの WSDL を参照することはできます。それにより、clientgen はやはり Web サービスの JAX-RPC スタブを生成することができます。

指定する各転送に対し、WebLogic Server は WSDL 内に追加のポートを生成します。このため、Web サービス呼び出し時に使用できる転送 (JMS、HTTP、または HTTPS) をクライアント アプリケーションで選択できるようにするには、適切な JWS アノテーションまたは jwsc の子要素を使用して、明示的に転送を追加する必要があります。

Java から開始する JMS 転送の使用 : 主な手順

Java から開始するときに JMS 転送を使用するには、少なくとも以下のタスクのいずれか 1 つを実行する必要があります。

以下に、Java から開始するときに JMS 転送を使用して Web サービスを呼び出せるようにするために必要な手順をすべて示します。

JMS 転送を使用した Web サービスを呼び出すためのクライアント アプリケーションの更新については、「JMS 転送を使用した WebLogic Web サービスの呼び出し」を参照してください。

WSDL から開始する JMS 転送の使用 : 主な手順

WSDL から開始するときに JMS 転送を使用するには、少なくとも以下のタスクのいずれか 1 つを実行する必要があります。

以下に、WSDL から開始するときに JMS 転送を使用して Web サービスを呼び出せるようにするために必要な手順をすべて示します。

JMS 転送を使用した Web サービスを呼び出すためのクライアント アプリケーションの更新については、「JMS 転送を使用した WebLogic Web サービスの呼び出し」を参照してください。

@WLJmsTransport JWS アノテーションの使用

JWS ファイルをプログラムした時点で、Web サービスの呼び出しにクライアント アプリケーションで (HTTP/S ではなく) JMS 転送を使用することが決まっている場合は、@WLJmsTransport を使用してその呼び出しの詳細を指定できます。後のビルド時に、「jwsc Ant タスクの <WLJmsTransport> 子要素の使用」に従い、jwsc Ant タスクの <WLJmsTransport> 子要素を指定して、JWS ファイル内の指定をオーバーライドし、さらなる JMS 転送指定を追加できます。

@WLJmsTranport アノテーションを使用する際は、以下のガイドラインに従ってください。

次の例では、@WLJmsTransport アノテーションを使用する簡単な JWS ファイルを示します。関連するコードは太字で示しています。

package examples.webservices.jmstransport;

import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.jws.soap.SOAPBinding;

import weblogic.jws.WLJmsTransport;

@WebService(name="JMSTransportPortType",
             serviceName="JMSTransportService",
            targetNamespace="http://example.org")

@SOAPBinding(style=SOAPBinding.Style.DOCUMENT,
             use=SOAPBinding.Use.LITERAL,
             parameterStyle=SOAPBinding.ParameterStyle.WRAPPED)

// Web サービスの URI を構成するのに使用されるコンテキスト パスとサービス URI が
// 「transports/JMSTransport」であることを指定する、WebLogic 固有の 
// JWS アノテーション

@WLJmsTransport(contextPath="transports", serviceUri="JMSTransport",
                queue="JMSTransportQueue", portName="JMSTransportServicePort")

/**
 * この JWS ファイルでは、1 つのオペレーション sayHello を含む簡単な
 * Java クラス実装の WebLogic Web サービスを形成する
 *
 * @author Copyright (c) 2005 by BEA Systems.All rights reserved.
 */

public class JMSTransportImpl {

  @WebMethod()
  public String sayHello(String message) {
    System.out.println("sayHello:" + message);
    return "Here is the message: '" + message + "'";
  }
}

jwsc Ant タスクの <WLJmsTransport> 子要素の使用

JMS 転送は jwsc Ant タスクの <jws> 要素の <WLJmsTransport> 子要素を使用して、ビルド時にも指定できます。ビルド時に転送を指定する理由としては、次のようなものが挙げられます。

jwsc Ant タスクに対して転送を指定すると、それが JWS ファイル内のすべての転送アノテーションに優先されます。

次の例では、jwsc Ant タスクに対して転送を指定する方法を示します。

  <target name="build-service">

    <jwsc
      srcdir="src"
      destdir="${ear-dir}">
      <jws file="examples/webservices/jmstransport/JMSTransportImpl.java">

        <WLJmsTransport
                contextPath="transports" 
                serviceUri="JMSTransport"
                portName="JMSTransportServicePort"
               queue="JMSTransportQueue"/>

      </jws>

    </jwsc>

  </target>

上述の例では、「@WLJmsTransport JWS アノテーションの使用」に示した JWS ファイルで指定されたものと同じ値を URL および JMS キューに対して指定する方法を示します。

jwsc Ant タスクの使用の詳細については、「jwsc」を参照してください。

JMS 転送を使用するための WSDL の編集

JMS 転送を使用するには、WSDL を編集して JMS 転送情報を定義する <wsdl:binding> と <wsdl:service> 定義を追加する必要があります。定義は、以下のいずれかの方法で追加することができます。

どちらの場合も、JMS 転送を使用するように <wsdl:binding> と <wsdl:service> 定義を以下のように編集する必要があります。

JMS 転送を使用した WebLogic Web サービスの呼び出し

JMS 転送を使用して Web サービスを呼び出すクライアント アプリケーションの記述は、HTTP 転送を使用する場合の記述と同様に行います。ただ 1 つ異なるのは、必ず、JMS キュー (@WLJmsTransport アノテーションまたは jwsc Ant タスクの <WLJmsTransport> 子要素で指定) やその他の JMS オブジェクトが作成済みでなければならないという点です。詳細については、「Java から開始する JMS 転送の使用 : 主な手順」または「WSDL から開始する JMS 転送の使用 : 主な手順」を参照してください。

HTTP を使用して JMS 転送でコンフィグレーションされた Web サービスを呼び出すことはできませんが、HTTP を使用してその Web サービスの WSDL を参照することはできます。それにより、clientgen Ant タスクはやはり Web サービスの JAX-RPC スタブを作成することができます。たとえば、この節で示す Web サービスの WSDL のための URL は、次のようになります。

http://host:port/transports/JMSTransport?WSDL

ただし、デプロイされた Web サービスの WSDL におけるエンドポイント アドレスでは、http:// ではなく jms:// が使用され、このアドレスには修飾子 ?URI=JMS_QUEUE が含まれるため、clientgen Ant タスクは Web サービス呼び出し時に JMS 転送を使用するために必要なスタブを自動作成し、クライアント アプリケーション側で通常と違う処理を行う必要はありません。JMS エンドポイントのアドレスの例を次に示します。

jms://host:port/transports/JMSTransport?URI=JMSTransportQueue

Web サービス呼び出しに関する全般的な情報については、「Web サービスの呼び出し」を参照してください。

デフォルトのサービス アドレス URL をオーバーライドする

clientgen で生成された JAX-RPC スタブを使用して Web サービスを呼び出すクライアント アプリケーションを作成する場合、Web サービスのデフォルトのサービス アドレス URL は、Service コンストラクタの WSDL ファイル引数の <address> 要素で指定したものとなります。

しかし場合によっては、特にクラスタにデプロイされている WebLogic Web サービスを呼び出す際に、クラスタのアドレスまたはクラスタ内の管理対象サーバのアドレスのリストを指定する場合には、このアドレスをオーバーライドする必要があることがあります。また、t3 プロトコルを使用して Web サービスを呼び出すことが必要な場合もあります。JMS 転送の使用時にこのサービス エンドポイント URL をオーバーライドするには、次の例で示すように、weblogic.wsee.jaxrpc.WLStub.JMS_TRANSPORT_JNDI_URL スタブ プロパティを使用します。

package examples.webservices.jmstransport.client;

import weblogic.wsee.jaxrpc.WLStub;

import java.rmi.RemoteException;

import javax.xml.rpc.ServiceException;
import javax.xml.rpc.Stub;

/**
 * JMSTransport Web サービスの sayHello オペレーションを呼び出す
 * 簡単なスタンドアロンのクライアント アプリケーション
 *
 * @author Copyright (c) 2004 by BEA Systems. All Rights Reserved.
 */

public class Main {

  public static void main(String[] args)
      throws ServiceException, RemoteException{

    JMSTransportService service = new JMSTransportService_Impl(args[0] + "?WSDL" );
    JMSTransportPortType port = service.getJMSTransportServicePort();

    Stub stub = (Stub) port;

    stub._setProperty(WLStub.JMS_TRANSPORT_JNDI_URL,
                      "t3://shackell01.amer.bea.com:7001");
    try {
      String result = null;

      result = port.sayHello("Hi there! ");

      System.out.println( "Got JMS result: " + result );

    } catch (RemoteException e) {
      throw e;
    }
  }
}

その他のスタブ プロパティについては、WLStub のリファレンス ドキュメントを参照してください。

デフォルトの TextMessage の代わりに JMS BytesMessage を使用する

JMS 転送を使用する場合、Web サービス ランタイムはデフォルトでは javax.jms.TextMessage オブジェクトを使用してメッセージを送信します。ほとんどのクライアント アプリケーションはこのデフォルトのままで十分ですが、状況によっては普通のテキストではなくバイナリ データを送信する必要がある場合もあります。その場合は、Web サービス ランタイムで javax.jms.BytesMessage を使用することを要求する必要があります。そのためには、クライアント アプリケーションで WLStub.JMS_TRANSPORT_MESSAGE_TYPE スタブ プロパティを使用し、値として WLStub.JMS_BYTESMESSAGE を設定します。次に例を示します。

    stub._setProperty(WLStub.JMS_TRANSPORT_MESSAGE_TYPE,
                      WLStub.JMS_BYTESMESSAGE);

Web サービス ランタイムは、リクエストと同じメッセージ データ型を使用して応答を送り返します。

このプロパティを設定できるクライアント アプリケーションの例については、「デフォルトのサービス アドレス URL をオーバーライドする」を参照してください。その他のスタブ プロパティについては、WLStub のリファレンス ドキュメントを参照してください。

WSDL ファイルへの HTTP アクセスを無効にする

「JMS 転送を使用した WebLogic Web サービスの呼び出し」で説明したように、デプロイされている Web サービスの WSDL には、デフォルトでは HTTP でアクセスできるようになっています。WSDL ファイルへのアクセスを無効にしたい場合 (特に、ファイアウォールの外で Web サービスにアクセスできる場合) は、以下のいずれかのタスクを実行します。

SOAP メッセージ ハンドラの作成と使用

Web サービスの中には、SOAP メッセージへのアクセスを必要とするものがあり、SOAP メッセージに対して SOAP メッセージ ハンドラを作成できます。

SOAP メッセージ ハンドラは、Web サービスのリクエストと応答の両方で SOAP メッセージをインターセプトするメカニズムです。ハンドラは、Web サービスそのものと Web サービスを呼び出すクライアント アプリケーションの両方で作成することができます。

ハンドラ使用の簡単な例としては、SOAP メッセージのヘッダ部分の情報へのアクセスがあります。SOAP のヘッダを使用して Web サービス固有の情報を格納しておいて、ハンドラを使用してその情報を操作することができます。

SOAP メッセージ ハンドラは、Web サービスのパフォーマンスを向上させるために使用することもできます。Web サービスがデプロイされてしばらくすると、同じパラメータを使用して Web サービスを呼び出すコンシューマが多いことに気付く場合があります。よく使用される Web サービス呼び出しの結果 (静的な結果を前提として) をキャッシュしておき、Web サービスを実装するバックエンド コンポーネントを呼び出すことなく、適宜、キャッシュしておいた結果をただちに返すことによって、Web サービスのパフォーマンスを向上させることができます。このパフォーマンスの向上は、ハンドラを使用して、SOAP リクエスト メッセージに頻繁に使用されるパラメータが含まれていないかチェックすることで達成されます。

次の表では、Web サービスでハンドラ チェーンがコンフィグレーションされていることを指定するために JWS ファイル内で使用できる標準的な JWS アノテーションを示しています。その後の節で、これらのアノテーションの使い方について、より詳細に説明します。詳細については、Web Services MetaData for the Java Platform 仕様 (JSR-181) を参照してください。

次の表では、javax.xml.rpc.handler API のメイン クラスおよびインタフェースについて説明します。これらの一部は、ハンドラそのものの作成時に使用します。これらの API については、後の節でより詳細に説明します。これらの API の詳細については、JAX-RPC 1.1 仕様を参照してください。

SOAP メッセージ ハンドラの Web サービスへの追加 : 主な手順

次の手順では、Web サービスに SOAP メッセージ ハンドラを追加する高度な手順を説明します。

Web サービスを実装する基本的な JWS ファイルをすでに作成済みであり、SOAP メッセージ ハンドラおよびハンドラ チェーンを追加することで Web サービスを更新することが前提となっています。また、Ant ベースの開発環境を設定済みであり、かつ jwsc Ant タスクを実行するためのターゲットを含む、作業用の build.xml ファイルがあることが前提となっています。詳細については、「WebLogic Web サービスの反復的な開発」および「JWS ファイルのプログラミング」を参照してください。

クライアント サイドの SOAP メッセージ ハンドラおよびハンドラ チェーンの作成については、「クライアントサイド SOAP メッセージ ハンドラの作成と使用」を参照してください。

SOAP メッセージ ハンドラおよびハンドラ チェーンの設計

SOAP メッセージ ハンドラおよびハンドラ チェーンを設計するときには、以下の事項を決める必要があります。

ハンドラ チェーン内の各ハンドラには、SOAP のリクエスト メッセージを処理するメソッドと SOAP の応答メッセージを処理するメソッドが 1 つずつあります。順序付けされたハンドラのグループが、ハンドラ チェーンです。Web サービスに、@HandlerChain または @SOAPMessageHandler という 2 つの JWS アノテーションのうち 1 つを備えるハンドラ チェーンが付加されていることを指定します。どちらをいつ使用するかは、後の節で説明します。

Web サービスを呼び出すときに、WebLogic Server は次のようにハンドラを実行します。

たとえば、JWS ファイルで @HandlerChain JWS アノテーションを使用して外部コンフィグレーション ファイルを指定することになっており、そのコンフィグレーション ファイルでは、次の例に示す 3 つのハンドラが格納された SimpleChain というハンドラ チェーンを定義していると仮定します。

<jwshc:handler-config xmlns:jwshc="http://www.bea.com/xml/ns/jws"
   xmlns:soap1="http://HandlerInfo.org/Server1"
   xmlns:soap2="http://HandlerInfo.org/Server2"
   xmlns="http://java.sun.com/xml/ns/j2ee" >

   <jwshc:handler-chain>

     <jwshc:handler-chain-name>SimpleChain</jwshc:handler-chain-name>

     <jwshc:handler>
       <handler-name>handlerOne</handler-name>
       <handler-class>examples.webservices.soap_handlers.global_handler.ServerHandler1</handler-class>
     </jwshc:handler>

     <jwshc:handler>
       <handler-name>handlerTwo</handler-name>
       <handler-class>examples.webservices.soap_handlers.global_handler.ServerHandler2</handler-class>
     </jwshc:handler>

     <jwshc:handler>
       <handler-name>handlerThree</handler-name>
       <handler-class>examples.webservices.soap_handlers.global_handler.ServerHandler3</handler-class>
     </jwshc:handler>

   </jwshc:handler-chain>

</jwshc:handler-config>

次の図は、WebLogic Server で各ハンドラの handleRequest() メソッドと handleResponse() メソッドが実行される順序を示しています。

通常、着信メッセージと発信メッセージで同じタイプの処理が必要となるので、各 SOAP メッセージ ハンドラには、リクエスト SOAP メッセージと応答 SOAP メッセージを処理する別個のメソッドがあります。たとえば、SOAP リクエストにあるセキュア データを復号化する handleRequest() メソッドと、SOAP 応答を暗号化する handleResponse() メソッドを持つ暗号化ハンドラを設計する場合があります。

一方、SOAP リクエストのみを処理し、それと同等の応答処理は行わないハンドラを設計することもできます。

また、ハンドラ チェーン内の次のハンドラを呼び出さず、そのまま、任意の時点でクライアント アプリケーションに応答を送信することも可能です。

GenericHandler クラスの作成

SOAP メッセージ ハンドラ クラスでは、javax.rpc.xml.handler.GenericHandler 抽象クラスを拡張する必要があります。この抽象クラス自体が、javax.rpc.xml.handler.Handler インタフェースを実装します。

GenericHandler クラスは、ハンドラの記述を容易にする便利な抽象クラスです。このクラスは、ライフサイクル メソッド init() および destroy() ならびに Handler インタフェースのさまざまな handleXXX() メソッドのデフォルト実装を提供します。ハンドラ クラスを記述する際には、Handler 実装クラスの一部としてカスタマイズが必要なメソッドのみをオーバーライドします。

具体的には、Handler インタフェースには、GenericHandler を拡張するハンドラ クラス内で実装できる、次のメソッドが格納されています。

特に画像などの添付ファイルを処理する場合などには、ハンドラ内から直接 SOAP メッセージを表示または更新しなければならない場合もあります。その場合には、javax.xml.soap.SOAPMessage 抽象クラスを使用します。このクラスは、SOAP With Attachments API for Java 1.1 (SAAJ) 仕様の構成要素です。詳細については、「SAAJ を使用して SOAP リクエスト メッセージおよび応答メッセージを直接操作する」を参照してください。

次の例は、SOAP のリクエストおよび応答メッセージを WebLogic Server のログ ファイルに出力する簡単な SOAP メッセージ ハンドラを示しています。

package examples.webservices.soap_handlers.global_handler;

import javax.xml.namespace.QName;
import javax.xml.rpc.handler.HandlerInfo;
import javax.xml.rpc.handler.GenericHandler;
import javax.xml.rpc.handler.MessageContext;
import javax.xml.rpc.handler.soap.SOAPMessageContext;
import javax.xml.rpc.JAXRPCException;

import weblogic.logging.NonCatalogLogger;

/**
 * このクラスは、SOAP のリクエストおよび応答メッセージにアクセスするために使用する、ハンドラ チェーンの
 * ハンドラを実装する
 * 
 * このクラスは、javax.xml.rpc.handler.GenericHandler 抽象クラスを
 * 拡張するものであり、単に、メッセージが Web サービス自体を実装するバックエンド 
 * Java クラスによって処理される前に、SOAP リクエストおよび応答メッセージを
 * サーバ ログ ファイルに出力する
 */

public class ServerHandler1 extends GenericHandler {

  private NonCatalogLogger log;

  private HandlerInfo handlerInfo;

  /**
   *  ハンドラのインスタンスを初期化する。メッセージ ログの記録先となる 
   *  nonCatalogLogger を作成する
   */

  public void init(HandlerInfo hi) {

    log = new NonCatalogLogger("WebService-LogHandler");
    handlerInfo = hi;

  }

  /**
   * Web サービスを実装する Java クラスにメッセージが送信される前に、SOAP 
   * リクエスト メッセージがログ ファイルに記録されることを指定する
   */

  public boolean handleRequest(MessageContext context) {

   SOAPMessageContext messageContext = (SOAPMessageContext) context;

   System.out.println("** Request: "+messageContext.getMessage().toString());
   log.info(messageContext.getMessage().toString());
   return true;

  }

  /**
   * Web サービスを呼び出したクライアント アプリケーションにメッセージが送り
   * 返される前に、SOAP 応答メッセージがログ ファイルに記録されることを
   * 指定する
   */

  public boolean handleResponse(MessageContext context) {

    SOAPMessageContext messageContext = (SOAPMessageContext) context;

    System.out.println("** Response: "+messageContext.getMessage().toString());
    log.info(messageContext.getMessage().toString());
    return true;

  }

  /**
   * SOAP エラーが Handler インスタンスによって送出された場合、メッセージが
   * ログ ファイルに記録されることを指定する
   */

  public boolean handleFault(MessageContext context) {

   SOAPMessageContext messageContext = (SOAPMessageContext) context;

   System.out.println("** Fault: "+messageContext.getMessage().toString());
   log.info(messageContext.getMessage().toString());
       return true;

  }

  public QName[] getHeaders() {

    return handlerInfo.getHeaders();

  }

}

Handler.init() メソッドを実装する

Handler.init() メソッドは、Handler オブジェクトのインスタンスを作成し、そのインスタンスが自動的に初期化されるようにするために呼び出されます。そのシグネチャは次のとおりです。

  public void init(HandlerInfo config) throws JAXRPCException {}

HandlerInfo オブジェクトには、SOAP メッセージ ハンドラ情報、特に初期化パラメータが格納されています。HandlerInfo.getHandlerConfig() メソッドを使用してパラメータを取得すると、このメソッドは、名前と値のペアの入った java.util.Map オブジェクトを返します。

初期化パラメータを処理する必要がある場合、または、他の初期化タスクを実行する必要がある場合は、init() メソッドを実装します。

初期化パラメータの使用例としては、デバッグのオン、オフ、メッセージやエラーを書き込むためのログ ファイルの名前の指定などがあります。

Handler.destroy() メソッドを実装する

Handler.destroy() メソッドは、Handler オブジェクトのインスタンスを破棄するために呼び出されます。そのシグネチャは次のとおりです。

  public void destroy() throws JAXRPCException {}

destroy() メソッドを実装すると、ハンドラのライフサイクルを通じて取得されたあらゆるリソースを解放できます。

Handler.getHeaders() メソッドを実装する

Handler.getHeaders() メソッドは、この Handler インスタンスで処理できるヘッダ ブロックを取得します。そのシグネチャは次のとおりです。

  public QName[] getHeaders() {}

Handler.handleRequest() メソッドを実装する

Handler.handleRequest() メソッドは、バックエンド コンポーネントによって処理される前に SOAP のリクエスト メッセージをインターセプトするために呼び出されます。そのシグネチャは次のとおりです。

  public boolean handleRequest(MessageContext mc) 
          throws JAXRPCException,SOAPFaultException  {}

このメソッドを実装すると、バックエンド コンポーネントによって処理される前の SOAP メッセージ内のデータの復号化などのタスクが実行できます。

MessageContext オブジェクトは、SOAP メッセージ ハンドラによって処理されたメッセージのコンテキストを抽出します。MessageContext プロパティにより、ハンドラ チェーン内のハンドラは処理ステートを共有できます。

MessageContext の SOAPMessageContext サブインタフェースを使用すると、SOAP のリクエスト メッセージの内容を取得または更新することができます。SOAP のリクエスト メッセージそのものは、javax.xml.soap.SOAPMessage オブジェクトに格納されます。このオブジェクトの詳細については、「SAAJ を使用して SOAP リクエスト メッセージおよび応答メッセージを直接操作する」を参照してください。

SOAPMessageContext クラスは、SOAP リクエストを処理する次の 2 つのメソッドを定義します。

SOAP リクエストのすべての処理をコーディングしたら、次のシナリオのいずれかをコーディングします。

Handler.handleResponse() メソッドを実装する

Handler.handleResponse() メソッドは、バックエンド コンポーネントによって処理された SOAP の応答メッセージをインターセプトするために呼び出されますが、この Web サービスを呼び出したクライアント アプリケーションに返される前に呼び出されます。そのシグネチャは次のとおりです。

  public boolean handleResponse(MessageContext mc) throws JAXRPCException {}

このメソッドを実装すると、クライアント アプリケーションに返される前に SOAP メッセージに含まれているデータを暗号化したり、戻り値に処理を加えたりといったタスクを実行できます。

MessageContext オブジェクトは、SOAP メッセージ ハンドラによって処理されたメッセージのコンテキストを抽出します。MessageContext プロパティにより、ハンドラ チェーン内のハンドラは処理ステートを共有できます。

MessageContext の SOAPMessageContext サブインタフェースを使用すると、SOAP の応答メッセージの内容を取得または更新することができます。SOAP の応答メッセージそのものは、javax.xml.soap.SOAPMessage オブジェクトに格納されます。「SAAJ を使用して SOAP リクエスト メッセージおよび応答メッセージを直接操作する」を参照してください。

SOAPMessageContext クラスは、SOAP 応答を処理する次の 2 つのメソッドを定義します。

SOAP 応答のすべての処理をコーディングしたら、次のシナリオのいずれかをコーディングします。

Handler.handleFault() メソッドを実装する

Handler.handleFault() メソッドは、SOAP メッセージ処理モデルに基づいて SOAP 障害を処理します。そのシグネチャは次のとおりです。

    public boolean handleFault(MessageContext mc) throws JAXRPCException  {}

このメソッドを実装すると、バックエンド コンポーネントによって生成された障害のほか、handleResponse() メソッドおよび handleRequest() メソッドによって生成されたあらゆる SOAP 障害の処理も扱うことができます。

MessageContext オブジェクトは、SOAP メッセージ ハンドラによって処理されたメッセージのコンテキストを抽出します。MessageContext プロパティにより、ハンドラ チェーン内のハンドラは処理ステートを共有できます。

MessageContext の SOAPMessageContext サブインタフェースを使用すると、SOAP メッセージの内容を取得または更新することができます。SOAP メッセージそのものは、javax.xml.soap.SOAPMessage オブジェクトに格納されます。「SAAJ を使用して SOAP リクエスト メッセージおよび応答メッセージを直接操作する」を参照してください。

SOAPMessageContext クラスは、SOAP メッセージを処理する次の 2 つのメソッドを定義します。

SOAP 障害のすべての処理をコーディングしたら、次のいずれかを実行します。

SAAJ を使用して SOAP リクエスト メッセージおよび応答メッセージを直接操作する

javax.xml.soap.SOAPMessage 抽象クラスは、SOAP With Attachments API for Java 1.1 (SAAJ) 仕様の構成要素です。このクラスは、SOAP メッセージ ハンドラ作成時に SOAP のリクエスト メッセージおよび応答メッセージを操作するのに使用します。この節では、SOAPMessage オブジェクトの基本構造と SOAP メッセージの表示および更新に役立つメソッドのいくつかについて説明します。

SOAPMessage オブジェクトは、SOAPPart オブジェクト (SOAP XML ドキュメントそのものが入っている)、または同オブジェクトと添付ファイルで構成されています。

SOAPMessage クラスの詳細な説明については、SAAJ に関する Javadoc を参照してください。SAAJ の詳細については、http://java.sun.com/xml/saaj/index.html を参照してください。

SOAPPart オブジェクト

SOAPPart オブジェクトには、SOAPEnvelope オブジェクトに格納された XML SOAP ドキュメントが入っています。このオブジェクトは、実際の SOAP のヘッダと本文を取得するのに使用します。

次の Java コードのサンプルは、Handler クラスによって提供された MessageContext オブジェクトから SOAP メッセージを取り出して、その各部を参照する方法を示しています。

SOAPMessage soapMessage =  messageContext.getMessage();
SOAPPart soapPart = soapMessage.getSOAPPart();
SOAPEnvelope soapEnvelope = soapPart.getEnvelope();
SOAPBody soapBody = soapEnvelope.getBody();
SOAPHeader soapHeader = soapEnvelope.getHeader(); 

AttachmentPart オブジェクト

javax.xml.soap.AttachmentPart オブジェクトには、SOAP メッセージに対するオプションの添付ファイルが入っています。添付ファイルは、SOAP メッセージの残りの部分とは異なり、XML フォーマットの必須部分ではないので、その形式は、単純なテキストからイメージ ファイルまで、さまざまです。

添付ファイルを操作するには、SOAPMessage クラスの以下のメソッドを使用します。

SOAP メッセージ ハンドラでの画像添付ファイルの操作

この節では、添付ファイル java.awt.Image にアクセスする SOAP メッセージ ハンドラを作成すること、および clientgen Ant タスクによって生成されたクライアント JAX-RPC スタブを使用するクライアント アプリケーションから Image が送信されていることを前提としています。

clientgen Ant タスクによって生成されたクライアント コードでは、添付ファイル java.awt.Image は image/gif ではなく text/xml の MIME タイプで、呼び出される WebLogic Web サービスに送信され、画像は画像を表す整数のストリームにシリアライズされます。特に、このクライアント コードは次の形式で画像をシリアライズします。

つまり、受信した Image 添付ファイルを操作する SOAP メッセージ ハンドラでは、このデータ ストリームをデシリアライズして元の画像を作成し直す必要があるということです。

JWS ファイルでのハンドラのコンフィグレーション

Web サービスのハンドラ チェーンをコンフィグレーションするために JWS ファイルで使用できる標準的なアノテーションは、@javax.jws.HandlerChain および @javax.jws.soap.SOAPMessageHandlers の 2 つです。

@javax.jws.HandlerChain

@javax.jws.HandlerChain アノテーション (この章では簡単にするため @HandlerChain とも言う) を使用する場合は、file 属性を使用して、Web サービスと関連付けるハンドラ チェーンのコンフィグレーションが含まれた外部ファイルを指定します。コンフィグレーションには、チェーン内のハンドラのリスト、ハンドラが実行される順序、初期化パラメータなどが含まれます。

以下の条件の 1 つ以上が適用される場合は、@SOAPMessageHandlers アノテーションではなく @HandlerChain アノテーションを JWS ファイルで使用します。

次の JWS ファイルでは、@HandlerChain アノテーションの使用例を示します。関連の Java コードは太字で示しています。

package examples.webservices.soap_handlers.global_handler;

import java.io.Serializable;

import javax.jws.HandlerChain;
import javax.jws.WebService;
import javax.jws.WebMethod;
import javax.jws.soap.SOAPBinding;

import weblogic.jws.WLHttpTransport;

@WebService(serviceName="HandlerChainService",
            name="HandlerChainPortType")

// HandlerConfig.xml ファイルでコンフィグレーションされる「SimpleChain」という
// 名前のハンドラ チェーンが、Web サービスのオペレーションが呼び出されるたびに
// 発動することを指定する、標準的な JWS アノテーション

@HandlerChain(file="HandlerConfig.xml", name="SimpleChain")

@SOAPBinding(style=SOAPBinding.Style.DOCUMENT,
             use=SOAPBinding.Use.LITERAL,
             parameterStyle=SOAPBinding.ParameterStyle.WRAPPED)

@WLHttpTransport(contextPath="HandlerChain", serviceUri="HandlerChain",
                 portName="HandlerChainServicePort")

/**
 * この JWS ファイルは、1 つのオペレーション sayHello を含む簡単な
 * Java クラス実装の WebLogic Web サービスの基本となる。この Web サービスにはまた、
 * @HandlerChain アノテーションで指定されているように、ハンドラ チェーンが
 * 関連付けられている
 * 
 * @author Copyright (c) 2005 by BEA Systems, Inc. All Rights Reserved.
 */

public class HandlerChainImpl  {

   public String sayHello(String input) {
     weblogic.utils.Debug.say( "in backend component. input:" +input );
     return "'" + input + "' to you too!";
   }

}

@HandlerChain アノテーションを使用する前に、前述の例に示すように、それを JWS ファイルにインポートする必要があります。

@HandlerChain アノテーションの file 属性を使用し、ハンドラ チェーンのコンフィグレーション情報を含む外部ファイルの名前を指定します。この属性の値は URL です。これは相対でも絶対でもかまいません。相対 URL は、ファイルをコンパイルするために jwsc Ant タスクを実行した時点での JWS ファイルの場所を基準とします。

Web サービスと関連付けるコンフィグレーション ファイル内のハンドラ チェーンの名前を指定するには、name 属性を使用します。この属性の値は、コンフィグレーション ファイル内の <handler-chain> 要素の name 属性に対応します。

外部コンフィグレーション ファイルの作成の詳細については、「ハンドラ チェーン コンフィグレーション ファイルの作成」を参照してください。

この節で説明した標準的な JWS アノテーションの詳細については、Web Services Metadata for the Java Platform 仕様を参照してください。

@javax.jws.soap.SOAPMessageHandlers

@javax.jws.soap.SOAPMessageHandlers (この節では簡単にするため @SOAPMessageHandlers とも言う) アノテーションを使用する場合、JWS ファイル自体の中で、Web サービスのオペレーションの前と後に実行する SOAP メッセージ ハンドラの配列を指定します (@SOAPMessageHandler アノテーションで指定)。@SOAPMessageHandler アノテーションには、ハンドラのクラス名、初期化パラメータ、ハンドラで処理される SOAP ヘッダのリストなどを指定する属性が含まれます。JWS ファイル自体の内部でハンドラのリストを指定するので、ハンドラ チェーンのコンフィグレーションは、Web サービス内に埋め込まれます。

以下の条件の 1 つ以上が適用される場合は、@SOAPMessageHandlers アノテーションを使用します。

次の JWS ファイルでは、@SOAPMessageHandlers アノテーションの簡単な使用例を示します。関連の Java コードは太字で示しています。

package examples.webservices.soap_handlers.simple;

import java.io.Serializable;

import javax.jws.soap.SOAPMessageHandlers;
import javax.jws.soap.SOAPMessageHandler;
import javax.jws.soap.SOAPBinding;
import javax.jws.WebService;
import javax.jws.WebMethod;

import weblogic.jws.WLHttpTransport;

@WebService(name="SimpleChainPortType",  
            serviceName="SimpleChainService")

// Web サービスのすべてのオペレーションの呼び出しの前と後に実行される 
// SOAP メッセージ ハンドラのリストを指定する標準的な JWS 
// アノテーション

@SOAPMessageHandlers ( {
  @SOAPMessageHandler (
   className="examples.webservices.soap_handlers.simple.ServerHandler1"),
  @SOAPMessageHandler (
   className="examples.webservices.soap_handlers.simple.ServerHandler2")
} )

@SOAPBinding(style=SOAPBinding.Style.DOCUMENT,
             use=SOAPBinding.Use.LITERAL,
             parameterStyle=SOAPBinding.ParameterStyle.WRAPPED)

@WLHttpTransport(contextPath="SimpleChain", serviceUri="SimpleChain",
                 portName="SimpleChainServicePort")

/**
 * この JWS ファイルは、1 つのオペレーション sayHello を含む簡単な
 * Java クラス実装の WebLogic Web サービスの基本となる。この Web サービスにはまた、
 * @SOAPMessageHandler/s アノテーションで指定されているように、ハンドラ チェーンが
 * 関連付けられている
 * 
 * @author Copyright (c) 2005 by BEA Systems, Inc. All Rights Reserved.
 */

public class SimpleChainImpl  {

   // デフォルトでは、すべてのパブリック メソッドがオペレーションとして公開される

   public String sayHello(String input)  {
     weblogic.utils.Debug.say( "in backend component. input:" +input );
     return "'" + input + "' to you too!";
   }
}

@SOAPMessageHandlers アノテーションおよび @SOAPMessageHandler アノテーションを使用する前に、前述の例に示すように、それらを JWS ファイルにインポートする必要があります。これらのアノテーションは、javax.jws.soap パッケージに入っています。

@SOAPMessageHandlers 配列で (@SOAPMessageHandler アノテーションを使用して) ハンドラをリストした順序により、ハンドラの実行の順序 (オペレーション前なら順序どおりに、オペレーション後なら逆順で) が指定されます。前述のサンプルでは、ハンドラ チェーンにおいて 2 つのハンドラをコンフィグレーションしています。これらのハンドラのクラス名は、examples.webservices.soap_handlers.simple.ServerHandler1 と examples.webservices.soap_handlers.simple.ServerHandler2 です。

@SOAPMessageHandler の initParams 属性を使用すると、特定のハンドラにおいて予期されている初期化パラメータの配列を指定できます。@InitParam 標準 JWS アノテーションを使用し、次の例のように、名前と値のペアを指定します。

@SOAPMessageHandler(
  className = "examples.webservices.soap_handlers.simple.ServerHandler1",
  initParams = { @InitParam(name="logCategory", value="MyService")} 
)

また、@SOAPMessageHandler アノテーションには、ハンドラによって実装される SOAP ロールをリストするための roles 属性、およびハンドラによって処理される SOAP ヘッダをリストするための headers 属性も含まれています。

この節で説明した標準的な JWS アノテーションの詳細については、Web Services Metadata for the Java Platform 仕様を参照してください。

ハンドラ チェーン コンフィグレーション ファイルの作成

JWS ファイルで @HandlerChain アノテーションを使用して、ハンドラ チェーンを Web サービスと関連付けることにした場合は、ハンドラ チェーン内のハンドラのリスト、それらの実行順、初期化パラメータなどを指定する外部コンフィグレーション ファイルを作成する必要があります。

このファイルは、JWS ファイルの外部にあるため、この単一のコンフィグレーション ファイルを複数の Web サービスで使用するようにコンフィグレーションし、エンタープライズ内のすべての Web サービスに関してハンドラ コンフィグレーション ファイルを標準化できます。加えて、すべての Web サービスを再コンパイルすることなく、ハンドラ チェーンのコンフィグレーションを変更できます。なお、非 SOAP の転送を使用するハンドラ チェーンにハンドラを入れた場合、@SOAPMessageHandler アノテーションではなく @HandlerChain アノテーションを使用することが必要となります。

コンフィグレーション ファイルは、次の簡単なサンプルに示すように、XML を使用して 1 つまたは複数のハンドラ チェーンをリストします。

<jwshc:handler-config xmlns:jwshc="http://www.bea.com/xml/ns/jws"
   xmlns:soap1="http://HandlerInfo.org/Server1"
   xmlns:soap2="http://HandlerInfo.org/Server2"
   xmlns="http://java.sun.com/xml/ns/j2ee" >
   <jwshc:handler-chain>
     <jwshc:handler-chain-name>SimpleChain</jwshc:handler-chain-name>
     <jwshc:handler>
       <handler-name>handler1</handler-name>
       <handler-class>examples.webservices.soap_handlers.global_handler.ServerHandler1</handler-class>
     </jwshc:handler>
     <jwshc:handler>
       <handler-name>handler2</handler-name>
       <handler-class>examples.webservices.soap_handlers.global_handler.ServerHandler2</handler-class>
     </jwshc:handler>
   </jwshc:handler-chain>
</jwshc:handler-config>

この例では、SimpleChain というハンドラ チェーンに、handler1 および handler2 という 2 つのハンドラが入っています。これらは <handler-class> 要素で指定されるクラス名で実装されます。2 つのハンドラは、関連の Web サービス オペレーションの前には昇順で実行され、オペレーション実行後には逆順で実行されます。

ハンドラ初期化パラメータ、ハンドラによって実装される SOAP ロール、およびハンドラによって処理される SOAP ヘッダを指定するには、それぞれ <handler> 要素の <init-param>、<soap-role>、および <soap-header> 子要素を使用します。

外部コンフィグレーション ファイルを定義する XML スキーマ、その作成に関する詳細、およびさらなるサンプルについては、Web Services Metadata for the Java Platform 仕様を参照してください。

Web サービスのコンパイルと再ビルド

この節では、Web サービスをコンパイルおよびビルドする作業用の build.xml Ant ファイルがあり、ハンドラ チェーンが含まれるように、そのビルド ファイルを更新すると仮定しています。この build.xml ファイルの作成については、「WebLogic Web サービスの反復的な開発」を参照してください。

メッセージ ハンドラのコンパイルとビルドが含まれるように開発環境を更新するには、以下のガイドラインに従います。