検索

A.7. JAX-WS Common API Reference

download PDF

JAX-WS の開発概念は、Web サービスのエンドポイントとクライアント間で共有されています。これには、ハンドラーフレームワーク、メッセージコンテキスト、および障害処理が含まれます。

ハンドラーフレームワーク

ハンドラーフレームワークは、クライアントおよびエンドポイント (サーバーコンポーネント) の JAX-WS プロトコルバインディングによって実装されます。バインディングプロバイダーとして知られるプロキシーおよび Dispatch インスタンスは、それぞれプロトコルバインディングを使用して抽象機能を特定のプロトコルにバインドします。

クライアントおよびサーバー側のハンドラーは、ハンドラーチェーンと呼ばれる順序付けされたリストに編成されます。ハンドラーチェーン内のハンドラーは、メッセージが送受信されるたびに呼び出されます。受信メッセージは、バインディングプロバイダーが処理する前にハンドラーによって処理されます。アウトバウンドメッセージは、バインディングプロバイダーが処理した後にハンドラーによって処理されます。

ハンドラーは、受信メッセージおよびアウトバウンドメッセージにアクセスして変更し、プロパティーのセットを管理するメソッドを提供するメッセージコンテキストで呼び出されます。メッセージコンテキストプロパティーは、ハンドラーとクライアントおよびサービスの実装間の通信だけでなく、個別のハンドラー間の通信を容易にします。異なるタイプのハンドラーは異なるタイプのメッセージコンテキストで呼び出されます。

論理ハンドラー
論理ハンドラーは、メッセージコンテキストプロパティーおよびメッセージペイロードでのみ動作します。論理ハンドラーはプロトコルに依存しないため、メッセージのプロトコル固有の部分には影響がありません。論理ハンドラーは、インターフェイス javax.xml.ws.handler.LogicalHandler を実装します。
プロトコルハンドラー
プロトコルハンドラーは、メッセージコンテキストプロパティーおよびプロトコル固有のメッセージで動作します。プロトコルハンドラーは特定のプロトコルに固有のもので、メッセージのプロトコル固有の側面にアクセスし、変更する可能性があります。プロトコルハンドラーは、javax.xml.ws.handler.LogicalHandler を除き、javax.xml.ws.handler.Handler から派生するインターフェイスを実装します。
サービスエンドポイントハンドラー

サービスエンドポイントでは、ハンドラーは @HandlerChain アノテーションを使用して定義されます。ハンドラーチェーンファイルの場所は、externalForm の絶対 java.net.URL か ソースファイルまたはクラスファイルからの相対パスのいずれかになります。

@WebService
@HandlerChain(file = "jaxws-server-source-handlers.xml")
public class SOAPEndpointSourceImpl {
   ...
}
サービスクライアントハンドラー

JAX-WS クライアントでは、ハンドラーはサービスエンドポイントの場合と同様に @HandlerChain アノテーションを使用するか、JAX-WS 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) のインスタンスに対するすべてのハンドラーで利用できます。たとえば、論理ハンドラーがプロパティーをメッセージコンテキストに置いた場合、そのプロパティーは MEP インスタンスの実行中にチェーンの任意のプロトコルハンドラーでも利用できます。

注記

非同期メッセージ交換パターン (MEP) を使用すると、HTTP 接続レベルでメッセージを非同期に送受信できます。これを有効にするには、要求コンテキストに追加のプロパティーを設定します。

APPLICATION レベルでスコープ設定されているプロパティーは、クライアントアプリケーションおよびサービスエンドポイント実装でも利用可能になります。プロパティーの defaultscope のスコープは HANDLER です。

論理メッセージと SOAP メッセージは、異なるコンテキストを使用します。

論理メッセージコンテキスト
論理ハンドラーが呼び出されると、LogicalMessageContext タイプのメッセージコンテキストを受け取ります。LogicalMessageContextMessageContext を、メッセージペイロードを取得および変更するメソッドで拡張します。メッセージのプロトコル固有の側面へのアクセスは提供しません。プロトコルバインディングは、論理メッセージコンテキストを介して使用できるメッセージのコンポーネントを定義します。SOAP バインディングにデプロイされた論理ハンドラーは SOAP ボディーのコンテンツにアクセスできますが、SOAP ヘッダーにはアクセスできません。一方、XML/HTTP バインディングは論理ハンドラーがメッセージの XML ペイロード全体にアクセスできることを定義します。
SOAP メッセージコンテキスト
SOAP ハンドラーが呼び出されると、SOAPMessageContext を受け取ります。SOAPMessageContextMessageContext を SOAP メッセージペイロードを取得および変更するメソッドで拡張します。

障害処理

アプリケーションが SOAPFaultException またはアプリケーション固有のユーザー例外を出力する可能性があります。後者の場合、必要な障害ラッパー Bean がデプロイメントに含まれていない場合は、ランタイム時に生成されます。

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 アノテーション

JAX-WS API で使用できるアノテーションは JSR-224 で定義されます。これらのアノテーションは javax.xml.ws パッケージにあります。XML Web Services の Jakarta EE と同等の Jakarta EE は、Jakarta XML Web Services Specification 2.3 仕様 です。

JWS API で使用できるアノテーションは JSR-181 で定義されます。これらのアノテーションは javax.jws パッケージにあります。Web Services Metadata の Jakarta EE と同等のものは、Jakarta Web Services Metadata Specification 2.1 仕様 に含まれています。

Red Hat logoGithubRedditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

Red Hat ドキュメントについて

Red Hat をお使いのお客様が、信頼できるコンテンツが含まれている製品やサービスを活用することで、イノベーションを行い、目標を達成できるようにします。

多様性を受け入れるオープンソースの強化

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。このような変更は、段階的に実施される予定です。詳細情報: Red Hat ブログ.

会社概要

Red Hat は、企業がコアとなるデータセンターからネットワークエッジに至るまで、各種プラットフォームや環境全体で作業を簡素化できるように、強化されたソリューションを提供しています。

© 2024 Red Hat, Inc.