JAX-WS Web サービスでのハンドラーの使用

Java™ API for XML Web Services (JAX-WS) により、相互操作と移植が可能な Web サービスを開発するための標準的な方法が提供されます。JAX-WS ハンドラーを使用して、Web サービス要求または応答処理をカスタマイズします。

始める前に

構成するアプリケーションのエンタープライズ・アーカイブ (EAR) ファイルが必要です。 Thin Client for JAX-WS 環境で実行している場合は、EAR ファイルから開始する必要はありません。 ロギングまたはトレースなどのハンドラーが使用する場合には、 サーバー・アプリケーションまたはクライアント・アプリケーションのみ構成する必要があります。SOAP ヘッダー内の情報の送信などの他のハンドラーが使用する場合には、 クライアント・アプリケーションおよびサーバー・アプリケーションが、シンメトリック・ハンドラーを使用して構成されている必要があります。

EAR ファイルのモジュールには、構成するハンドラー・クラスが含まれていなければなりません。 ハンドラー・クラスは、 javax.xml.ws.handler.LogicalHandler<LogicalMessageContext> インターフェース または javax.xml.ws.handler.soap.SOAPHandler<SOAPMessageContext> インターフェースを実装します。
要確認: インバウンド SOAPMessage をインターセプトして操作する (添付ファイル・パーツを追加するなど) 場合、SOAPMessageContext の setmessage パーツを使用して、添付ファイルが SOAPMessageContext のパーツであるようにします。 このようにすると、JAX-WS ランタイムは最新の SOAPMessage にアクセスし、添付ファイル・パーツを正しく処理できるようになります。 以下の例では、このプロセスを示しています。
 SOAPMessage m = context.getMessage(); 
 AttachmentPart ap1 = m.createAttachmentPart(); 
 ap1.setContent("abc", "text/plain");           
 m.addAttachmentPart(ap1);
 context.setMessage(m);                       

このタスクについて

Java API for XML-based RPC (JAX-RPC) プログラミング・モデルのように、 JAX-WS プログラミング・モデルは、アプリケーション・ハンドラー機能を提供します。 この機能によって、インバウンド・フローまたはアウトバウンド・フローでメッセージを操作できます。 ハンドラーを JAX-WS ランタイム環境に追加して、要求および応答メッセージの追加処理を行うことができます。 ハンドラーは、情報の収集とロギング、セキュリティーまたは他の情報のメッセージへの追加など、さまざまな目的に使用できます。 SOAP ではサポートされない追加プロトコルをサポートするために、 JAX-WS はハンドラーに 2 つの異なる分類をしています。 ハンドラーの 1 つのタイプは、論理ハンドラーです。 この論理ハンドラーは、プロトコルに依存せず、Extensible Markup Language (XML) メッセージとしてフロー内のメッセージを取得することができます。 論理ハンドラーは、メッセージ・コンテキスト・プロパティーおよびメッセージ・ペイロードを操作します。 これらのハンドラーは、javax.xml.ws.handler.LogicalHandler インターフェースを実装している必要があります。 論理ハンドラーは、メッセージ情報の取得元として使用できる LogicalMessageContext オブジェクトを受信します。 論理ハンドラーは、SOAP ベース構成と XML/HTTP ベース構成の両方に存在させることができます。

第 2 のタイプのハンドラーは、プロトコル・ハンドラーです。 プロトコル・ハンドラーは、メッセージ・コンテキスト・プロパティーとプロトコル固有メッセージを操作します。 プロトコル・ハンドラーは、SOAP ベース構成のみを操作することができ、 javax.xml.ws.handler.soap.SOAPHandler インターフェースを実装している必要があります。 プロトコル・ハンドラーは、メッセージ・データを読み取るために、 メッセージを javax.xml.soap.SOAPMessage として受信します。

JAX-WS ランタイムは、サーバー・サイドのハンドラー・クラスとクライアント・サイドのハンドラー・クラスを区別しません。 JAX-WS ランタイムは、特定ハンドラーの handleMessage(MessageContext) メソッドまたは handleFault(MessageContext) メソッドが呼び出される際に、 インバウンド・フローとアウトバウンド・フローを区別しません。 サーバーまたはクライアントのハンドラーを構成し、これらのメソッド内に十分なロジックを実装して、 現行メッセージのインバウンドまたはアウトバウンドの方向を検出する必要があります。

