43.10. ハンドラーを使用するためのエンドポイントの設定
43.10.1. プログラムによる設定
43.10.1.1. コンシューマーへのハンドラーチェーンの追加
概要
ハンドラーチェーンをコンシューマーに追加するには、ハンドラーのチェーンを明示的に構築する必要があります。その後、サービスプロキシーの Binding
オブジェクトにハンドラーチェーンを直接設定します。
Spring の設定を使用して設定されたハンドラーチェーンは、プログラムで設定されたハンドラーチェーンをオーバーライドします。
手順
ハンドラーチェーンをコンシューマーに追加するには、次のようにします。
-
ハンドラーチェーンを保持する
List<Handler>
オブジェクトを作成します。 - チェーンに追加される各ハンドラーのインスタンスを作成します。
- インスタンス化された各ハンドラーオブジェクトを、ランタイムによって呼び出される順序でリストに追加します。
サービスプロキシーから Binding オブジェクトを取得します。
Apache CXF は、
org.apache.cxf.jaxws.binding.DefaultBindingImpl
というバインディングインターフェイスの実装を提供します。-
Binding オブジェクトの
setHandlerChain()
メソッドを使用して、プロキシーにハンドラーチェーンを設定します。
例
例43.14「コンシューマーへのハンドラーチェーンの追加」 は、ハンドラーチェーンをコンシューマーに追加するためのコードを示しています。
例43.14 コンシューマーへのハンドラーチェーンの追加
import javax.xml.ws.BindingProvider; import javax.xml.ws.handler.Handler; import java.util.ArrayList; import java.util.List; import org.apache.cxf.jaxws.binding.DefaultBindingImpl; ... SmallNumberHandler sh = new SmallNumberHandler(); List<Handler> handlerChain = new ArrayList<Handler>(); handlerChain.add(sh); DefaultBindingImpl binding = ((BindingProvider)proxy).getBinding(); binding.getBinding().setHandlerChain(handlerChain);
例43.14「コンシューマーへのハンドラーチェーンの追加」 のコードは、以下を行います。
ハンドラーをインスタンス化します。
チェーンを保持する List
オブジェクトを作成する。
ハンドラーをチェーンに追加します。
Binding オブジェクトを DefaultBindingImpl
オブジェクトとしてプロキシーから取得する。
ハンドラーチェーンをプロキシーのバインディングに割り当てます。
43.10.1.2. サービスプロバイダーへのハンドラーチェーンの追加
概要
SEI または実装クラスのいずれかに @HandlerChain
アノテーションを付けて、ハンドラーチェーンをサービスプロバイダーに追加します。注釈は、サービスプロバイダーが使用するハンドラーチェーンを定義するメタデータファイルを指します。
手順
ハンドラーチェーンをサービスプロバイダーに追加するには、次のようにします。
-
プロバイダーの実装クラスに
@HandlerChain
アノテーションを付けます。 - ハンドラーチェーンを定義するハンドラー設定ファイルを作成します。
@HandlerChain アノテーション
javax.jws.HandlerChain
アノテーションは、サービスプロバイダーの実装クラスに付けられます。アノテーションは、その file
プロパティーで指定されたハンドラーチェーンの設定ファイルを読み込むようにランタイムに指示します。
アノテーションの file
プロパティーは、読み込むハンドラーの設定ファイルを識別する 2 つの方法をサポートします。
- a URL
- 相対パス名
例43.15「ハンドラーチェーンをロードするサービスの実装」に、handlers.xml
と呼ばれるファイルに定義されたハンドラーチェーンを使用するサービスプロバイダーの実装を示します。handlers.xml
は、サービスプロバイダーが実行されるディレクトリーに存在する必要があります。
例43.15 ハンドラーチェーンをロードするサービスの実装
import javax.jws.HandlerChain;
import javax.jws.WebService;
...
@WebService(name = "AddNumbers",
targetNamespace = "http://apache.org/handlers",
portName = "AddNumbersPort",
endpointInterface = "org.apache.handlers.AddNumbers",
serviceName = "AddNumbersService")
@HandlerChain(file = "handlers.xml")
public class AddNumbersImpl implements AddNumbers
{
...
}
ハンドラー設定ファイル
ハンドラー設定ファイルは、JSR 109 (Web Services for Java EE、バージョン 1.2) に付属する XML 文法を使用してハンドラーチェーンを定義します。この文法は http://java.sun.com/xml/ns/javaee
で定義されます。
ハンドラー設定ファイルのルート要素は、handler-chains
要素です。handler-chains
要素には、1 つまたは複数の handler-chain
要素があります。
handler-chain
要素は、ハンドラーチェーンを定義します。表43.1「サーバーサイドハンドラーチェーンの定義に使用される要素」で、handler-chain
要素の子を説明します。
要素 | 説明 |
---|---|
ハンドラーを説明する要素が含まれています。 | |
ハンドラーチェーンがバインドされるサービスを定義する WSDL | |
ハンドラーチェーンがバインドされるエンドポイントを定義する WSDL | |
ハンドラーチェーンが使用されるメッセージバインディングを指定します。バインディングは、URI として指定するか、 メッセージバインディング URI の詳細については、23章Apache CXF バインディング ID を参照してください。 |
handler-chain
要素に必要なのは、子要素としての handler
1 つだけです。ただし、完全なハンドラーチェーンを定義するのに、handler
要素を必要な数だけサポートします。チェーン内のハンドラーは、ハンドラーチェーン定義で指定された順序で実行されます。
最終的な実行順序は、指定されたハンドラーを論理ハンドラーとプロトコルハンドラーに分類することによって決定されます。グループ内では、設定で指定された順序が使用されます。
protocol-binding
などの他の子は、定義されたハンドラーチェーンのスコープを制限するために使用されます。たとえば、service-name-pattern
要素を使用する場合、ハンドラーチェーンは WSDL port
要素が指定の WSDL service
要素の子であるサービスプロバイダーにのみ割り当てられます。handler
要素では、これらの制限用の子の 1 つしか使用できません。
handler
要素は、ハンドラーチェーンの個々のハンドラーを定義します。handler-class
子要素は、ハンドラーを実装するクラスの完全修飾名を指定します。handler
要素は、ハンドラーに一意の名前を指定するオプションの handler-name
要素を持つこともできます。
例43.16「ハンドラー設定ファイル」 は、単一のハンドラーチェーンを定義するハンドラー設定ファイルを示しています。チェーンは 2 つのハンドラーで設定されています。
例43.16 ハンドラー設定ファイル
<handler-chains xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee"> <handler-chain> <handler> <handler-name>LoggingHandler</handler-name> <handler-class>demo.handlers.common.LoggingHandler</handler-class> </handler> <handler> <handler-name>AddHeaderHandler</handler-name> <handler-class>demo.handlers.common.AddHeaderHandler</handler-class> </handler> </handler-chain> </handler-chains>
43.10.2. Spring の設定
概要
ハンドラーチェーンを使用するようにエンドポイントを設定する最も簡単な方法は、エンドポイントの設定でチェーンを定義することです。これは、jaxwxs:handlers
子要素をエンドポイントを設定する要素に追加して行います。
設定ファイルを介して追加されたハンドラーチェーンは、プログラムで設定されたハンドラーチェーンよりも優先されます。
手順
ハンドラーチェーンをロードするようにエンドポイントを設定するには、次のようにします。
エンドポイントに設定要素がまだない場合は、設定要素を追加します。
Apache CXF エンドポイントの設定の詳細については、17章JAX-WS エンドポイントの設定 を参照してください。
-
jaxws:handlers
子要素をエンドポイントの設定要素に追加します。 チェーンの各ハンドラーに対して、ハンドラーを実装するクラスを指定する
bean
要素を追加します。ハンドラー実装が複数の場所で使用される場合は、
ref
要素を使用してbean
要素を参照できます。
ハンドラー要素
jaxws:handlers
要素は、エンドポイントの設定でハンドラーチェーンを定義します。これは、すべての JAX-WS エンドポイント設定要素の子として表示できます。以下のとおりです。
-
jaxws:endpoint
はサービスプロバイダーを設定します。 -
jaxws:server
もサービスプロバイダーを設定します。 -
jaxws:client
はサービスコンシューマーを設定します。
次の 2 つの方法のいずれかで、ハンドラーをハンドラーチェーンに追加します。
-
実装クラスを定義する
bean
要素を追加する -
ref
要素を使用して、設定ファイルの他の場所から名前付きbean
要素を参照する
設定でハンドラーが定義される順序は、ハンドラーが実行される順序です。論理ハンドラーとプロトコルハンドラーを混在させると、順序が変更される場合があります。ランタイムは、設定で指定された基本的な順序を維持しながら、それらを適切な順序にソートします。
例
例43.17「Spring でハンドラーチェーンを使用するようにエンドポイントを設定する」 は、ハンドラーチェーンをロードするサービスプロバイダーの設定を示しています。
例43.17 Spring でハンドラーチェーンを使用するようにエンドポイントを設定する
<beans ... xmlns:jaxws="http://cxf.apache.org/jaxws" ... schemaLocation="... http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd ..."> <jaxws:endpoint id="HandlerExample" implementor="org.apache.cxf.example.DemoImpl" address="http://localhost:8080/demo"> <jaxws:handlers> <bean class="demo.handlers.common.LoggingHandler" /> <bean class="demo.handlers.common.AddHeaderHandler" /> </jaxws:handlers> </jaws:endpoint> </beans>