第43章 ハンドラーの作成

概要

JAX-WS は、メッセージ処理モジュールをアプリケーションに追加するための柔軟なプラグインフレームワークを提供します。ハンドラーと呼ばれるこれらのモジュールは、アプリケーションレベルのコードから独立しており、低レベルのメッセージ処理機能を提供できます。

43.1. ハンドラー: はじめに

概要

サービスプロキシーがサービスで操作を呼び出すと、操作のパラメーターが Apache CXF に渡され、そこでメッセージに組み込まれ、ネットワークに配置されます。サービスがメッセージを受信すると、Apache CXF はネットワークからメッセージを読み取り、メッセージを再構築してから、操作の実装を担当するアプリケーションコードに操作パラメーターを渡します。アプリケーションコードが要求の処理を終了すると、応答メッセージは、要求を発信したサービスプロキシーへのトリップ時に同様の一連のイベントを実行します。これは、図43.1「メッセージ交換パス」 に示されています。

図43.1 メッセージ交換パス

クライアントとサーバー間のメッセージ交換パス

JAX-WS は、アプリケーションレベルのコードとネットワークの間でメッセージデータを操作するためのメカニズムを定義します。たとえば、オープンネットワークを介して渡されるメッセージデータを独自の暗号化メカニズムを使用して暗号化することができます。データを暗号化および復号化する JAX-WS ハンドラーを作成できます。次に、ハンドラーをすべてのクライアントとサーバーのメッセージ処理チェーンに挿入できます。

図43.2「ハンドラーを使用したメッセージ交換パス」 に示すように、ハンドラーは、アプリケーションレベルのコードとメッセージをネットワークに配置するトランスポートコードの間を移動するチェーンに配置されます。

図43.2 ハンドラーを使用したメッセージ交換パス

ハンドラーは、トランスポートとアプリケーション層の間のメッセージエクスチェンジパスに配置されます

ハンドラーの種類

JAX-WS 仕様では、次の 2 つの基本的なハンドラータイプが定義されています。

  • 論理ハンドラー 論理ハンドラーは、メッセージペイロードとメッセージコンテキストに格納されているプロパティーを処理できます。たとえば、アプリケーションが純粋な XML メッセージを使用する場合、論理ハンドラーはメッセージ全体にアクセスできます。アプリケーションが SOAP メッセージを使用する場合、論理ハンドラーは SOAP 本体のコンテンツにアクセスできます。メッセージコンテキストに配置されない限り、SOAP ヘッダーまたは添付ファイルにアクセスすることはできません。

    論理ハンドラーは、ハンドラーチェーン上のアプリケーションコードの最も近くに配置されます。これは、メッセージがアプリケーションコードからトランスポートに渡されるときに最初に実行されることを意味します。ネットワークからメッセージを受信してアプリケーションコードに戻すと、論理ハンドラーが最後に実行されます。

  • プロトコルハンドラー プロトコルハンドラーは、ネットワークから受信したメッセージ全体と、メッセージコンテキストに格納されているプロパティーを処理できます。たとえば、アプリケーションが SOAP メッセージを使用する場合、プロトコルハンドラーは、SOAP 本体、SOAP ヘッダー、および添付ファイルのコンテンツにアクセスできます。

    プロトコルハンドラーは、ハンドラーチェーンのトランスポートの最も近くに配置されます。これは、ネットワークからメッセージを受信したときに最初に実行されることを意味します。アプリケーションコードからネットワークにメッセージが送信されると、プロトコルハンドラーが最後に実行されます。

    注記

    Apache CXF でサポートされている唯一のプロトコルハンドラーは、SOAP に固有のものです。

ハンドラーの実装

2 つのハンドラータイプの違いは非常に微妙であり、共通のベースインターフェイスを共有しています。共通の親子関係があるため、論理ハンドラーとプロトコルハンドラーは、次のような実装が必要な多くのメソッドを共有します。

  • handleMessage() handleMessage() メソッドは、すべてのハンドラーの中心的なメソッドです。これは、通常のメッセージの処理を担当するメソッドです。
  • handleFault() handleFault() は、障害メッセージを処理するメソッドです。
  • close() メッセージがチェーンの最後に到達すると、ハンドラーチェーンのすべての実行済みハンドラーで close() が呼び出されます。これは、メッセージ処理中に消費されたリソースをクリーンアップするために使用されます。

論理ハンドラーの実装とプロトコルハンドラーの実装の違いは、次の点にあります。

  • 実装されている特定のインターフェイス

    すべてのハンドラーは、ハンドラーインターフェイスから派生したインターフェイスを実装します。論理ハンドラーは、LogicalHandler インターフェイスを実装します。プロトコルハンドラーは、ハンドラーインターフェイスのプロトコル固有の拡張機能を実装します。たとえば、SOAP ハンドラーは SOAPHandler インターフェイスを実装します。

  • ハンドラーが利用できる情報の量

    プロトコルハンドラーは、メッセージの内容と、メッセージの内容とともにパッケージ化されているすべてのプロトコル固有の情報にアクセスできます。論理ハンドラーは、メッセージの内容にのみアクセスできます。論理ハンドラーには、プロトコルの詳細に関する知識がありません。

アプリケーションへのハンドラーの追加

アプリケーションにハンドラーを追加するには、次のことを行う必要があります。

  1. ハンドラーをサービスプロバイダー、コンシューマー、またはその両方で使用するかどうかを決定します。
  2. どのタイプのハンドラーがジョブに最も適切かを判断します。

  3. 適切なインターフェイスを実装します。

    論理ハンドラーを実装するには、「論理ハンドラーの実装」 を参照してください。

    プロトコルハンドラーを実装するには、「プロトコルハンドラーの実装」 を参照してください。

  4. ハンドラーを使用するようにエンドポイントを設定します。「ハンドラーを使用するためのエンドポイントの設定」を参照してください。