13.5.2. JAX-WS の共通 API リファレンス
ハンドラーフレームワークは JAX-WS プロトコルバインディングにより、サーバーコンポーネントであるクライアントおよびエンドポイントのランタイムに実装されます。プロキシおよび Dispatch のインスタンスは、バインディングプロバイダー と総称されており、それぞれがプロトコルバインディングを使用して抽象機能を特定のプロトコルにバインドします。
メッセージハンドラーのタイプ
- 論理ハンドラー
- 論理ハンドラー はメッセージコンテキストプロパティーおよびメッセージペイロードでのみ動作します。論理ハンドラーはプロトコル非依存なので、メッセージのプロトコル固有の部分に影響を与えることはできません。論理ハンドラーはインターフェース
javax.xml.ws.handler.LogicalHandlerを実装します。 - プロトコルハンドラー
- Protocol handlers はメッセージコンテキストおよびプロトコル固有のメッセージでのみ動作します。プロトコルハンドラーは特定のプロトコルに固有で、プロトコル固有のメッセージアスペクトにアクセスし、変更することが可能です。 プロトコルハンドラーは
javax.xml.ws.handler.Handler except javax.xml.ws.handler.LogicalHandlerから派生する任意のインターフェースを実装します。 - サービスエンドポイントハンドラー
- サービスエンドポイントでは、ハンドラーは
@HandlerChainアノテーションを使用して定義されます。ハンドラーチェーンファイルのロケーションは、externalForm内の絶対java.net.URL、あるいはソースファイル/クラスファイルからの相対パスで指定することができます。例13.30 サービスエンドポイントハンドラーの例
@WebService @HandlerChain(file = "jaxws-server-source-handlers.xml") public class SOAPEndpointSourceImpl { ... } - サービスクライアントハンドラー
- JAX-WS クライアントでは、ハンドラーは サービスエンドポイント同様に
@HandlerChainアノテーションを使用するか、動的に JAX-WS API を使用して定義します。例13.31 API を使用したサービスクライアントハンドラーの定義
Service service = Service.create(wsdlURL, serviceName); Endpoint port = (Endpoint)service.getPort(Endpoint.class); BindingProvider bindingProvider = (BindingProvider)port; List<Handler> handlerChain = new ArrayList<Handler>(); handlerChain.add(new LogHandler()); handlerChain.add(new AuthorizationHandler()); handlerChain.add(new RoutingHandler()); bindingProvider.getBinding().setHandlerChain(handlerChain);setHandlerChainメソッドへのコールが必要です。
MessageContext インターフェースは、全 JAX-WS メッセージコンテキスト用のスーパーインターフェースです。追加のメソッドと定数を使用して Map<String,Object> を拡張し、ハンドラーチェーン内のハンドラーが処理関連の状態を共有できるようにするプロパティセットを管理します。たとえば、ハンドラーは put メソッドを使用してメッセージコンテキストにプロパティを挿入することができます。その後、ハンドラーチェーン内の単一または複数のハンドラーは、 get メソッドでメッセージを取得できるようになります。
APPLICATION または HANDLER としてスコープ指定されます。すべてのプロパティは、特定のエンドポイントの メッセージ交換パターン (MEP) のインスタンスの全ハンドラーが使用することができます。たとえば、論理ハンドラーがメッセージコンテキストにプロパティを挿入すると、そのプロパティは、MET インスタンスの実行中にチェーン内の任意のプロトコルハンドラーも使用することができます。
注記
APPLICATION レベルにスコープ指定されているプロパティはクライアントアプリケーションとサービスエンドポイントの実装でも使用することができます。プロパティの defaultscope は HANDLER です。
- 論理メッセージコンテキスト
- 論理ハンドラーが呼び出される際には、タイプ
LogicalMessageContextのメッセージコンテキストを受信します。LogicalMessageContextは、メッセージペイロードを取得/変更するメソッドを使用してMessageContextを拡張します。これは、メッセージのプロトコル固有のアスペクトへのアクセスは提供しません。プロトコルバインディングは、論理メッセージコンテキストを介して使用可能なメッセージコンポーネントを定義します。SOAP バインディングにデプロイされている論理ハンドラーは、SOAP ボディーのコンテンツにアクセス可能ですが、SOAP ヘッダーにはアクセスできません。一方、XML/HTTP バインディングは論理ハンドラーがメッセージの XML ペイロード全体にアクセスできることを定義します。 - SOAP メッセージコンテキスト
- SOAP ハンドラーが呼び出される際には、
SOAPMessageContextを受信します。SOAPMessageContextは SOAP メッセージペイロードを取得/変更するメソッドを使用してMessageContextを拡張します。
アプリケーションは SOAPFaultException またはアプリケーション固有のユーザー例外をスローします。後者の場合、必要とされる障害ラッパー (fault wrapper) Bean が既にデプロイメントの一部となっていなければ、ランタイムに生成されます。
例13.32 フォルトハンドリングの例
public void throwSoapFaultException()
{
SOAPFactory factory = SOAPFactory.newInstance();
SOAPFault fault = factory.createFault("this is a fault string!", new QName("http://foo", "FooCode"));
fault.setFaultActor("mr.actor");
fault.addDetail().addChildElement("test");
throw new SOAPFaultException(fault);
}
public void throwApplicationException() throws UserException
{
throw new UserException("validation", 123, "Some validation error");
}
JAX-WS API で使用可能なアノテーションは JSR-224 で定義されています。この定義は http://www.jcp.org/en/jsr/detail?id=224 に記載されています。これらのアノテーションは javax.xml.ws パッケージに含まれています。
javax.jws パッケージに含まれています。
