静的 JAX-WS Web サービス・クライアントの実装

Web Services for Java™ Platform, Enterprise Edition (Java EE) 仕様および Java API for XML-Based Web Services (JAX-WS) プログラミング・モデルに基づいて、静的 Web サービス・クライアントを開発することができます。

始める前に

ベスト・プラクティス ベスト・プラクティス: IBM® WebSphere® Application Server は、 Java API for XML-Based Web Services (JAX-WS) プログラミング・モデルおよび Java API for XML-based RPC (JAX-RPC) プログラミング・モデルをサポートします。 JAX-WS は、JAX-RPC プログラミング・モデルが提供する基盤を拡張する、次世代の Web サービス・プログラミング・モデルです。戦略的 JAX-WS プログラミング・モデルを使用すると、標準ベースの注釈モデルのサポートによって、Web サービスおよび Web クライアントの開発が容易になります。JAX-RPC プログラミング・モデルとアプリケーションは引き続きサポートされますが、Web サービス・アプリケーションおよびクライアントを新規に開発する場合は、実装が容易な JAX-WS プログラミング・モデルをご利用ください。bprac

このタスクについて

JAX-WS プログラミング・モデルに基づく Web サービス・クライアントの開発

JAX-WS Web サービスのアクセスと呼び出しの両方ができる Web サービス・クライアントは、Web Services for Java Platform, Enterprise Edition (Java EE) 仕様に基づいて開発されます。アプリケーション・サーバーは、 JAX-WS プログラミング・モデルに基づいた Enterprise JavaBeans (EJB) クライアント、Java EE アプリケーション・クライアント、JavaServer Pages (JSP) ファイルとサーブレットをサポートしています。 JAX-RPC 仕様に基づく Web サービス・クライアントは、 Web サービス記述言語 (WSDL) ファイルが Web Services-Interoperability (WS-I) Basic Profile に準拠している場合は、JAX-WS ベースの Web サービスを呼び出すことができます。

JAX-WS クライアント・プログラミング・モデルは、ディスパッチ・クライアント API と、動的プロキシー・クライアント API の両方をサポートします。 ディスパッチ・クライアント API が動的クライアント・プログラミング・モデルであるのに対して、 動的プロキシー・クライアントは JAX-WS の静的クライアント・プログラミング・モデルです。 ディスパッチおよび動的プロキシー・クライアントは、 JAX-WS Web サービスの同期呼び出しと非同期呼び出しの両方を使用可能にします。

動的プロキシー・クライアントは、提供されるサービス・エンドポイント・インターフェース (SEI) に基づく Web サービスを呼び出します。 JAX-WS 動的プロキシー・インスタンスは、 基本 Java SE Runtime Environment (JRE) 6 の動的プロキシー機能を活用します。静的クライアントを開発する場合は、WSDL ファイルから始める必要があります。

これに対して、ディスパッチ・クライアント API の javax.xml.ws.Dispatch は、XML メッセージング指向クライアントで、 XML 構成体を使用したい上級 XML 開発者向けです。 ディスパッチ API は、PAYLOAD モードまたは MESSAGE モードのいずれかでデータを送信できます。 PAYLOAD モードを使用する場合、ディスパッチ・クライアントは soap:Body の内容の提供を担当します。 さらに、JAX-WS には soap:Envelope エレメントのペイロードが含まれています。 MESSAGE モードを使用する場合、 ディスパッチ・クライアントは SOAP エンベロープ全体の提供を担当します。動的クライアントを 開発する場合には、WSDL ファイルは必要ありません。

JAX-WS プログラミング・モデルに基づいた Web サービス・クライアントを開発するには、 Web サービス・アプリケーションのニーズに最適なクライアント・モデルを決定する必要があります。 Web サービス・クライアントに、サービス・エンドポイント・インターフェースに基づくサービスを動的プロキシーを使用して呼び出させる場合は、 動的プロキシー API を使用して静的 Web サービス・クライアントを開発します。 プロキシーが作成された後、クライアント・アプリケーションは、 サービス・エンドポイント・インターフェースの標準実装のように、これらのプロキシーでメソッドを呼び出すことができます。 ただし、Java 抽象ではなく XML を直接操作し、メッセージ構造またはメッセージ・ペイロード構造のいずれかを操作したい場合は、 ディスパッチ API を使用して動的 Web サービス・クライアントを開発します。動的 Web サービス・クライアント の開発方法について詳しくは、動的 JAX-WS Web サービス・クライアントの実装に関する説明をお読みください。