ハンドラーを Web サービス・クライアント・アプリケーションで使用するには、@HandlerChain アノテーションをサービス・エンドポイント・インターフェースまたは生成されたサービス・クラスに追加し、ハンドラー・チェーン構成ファイルを付与する必要があります。@HandlerChain アノテーションには、 作成するハンドラー・チェーン構成ファイルを指すファイル属性も含まれています。 Web サービス・クライアント・アプリケーションの場合、バインディング API を使用して、ハンドラー・チェーンをプログラムで構成することできます。handlerchain クラスをプログラムで変更するには、 HandlerResolver メソッドのデフォルト実装またはカスタム実装のいずれかを使用します。

ハンドラーをサーバー・アプリケーションで使用するには、 @HandlerChain アノテーションをサービス・エンドポイント・インターフェースまたはエンドポイント実装クラスのいずれかに設定し、関連したハンドラー・チェーン構成ファイルを用意する必要があります。 サーバーのハンドラーは、 @HandlerChain アノテーションをサービス・エンドポイント実装または実装クラスに設定することでのみ構成できます。 ハンドラー・クラスは、サーバー・アプリケーションの EAR ファイルに含める必要があります。

@HandlerChain アノテーションを使用するハンドラーのサーバー実装の場合とクライアント実装の場合は、 アノテーションが付いたファイルからの相対パス、または完全な URL として、 ハンドラー構成のロケーションを指定する必要があります。以下に例を示します。
@HandlerChain(file="../../common/handlers/myhandlers.xml")
または
@HandlerChain(file="http://foo.com/myhandlers.xml")
ハンドラー構成ファイルのスキーマについて詳しくは、 JSR 181 仕様を参照してください。

JAX-WS ハンドラーについて詳しくは、 JAX-WS 仕様の第 9 章を参照してください。

手順

  1. JAX-WS ハンドラーをサービスに実装するのか、クライアントに実装するのかを決定します。
  2. クライアント・ハンドラーを構成するには、 サービス・インスタンスまたはサービス・エンドポイント・インターフェースに @HandlerChain アノテーションを設定します。あるいは、ハンドラー・チェーンをプログラムで変更して、 ハンドラー・チェーンを実行時にビルドする方法を制御することができます。 ハンドラー・チェーンをプログラムで変更することを選択した場合、 デフォルトのハンドラー・リゾルバーを使用するのか、サービス・インスタンスに登録されているハンドラー・リゾルバーのカスタム実装を使用するのかを決定する必要があります。 サービス・インスタンスは、バインディング・プロバイダーを作成するときにハンドラー・リゾルバーを使用します。 バインディング・プロバイダーが作成される場合、 サービスによって登録されているハンドラー・リゾルバーがハンドラー・チェーンの作成に使用され、 その後で、ハンドラー・チェーンがバインディング・プロバイダーの構成に使用されます。
    1. ハンドラー・リゾルバーのデフォルト実装を使用します。 ランタイムは、今では @HandlerChain アノテーションと、 HandlerResolver クラスのデフォルト実装を使用してハンドラー・チェーンをビルドします。 バインディングから既存のハンドラー・チェーンを取得し、ハンドラーを追加または除去し、 さらに変更したハンドラー・チェーンをバインディング・オブジェクトに返すことができます。
    2. ハンドラー・リゾルバーのカスタム実装を使用するためには、 カスタム HandlerResolver クラスをサービス・インスタンスに設定します。 ランタイムは、HandlerResolver クラスのカスタム実装を使用してハンドラー・チェーンをビルドします。 デフォルトのランタイム実装は使用されません。 このシナリオでは、カスタム HandlerResolver インスタンスがサービス・インスタンスに登録されると、 バインディングからハンドラー・チェーンを取得するときに、@HandlerChain アノテーションが読み取られなくなります。 バインディングから既存のハンドラー・チェーンを取得し、ハンドラーを追加または除去し、 さらに変更したハンドラー・チェーンをバインディング・オブジェクトに返すことができます。
  3. サーバー・ハンドラーを構成するには、 @HandlerChain アノテーションをサービス・エンドポイント・インターフェースまたは実装クラスに設定します。 @HandlerChain アノテーションをサービス・エンドポイント・インターフェースと実装クラスの両方に構成する場合、実装クラスが優先します。
  4. ハンドラー・チェーン構成 XML ファイルを作成します。 @HandlerChain が参照するハンドラー・チェーン構成 XML ファイルを作成する必要があります。
  5. @HandlerChain アノテーションを使用してサーバーまたはクライアントのハンドラーを構成するときは、 サービス・エンドポイント・インターフェースのクラスパスにハンドラー・チェーン構成 XML ファイルを追加します。 クラスパスには、構成 XML ファイルに含まれているハンドラー・クラスも含める必要があります。
  6. ハンドラー実装を作成します。

