WebSphere Application Server Version 6.1 Feature Pack for Web Services   
             オペレーティング・システム: AIX , HP-UX, i5/OS, Linux, Solaris, Windows, Windows Vista, z/OS

             目次と検索結果のパーソナライズ化
             New or updated topic for this feature pack

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> インターフェースを実装します。

このタスクについて

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 アノテーションを使用するハンドラーのサーバー実装の場合とクライアント実装の場合は、ともに、ハンドラー構成ファイルは、サービス・エンドポイント・インターフェースのクラスパスになければなりません。 ハンドラー構成ファイルのスキーマについて詳しくは、 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 サービス・アプリケーションをデプロイします。



関連概念
JAX-WS
JAX-WS クライアント・プログラミング・モデル
関連タスク
JavaBeans からの Web サービス・アプリケーションの開発
Web サービス・クライアントの開発とデプロイ
関連資料
JAX-WS のアノテーション
Web サービス仕様と API
関連情報
Java API for XML Web Services (JAX-WS) API documentation
Java API for XML Web Services (JAX-WS) API User's Guide documentation
タスク・トピック    

ご利用条件 | フィードバック

最終更新: Jan 21, 2008 4:10:06 PM EST
http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/index.jsp?topic=/com.ibm.websphere.wsfep.multiplatform.doc/info/ae/ae/twbs_jaxwshandler.html