SEI ベースの JAX-WS Web サービスでのメソッドの公開

サービス・エンドポイント実装で @WebService アノテーションおよび @WebMethod アノテーションを使用して、Java™ API for XML-Based Web Services (JAX-WS) Web サービスとして公開したい Java メソッドを指定することができます。

始める前に

JAX-WS テクノロジーにより、標準サービス・エンドポイント・インターフェースとプロバイダー・インターフェースの両方に基づいた Web サービスの実装が可能になります。既存の Java クラスから始めて JAX-WS Web サービスを開発する場合は (ボトムアップ・アプローチと呼ばれています)、最初にクラスを Web サービスとして定義するために、クラスに @WebService または @WebServiceProvider のいずれかのアノテーションを付ける必要があります。

プロバイダー・インターフェースを使用して JAX-WS サービスを定義する方法は、 ダイナミック・アプローチです。プロバイダー・インターフェースを使用するには、 クラスに javax.xml.ws.Provider インターフェースが実装されており、 @WebServiceProvider アノテーションが含まれている必要があります。プロバイダー・インターフェースには、 invoke メソッドという 1 つのメソッドがあります。 これは、さまざまなメッセージまたはメッセージ・ペイロードを処理する際に Java プログラミング言語の総称を使用して 入力タイプと出力タイプの両方を制御します。

このアプローチとは対照的に、サービス・エンドポイント・インターフェース (SEI) アプローチを使用して、Java アノテーションにより Web サービスを記述できます。

このタスクについて

最初に Web サービスを定義するには、Java クラスに @WebService アノテーションを付けます。メソッドを個々に選択して @WebMethod アノテーションを 付け、これらのメソッドの Web サービス操作としての公開を制御することもできます。

メソッドを操作として公開する方法に関して、複数の Web サービス仕様間であいまいな部分があるため、以下のガイドラインを使用して、使用する JAX-WS 実装に関係なく一貫性のある動作になるようにしてください。

  • 基本 Web サービスを定義する場合は、実装クラスに @WebService アノテーションを付けます。
  • 明示的な SEI を使用して Web サービスを定義する場合は、@WebService アノテーション の endpointInterface 属性を使用して、Java インターフェース・クラスを明示的に参照します。
  • @WebService アノテーションの wsdlLocation 属性で、WSDL ファイルへの参照を指定します。 定義済みの WSDL ファイルを指定することにより、パフォーマンスが向上します。 また、WSDL ファイルとアノテーションとの不一致は、ランタイム環境により、 ユーザーに報告されます。
    トラブルの回避 (Avoid trouble) トラブルの回避 (Avoid trouble): JAX-WS 2.2 仕様では、SOAP 1.2 はバインディング・タイプとして宣言され、wsdlLocation 属性は空ストリング (デフォルト) である場合、コンテナーは WSDL を自動的に生成できません。そのため、?wsdl を使用して WSDL ファイルを要求した場合、以下の例外メッセージが表示されます。
    CWWKW0037E: The WSDL that is compliant with the JAX-WS 2.2 specification cannot be generated.
    WSDL ファイルを表示する場合は、WSDL ファイルを手動で生成してアプリケーションに配置し、正しい場所を使用して wsdlLocation 属性を指定する必要があります。gotcha
  • 明示的な SEI を使用すると、SEI のすべての public メソッド および継承クラスは常に公開されます。既に公開済みのメソッドをさらにカスタマイズしたい場合は、 @WebMethod アノテーションを追加するだけでカスタマイズできます。
  • @WebService アノテーションで明示的な SEI への参照、または既存の WSDL ファイルへの参照を 指定することにより、メソッド公開時にあいまいさが生じないようにすることができます。
  • 明示的な SEI を使用しない場合は、以下のルールに従って、メソッドが一貫して公開されるようにしてください。
    • 公開したいメソッドが含まれている実装クラスおよびそのすべてのスーパークラス に @WebService アノテーションを追加します。クラスに @WebService アノテーションを追加すると、 そのクラス内の static でも final でもないすべての public メソッドが公開されます。
    • より細かく制御して特定のメソッドのみを公開したい場合は、 メソッドを選択して @WebMethod アノテーションを付けることができます。 メソッドが必ず公開されるようにするには、 そのメソッドに @WebMethod アノテーションを付けます。 メソッドが公開されないようにするには、そのメソッドに @WebMethod(exclude=true) アノテーションを付けます。
サポートされる構成 サポートされる構成: sptcfg
アノテーションを付けていないメソッドの公開に関する動作の変更点

Web サービス操作としてのメソッドの公開に関する JAX-WS の動作が変更されました。 これは、新しく明確化された JAX-WS 仕様に従って変更されました。

前のバージョンからマイグレーションされた、明示的な SEI または WSDL がないアプリケーションでは、以下に示されているような追加の操作が公開される場合があります。JAX-WS ランタイム環境が既存の動作を使用するようにプロパティーを設定することができます。 WSDL または SEI がないアプリケーションをマイグレーションする際に、 追加メソッドが公開されないようにするためには、このプロパティーが必要になることがあります。

@WebService
public class Foo {
	@WebMethod
		public void a() {}	// exposed now, exposed before
		public void b() {}	// exposed now, not exposed before
}
新しい解釈では、実装クラスおよびそのスーパークラスの public メソッドは、以下の条件にあてはまる場合にのみ公開されます。
  • 含まれているクラスに @WebService アノテーションがある。
  • メソッドに @WebMethod(exclude=true) アノテーションがない。