このタスクを完了して、WSDL ファイルで開始する静的 Web サービス・クライアントを開発します。

静的または動的 JAX-WS クライアントを使用して Web サービスを非同期に呼び出すには、 実装するのがコールバック・モデルであるのか、ポーリング・モデルであるのかを決定します。 Web サービス・クライアントに対する非同期コールバックまたはポーリングの実装について詳しくは、 JAX-WS Web サービスの非同期呼び出しを参照してください。 サービスおよびクライアントに関する JAX-WS プログラミング・モデルでは、アノテーションを使用して、 ベンダー中立の方法で JAX-RPC クライアント・バインディングで提供された同一情報を表します。

管理対象および管理対象外 JAX-WS Web サービス・クライアント

アプリケーション・サーバーは、JAX-WS プログラミング・モデルを使用する場合、管理対象と管理対象外の両方の Web サービス・クライアントをサポートします。

  • 管理対象クライアント

    Java EE クライアント用 Web サービスのクライアントは Java Specification Requirements (JSR) 109 により定義され、管理対象クライアントとなります。これは、これらのクライアントが Java EE コンテナー内で稼働するためです。これらのクライアントは、エンタープライズ・アーカイブ (EAR) ファイルとしてパッケージされており、サービス要求元として動作するコンポーネントが含まれています。 こうしたコンポーネントは Java EE クライアント・アプリケーションであっても、サーブレットや JavaServer Pages (JSP) のような Web コンポーネントであっても、またはセッション Enterprise JavaBeans (EJB) であってもかまいません。Web サービスの管理対象クライアントでは JSR 109 API とデプロイメント情報を使用して Web サービスを検索し、呼び出します。

    管理対象クライアントの場合、 Java Naming and Directory Interface (JNDI) 検索を使用してサービスを検索するか、 アノテーションを使用して JAX-WS サービスまたはポートのインスタンスを挿入できます。UserName トークン Web Services Security、デジタル署名 Web Services Security、および Lightweight Third-Party Authentication (LTPA) トークン Web Services Security のセットアップ方法に関する資料を参照してください。以下に、JSR 109 準拠のコンテキスト検索のコード例を示します。

    InitialContext ctx = new InitialContext();
        FredsBankService service
    =(FredsBankService)ctx.lookup("java:comp/env/service/FredsBankService");
        FredsBank fredsBank = service.getFredsBankPort();
        long balance = fredsBank.getBalance();  

    @WebServiceRef アノテーション または @Resource アノテーションを使用して、管理対象クライアントを宣言できます。これらのアノテーションを 使用すると、JNDI 名前空間にバインドされているアノテーションで指定された タイプになります。また、フィールドまたはメソッドでアノテーションを使用すると、JAX-WS サービス またはポート・インスタンスの注入になります。クライアント・デプロイメント記述子で service-ref エントリーを宣言する代わりに、これらのアノテーション を使用できます。クライアント・デプロイメント記述子を使用して、JAX-RPC 管理対象クライアント と同様に JAX-WS 管理対象クライアントを宣言することもできます。また、デプロイメント記述子 を使用して、@WebServiceRef アノテーションおよび @Resource アノテーションで指定されている 情報をオーバーライドし、拡張することもできます。@WebServiceRef アノテーション を使用して、JAX-WS サービスまたはポート・インスタンスをバインドし、注入します。JAX-WS サービス・インスタンス をバインドして注入するには、@Resource アノテーションのみを使用します。これらのアノテーション のいずれかを使用した JAX-WS 管理対象クライアントの宣言は、特定のクラス・タイプでのみ サポートされています。このようなクラス・タイプには、JAX-WS エンドポイント実装クラス、JAX-WS ハンドラー・クラス、エンタープライズ Bean クラス、サーブレット・クラスなどがあります。

    以下の例では、@WebServiceRef アノテーションを使用して、 FredsBank のインスタンスを取得しています。
    @WebServiceRef(name=”service/FredsBankPort”, value=FredsBankService.class)
    FredsBank fredsBank;
    このクラスでは、fredsBank フィールドを 初期化する必要はありません。このフィールドは直接使用できます。
    long balance = fredsBank.getBalance();
    また、以下の例のように、@WebServiceRef アノテーションを使用して、JAX-WS サービス・クラスの インスタンスを取得することもできます。
    @WebServiceRef(name=”service/FredsBankService”)
    FredsBankService service;
    このクラスでは、service フィールドを 初期化する必要はありません。このフィールドは直接使用できます。
     FredsBank fredsBank = service.getFredsBankPort(); long balance = fredsBank.getBalance();
    @WebServiceRef アノテーション以外に、@Resource アノテーションを使用して、JAX-WS サービス・クラスの インスタンスを取得できます。例えば、以下のようにします。
    @Resource(name=”service/FredsBankService”, type=FredsBankService.class)
    FredsBankService service;
    これで、@WebServiceRef アノテーションとの場合と同様、 インスタンス化しないで service フィールドを使用できるようになりました。 例えば、以下のようになります。
    FredsBank fredsBank = service.getFredsBankPort(); long balance = fredsBank.getBalance();
    クラスでは、@Resource アノテーションまたは @WebServiceRef アノテーション を使用できます。この場合、以下の例のように、JNDI を使用して JAX-WS のサービスまたはポートを検索する 必要があります。
    @WebServiceRef(name=”service/FredsBankService”, type=FredsBankService”)
    public class J2EEClientExample {
    		…
    		…
    
    		public static void main(String[] args) {
    			…
    			…
    		InitialContext ctx = new InitialContext();
    FredsBankService service =(FredsBankService)ctx.lookup("java:comp/env/service/FredsBankService");
        	FredsBank fredsBank = service.getFredsBankPort();
        	long balance = fredsBank.getBalance();  
    	}
    	…
    }

    @WebServiceRef アノテーションおよび @Resource アノテーションの詳細については、 JSR-109、JSR-224、JSR-250、および Java Platform Enterprise Edition 5, (Java EE 5) の仕様を参照してください。

    前述したように、アノテーションまたは JNDI を 使用して JAX-WS のサービスおよびポートのインスタンスを取得する場合は、戻される オブジェクトをインスタンス化しないでください。インスタンス化すると、 管理対象外クライアント・インスタンスになります。以下に、 不適切な使用方法の例を示します。
    @WebServiceRef(name=”service/FredsBankService”)
    FredsBankService service;service = new FredsBankService(); // client becomes unmanaged.

    @WebServiceRef アノテーションまたは @Resource アノテーションによって宣言された JAX-WS 管理対象クライアント、およびクライアント・デプロイメント記述子で service-ref エントリーを使用して宣言されたクライアントには、 管理コンソールを使用して、これらのクライアントが使用するエンドポイント URL を指定できます。指定した URL によって、クライアントで使用される WSDL 文書のエンドポイント URL が オーバーライドされます。このエンドポイント URL の指定の詳細については、Web サービス・クライアント・バインディングの構成の資料を参照してください。

  • 管理対象外クライアント

    Java EE コンテナー内で稼働せずに、JAX-WS ランタイム環境を使用して Web サービスを呼び出す Java Platform, Standard Edition (Java SE 6) クライアントは、 管理対象外クライアントと呼ばれます。Web サービスの管理対象外クライアントは、 WSDL ファイルを直接検査し、JAX-WS API を使用して Web サービスの呼び出しを 作成することができる、独立型の Java クライアントです。これらのクライアントは、どのようなデプロイメント情報も含まない JAR ファイルとしてパッケージされます。