タスクの結果

JAX-WS Web サービスまたは Web サービス・クライアントがハンドラーを使用して要求および応答メッセージ交換の追加処理を実行できるようにしました。

以下の例は、@HandlerChain アノテーションを使用してサービス・エンドポイント・インターフェースに JAX-WS ハンドラーを構成する際に必要なステップを示しています。

@HandlerChain アノテーションには、 作成するハンドラー・チェーン構成 XML ファイルを指すファイル属性も含まれています。 次のファイルは、標準のハンドラー構成ファイルを示しています。 protocol-bindings エレメント、port-name-pattern エレメント、および service-name-pattern エレメントは、すべてフィルターであり、 ハンドラーを適用できるサービスを制限する目的に使用します。
<?xml version="1.0" encoding="UTF-8"?>

<jws:handler-chains xmlns:jws="http://java.sun.com/xml/ns/javaee">
<!-- Note:  The '*" denotes a wildcard. -->

		<jws:handler-chain name="MyHandlerChain">
				<jws:protocol-bindings>##SOAP11_HTTP ##ANOTHER_BINDING</jws:protocol-bindings>
				<jws:port-name-pattern 
              xmlns:ns1="http://handlersample.samples.ibm.com/">ns1:MySampl*</jws:port-name-pattern>
        <jws:service-name-pattern 
              xmlns:ns1="http://handlersample.samples.ibm.com/">ns1:*</jws:service-name-pattern>
				<jws:handler>
						<jws:handler-class>com.ibm.samples.handlersample.SampleLogicalHandler</jws:handler-class>
				</jws:handler>
				<jws:handler>
						<jws:handler-class>com.ibm.samples.handlersample.SampleProtocolHandler2</jws:handler-class>
				</jws:handler>
				<jws:handler>
						<jws:handler-class>com.ibm.samples.handlersample.SampleLogicalHandler</jws:handler-class>
				</jws:handler>
				<jws:handler>
						<jws:handler-class>com.ibm.samples.handlersample.SampleProtocolHandler2</jws:handler-class>
				</jws:handler>
		</jws:handler-chain>
	
</jws:handler-chains>

</jws:handler-chains>

handler.xml ファイルと、handler.xml ファイルに含まれるハンドラー・クラスがクラスパスに追加されている必要があります。

以下の例は、ハンドラー実装を示しています。
package com.ibm.samples.handlersample;

import java.util.Set;

import javax.xml.namespace.QName;
import javax.xml.ws.handler.MessageContext;
import javax.xml.ws.handler.soap.SOAPMessageContext;

public class SampleProtocolHandler implements
        javax.xml.ws.handler.soap.SOAPHandler<SOAPMessageContext> {

    public void close(MessageContext messagecontext) {
    }

    public Set<QName> getHeaders() {
        return null;
    }

    public boolean handleFault(SOAPMessageContext messagecontext) {
        return true;
    }

    public boolean handleMessage(SOAPMessageContext messagecontext) {
        Boolean outbound = (Boolean) messagecontext.get(MessageContext.MESSAGE_OUTBOUND_PROPERTY);
        if (outbound) {
            // Include your steps for the outbound flow.
        }
        return true;
    }

}

次のタスク

Web サービス・アプリケーションをデプロイします。

トピックのタイプを示すアイコン タスク・トピック



タイム・スタンプ・アイコン 最終更新: last_date
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twbs_jaxwshandler
ファイル名:twbs_jaxwshandler.html