既存の解釈では、実装クラスおよびそのスーパークラスのメソッドは、 以下の条件にあてはまる場合にのみ公開されます。
  • 含まれているクラスに @WebService アノテーションがある。
  • メソッドに @WebMethod アノテーションがなく、 その他のメソッドにも @WebMethod アノテーションがない。
  • メソッドに @WebMethod アノテーションまたは @WebMethod(exclude=false) アノテーションがある。

JAX-WS ランタイム環境が既存の @WebMethod の動作を使用するように指定するには、 jaxws.runtime.legacyWebMethod=true プロパティーを設定します。 このプロパティーを Java 仮想マシン (JVM) システム・プロパティー として、または Web アプリケーション・アーカイブ (WAR) ファイルの META-INF/MANIFEST.MF ファイル内のプロパティーとして構成することができます。デフォルトでは、このプロパティーは false に設定されており、 アプリケーション・サーバーは新しい動作を使用します。

以下の条件がすべて該当する場合は、WSWS7054E エラー・メッセージが表示されることがあります。
  • Web サービス・アプリケーションがアノテーションなしのメソッドで構成されている。
  • メソッドが、Web サービス・オペレーションにマップされるようになっていない。
  • アプリケーションが、SEI を参照することもなく、WSDL ファイルをパッケージすることもない。
エラー・メッセージには、次のようなテキストの情報が含まれます。
javax.xml.ws.WebServiceException: WSWS7054E:
 The Web Services Description Language (WSDL) file could not be generated for the XXXX Web service implementation
 class because of the following error: javax.xml.ws.WebServiceException: Unable to create JAXBContext
JAX-WS ツールは、JAX-WS 仕様に準拠していて @WebMethod マッピング原則に従います。 この変更によって、準拠していないこれまでのデフォルト動作に依存しているアプリケーションに影響が及ぶ可能性があります。 使用しているアプリケーションが WSDL や SEI をパッケージおよび参照し、SEI 実装ですべてのメソッドが @WebMethod exclude フラグによって適切にアノテーションが付いている場合には、この変更は影響を及ぼしません。 ただし、影響を受ける場合には、WSDL 生成でそうしたメソッドが除外されるように、明示的にアノテーションをメソッドに追加します。 例えば、@WebMethod(exclude=true) などとします。 また、ランタイムがユーザーのために WSDL を生成する必要がなくなるように、アプリケーションで WSDL をパッケージ化することもできます。
static メソッドおよび final メソッドの公開に関する動作の変更点

明示的な SEI がないサービス内の static メソッドまたは final メソッドは、 Web サービス操作として公開されなくなりました。これらのメソッドを公開する場合は、 WSDL をアプリケーションにパッケージし、jaxws.runtime.legacyWebMethod=true を設定してください。

手順

  1. Web サービス操作として公開したいメソッドを識別します。
  2. @WebService アノテーションが付けられたクラスで、メソッドを操作として公開する ためのルールを検討します。
  3. Web サービス内でメソッドを操作として適切に公開するために、 SEI がないアプリケーションに @WebMethod アノテーションおよび @WebService アノテーションを適用するためのベスト・プラクティスを使用します。

タスクの結果

@WebMethod アノテーションを使用して、Web サービス操作として公開するメソッドを指定しました。

トラブルの回避 (Avoid trouble) トラブルの回避 (Avoid trouble):

アプリケーション・サーバー環境をアップグレードし、 問題が発生している場合は、以下のトラブルシューティング情報をお読みください。

JAX-WS ツールのバージョン 2.1.6 以上の環境を使用している場合に、 WSDL ファイルと portType の不一致を示すクライアント・エラーが発生する
以下のようなクライアント・サイド・エラー・メッセージを受け取ることがあります。
javax.xml.ws.WebServiceException: 次のエラーのためにエンドポイント検証に失敗しました:
:: エンドポイント・インターフェースが無効です (Invalid Endpoint Interface) ::
:: The number of operations in the WSDL portType does not match the number of methods in the SEI or web service
 implementation class.  WSDL の操作 = [...] ディスパッチ操作 = [....] (wsdl operations = [...] dispatch operations = [....])

この問題を修正するには、 WSDL ファイルに一致するようにクライアント成果物を再生成する必要があります。

ベスト・プラクティス ベスト・プラクティス: 更新された WSDL ファイルを受信したら、必ずクライアント・サイドの成果物を再生成してください。bprac
Web サービスで ?WSDL 操作を実行するクライアントにディスパッチ不可の操作がある
?WSDL 操作の実行後、JAX-WS ランタイム環境がディスパッチできる操作よりも多くの操作を含む WSDL ファイルを受け取ることがあります。クライアントが、ディスパッチ不可の操作を呼び出そうとすると、 以下のようなエラー・メッセージを受け取ります。
操作が見つからないエンドポイント参照 (EPR): http://localhost:9086/example/BeanImpl2Service
WSA アクション = <WSA_action_from_server> です。この EPR が以前は到達可能であった場合は、サーバー管理者に連絡してください。(If this EPR was previously reachable, contact the server administrator.)
クライアントは、Web サービスが公開しようとする操作にアクセスする必要があります。この問題は、以下のいずれかの方法で修正できます。
  • 生成される WSDL ファイルで正しい操作セットが公開されるように、Web サービス・アプリケーション内の @WebMethod アノテーションを変更します。
  • jaxws.runtime.legacyWebMethod プロパティー を false に設定して、WSDL 内のすべての操作がディスパッチされるようにします。
gotcha

トピックのタイプを示すアイコン タスク・トピック



タイム・スタンプ・アイコン 最終更新: last_date
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twbs_devjaxws_exposewebmethod
ファイル名:twbs_devjaxws_exposewebmethod.html