WebSphere Application Server バージョン 7.0 以降からは、Java EE 5 アプリケーション・モジュール (Web アプリケーション・モジュールのバージョン 2.5 以上、または EJB モジュールのバージョン 3.0 以上) は、JAX-WS のサービスとクライアントの識別のためにアノテーションのスキャンが実行されます。ただし、Java EE 5 より前のアプリケーション・モジュール (Web アプリケーション・モジュールの バージョン 2.4 以前、または EJB モジュールのバージョン 2.1 以前) では、 パフォーマンス上の理由から、デフォルトでは JAX-WS アノテーションがスキャンされません。 バージョン 6.1 Feature Pack for Web Services では、デフォルトの動作として、アプリケーションのインストール時に、JAX-WS サービスを識別するために Java EE 5 より前の Web アプリケーション・モジュールをスキャンし、サービス・クライアントを探索するために Java EE 5 より前の Web アプリケーション・モジュールおよび EJB モジュールをスキャンしていました。 WebSphere Application Server バージョン 7.0 以降のデフォルトの動作では、以前のリリースのフィーチャー・パックとの後方互換性を維持するために、アプリケーションのインストール時またはサーバーの始動時に Java EE 5 より前のモジュールでアノテーションをスキャンしないようになっているため、Web アプリケーション・アーカイブ (WAR) ファイルまたは EJB モジュールの META-INF/MANIFEST.MF で UseWSFEP61ScanPolicy プロパティーを構成するか、または Java 仮想マシンのカスタム・プロパティー com.ibm.websphere.webservices.UseWSFEP61ScanPolicy をサーバーで定義して、アプリケーションのインストール時およびサーバーの始動時にスキャンを要求するようにする必要があります。アノテーションのスキャンについて詳しくは、JAX-WS アノテーションに関する情報を 参照してください。

手順

  1. アクセスする Web サービス用の Web サービス記述言語 (WSDL) ファイルを取得します。

    WSDL ファイルは、E メールか Uniform Resource Locator (URL) を使用してサービス・プロバイダーから 取得するか、Universal Description, Discovery and Integration (UDDI) レジストリーで検索して取得できます。

  2. WSDL ファイルから JAX-WS クライアント成果物を開発します。
    1. 動的プロキシー API を使用する静的 JAX-WS Web サービス・アプリケーションの場合、wsimport コマンドを使用して、WSDL ファイルからクライアント成果物を開発します
    2. (オプション) JAX-WS クライアント・サイド・デプロイメント記述子を作成します。必要であれば、 application-client.xml、web.xml、または ejb-jar.xml の各クライアント・サイド・デプロイメント記述子を使用して、JAX-WS Web サービスのアノテーションに含まれている バインディング情報を拡張またはオーバーライドすることができます。
  3. クライアント実装を完了します。

    Web サービスの呼び出しに使用されるクライアント・アプリケーション・コードを作成します。

    JSR 109 仕様の第 4 章を参照してください。サポートされる標準および仕様の完全なリストについては、Web サービス仕様書および API 文書を参照してください。
    トラブルの回避 (Avoid trouble) トラブルの回避 (Avoid trouble):
    • クライアント・アプリケーションをサーバーにインストールする場合、WAR モジュールと EJB モジュールのいずれかに含める必要があります。共有ライブラリー・ファイルでは、JAX-WS クライアントのスキャンは行われません。このため、共有ライブラリー JAR ファイルはクライアント・アプリケーションのコンテナーとして使用できません。
    • クライアント・アプリケーションが JSR 109 クライアントに複数のスレッドを作成する場合、メタデータ (WebSphere Application Server 構成を含む) はスレッドにコピーされず、Global Security Handler は呼び出されません。
    gotcha
  4. (オプション) Web サービス対応クライアント Java アーカイブ (JAR) ファイルをエンタープライズ・アーカイブ (EAR) ファイルにアセンブルします。 Java EE クライアント・コンテナーで実行される JAX-WS Web サービス・クライアントを開発する場合、 このステップを実行します。
  5. (オプション) Web サービス対応クライアント Web アプリケーション・アーカイブ (WAR) ファイルをエンタープライズ・アーカイブ (EAR) ファイルにアセンブルします。 Java EE Web コンテナーで実行される JAX-WS Web サービス・クライアントを開発する場合、 このステップを実行します。
  6. (オプション) Web サービス・アプリケーションをデプロイします。 Java EE クライアント・コンテナーで実行される JAX-WS Web サービス・クライアントをデプロイする場合、 このステップを実行します。
  7. Web サービス対応 クライアント・アプリケーションをテストします。 管理対象外クライアント JAR ファイルまたは管理対象クライアント・アプリケーション をテストできます。

タスクの結果

Web サービス・クライアント・アプリケーションの作成とテストが完了しました。

次のタスク

Web サービス・アプリケーション・クライアントを開発し、そのクライアントが静的にバインドされた後、実装で使用されるサービス・エンドポイントは、開発プロセス中に使用した WSDL ファイルで識別されるものとなります。Web サービス・アプリケーションのインストール中、またはインストール後に、サービス・エンドポイントの変更が必要になる場合があります。管理対象クライアントの場合、 エンドポイントは、管理コンソールまたは wsadmin スクリプト・ツールを使用して変更できます。 管理対象外の JAX-WS Web サービス・クライアントの場合、 エンドポイントは、クライアント・アプリケーション内から変更できます。

また、Web サービス・クライアントの拡張を実装することにより、 Web サービスをカスタマイズすることもできます。これらの拡張の例としては、SOAP ヘッダーの値の 送受信、HTTP または Java Message Service (JMS) トランスポート・ヘッダーの送受信があります。 これらの拡張の詳細については、 Web サービス・クライアントの拡張の実装に関する説明を参照してください。


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



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