Oracle® Fusion Middleware

Oracle WebLogic Server JAX-RPC Webサービスの開発

12c (12.2.1)

E69969-01(原本部品番号:E55165-01)

2015年10月

このドキュメントでは、ソフトウェア開発者を対象に、Java API for XML-based RPC (JAX-RPC)を使用してWebLogic Webサービスを開発する方法について説明します。

Oracle Fusion Middleware Oracle WebLogic Server JAX-RPC Webサービスの開発, 12c (12.2.1)

E69969-01

Copyright © 2013, 2015, Oracle and/or its affiliates.All rights reserved.

このソフトウェアおよび関連ドキュメントの使用と開示は、ライセンス契約の制約条件に従うものとし、知的財産に関する法律により保護されています。ライセンス契約で明示的に許諾されている場合もしくは法律によって認められている場合を除き、形式、手段に関係なく、いかなる部分も使用、複写、複製、翻訳、放送、修正、ライセンス供与、送信、配布、発表、実行、公開または表示することはできません。このソフトウェアのリバース・エンジニアリング、逆アセンブル、逆コンパイルは互換性のために法律によって規定されている場合を除き、禁止されています。

ここに記載された情報は予告なしに変更される場合があります。また、誤りが無いことの保証はいたしかねます。誤りを見つけた場合は、オラクル社までご連絡ください。

このソフトウェアまたは関連ドキュメントを、米国政府機関もしくは米国政府機関に代わってこのソフトウェアまたは関連ドキュメントをライセンスされた者に提供する場合は、次の通知が適用されます。

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government.

このソフトウェアもしくはハードウェアは様々な情報管理アプリケーションでの一般的な使用のために開発されたものです。このソフトウェアもしくはハードウェアは、危険が伴うアプリケーション(人的傷害を発生させる可能性があるアプリケーションを含む)への用途を目的として開発されていません。このソフトウェアもしくはハードウェアを危険が伴うアプリケーションで使用する際、安全に使用するために、適切な安全装置、バックアップ、冗長性(redundancy)、その他の対策を講じることは使用者の責任となります。このソフトウェアもしくはハードウェアを危険が伴うアプリケーションで使用したことに起因して損害が発生しても、オラクル社およびその関連会社は一切の責任を負いかねます。

OracleおよびJavaはOracle Corporationおよびその関連企業の登録商標です。その他の名称は、それぞれの所有者の商標または登録商標です。

Intel、Intel Xeonは、Intel Corporationの商標または登録商標です。すべてのSPARCの商標はライセンスをもとに使用し、SPARC International, Inc.の商標または登録商標です。AMD、Opteron、AMDロゴ、AMD Opteronロゴは、Advanced Micro Devices, Inc.の商標または登録商標です。UNIXは、The Open Groupの登録商標です。

このソフトウェアまたはハードウェア、そしてドキュメントは、第三者のコンテンツ、製品、サービスへのアクセス、あるいはそれらに関する情報を提供することがあります。適用されるお客様とOracle Corporationとの間の契約に別段の定めがある場合を除いて、Oracle Corporationおよびその関連会社は、第三者のコンテンツ、製品、サービスに関して一切の責任を負わず、いかなる保証もいたしません。適用されるお客様とOracle Corporationとの間の契約に定めがある場合を除いて、Oracle Corporationおよびその関連会社は、第三者のコンテンツ、製品、サービスへのアクセスまたは使用によって損失、費用、あるいは損害が発生しても一切の責任を負いかねます。

目次

タイトルおよび著作権情報

はじめに

- ドキュメントのアクセシビリティについて

- 表記規則

このガイドでの新しい情報

- 12c (12.2.1)の新機能と変更された機能

- 12c (12.1.3)の新機能と変更された機能

- 12c (12.1.2)の新機能と変更された機能

第I部 概要

1 JAX-RPC Webサービスの概要

2 JAX-RPC Webサービス開発者向けサンプル

- 簡単なHelloWorld Webサービスの作成

- サンプルHelloWorldImpl.java JWSファイル

- HelloWorldImpl.javaのサンプルAntビルド・ファイル

- ユーザー定義のデータ型を使用するWebサービスの作成

- サンプルBasicStruct JavaBean

- サンプルComplexImpl.java JWSファイル

- ComplexImpl.java JWSファイルのサンプルAntビルド・ファイル

- WSDLファイルからのWebサービスの作成

- サンプルWSDLファイル

- サンプルTemperaturePortType Java実装ファイル

- TemperatureServiceのサンプルAntビルド・ファイル

- Java SEクライアントからのWebサービスの呼出し

- サンプルJavaクライアント・アプリケーション

- Javaクライアント・アプリケーションをビルドするためのサンプルAntビルド・ファイル

- WebLogic WebサービスからのWebサービスの呼出し

- サンプルClientServiceImpl.java JWSファイル

- ClientServiceをビルドするためのサンプルAntビルド・ファイル

第II部 基本的なJAX-RPC Webサービスの開発

3 JAX-RPC Webサービスの開発

- WebLogic Webサービス・プログラミング・モデルの概要

- Webサービス機能用のドメイン構成

- Javaから開始するWebLogic Webサービスの開発: 主な手順

- WSDLファイルから開始するWebLogic Webサービスの開発: 主な手順

- 基本的なAnt build.xmlファイルの作成

- jwsc WebLogic WebサービスAntタスクの実行

- Webサービスの呼出しに使用されるトランスポートの指定

- WebLogic Webサービスのコンテキスト・パスの定義

- jwscの使用例

- wsdlc WebLogic WebサービスAntタスクの実行

- wsdlcで生成される途中まで作成済みのJWS実装クラス・ファイルの更新

- WebLogic Webサービスのデプロイとアンデプロイ

- wldeploy Antタスクを使用したWebサービスのデプロイ

- 管理コンソールを使用したWebサービスのデプロイ

- WebサービスのWSDLの参照

- 動的なWSDLで指定されたサーバー・アドレスの構成

- Webサービスがコールバック・サービスでなく、HTTP/Sを使用して呼び出せる場合

- Webサービスがコールバック・サービスでなく、JMSトランスポートを使用して呼び出せる場合

- Webサービスがコールバック・サービスである場合

- Webサービスがプロキシ・サーバーを使用して呼び出せる場合

- Webサービスのテスト

- WebサービスのWebLogic分割開発ディレクトリ環境への統合

4 JWSファイルのプログラミング

- JWSファイルとJWSアノテーションの概要

- JWSファイルのJava要件

- JWSファイルのプログラミング: 一般的な手順

- JWSファイルの例

- JWSファイルがWebサービスを実装することの指定(@WebServiceアノテーション)

- WebサービスとSOAPメッセージ・プロトコルのマッピングの指定(@SOAPBindingアノテーション)

- Webサービスのコンテキスト・パスとサービスURIの指定(@WLHttpTransportアノテーション)

- JWSメソッドをパブリック操作として公開することの指定(@WebMethodおよび@OneWayアノテーション)

- 操作のパラメータとWSDL要素のマッピングのカスタマイズ(@WebParamアノテーション)

- 操作の戻り値とWSDL要素のマッピングのカスタマイズ(@WebResultアノテーション)

- Webサービスの実行時情報へのアクセス

- JwsContextを使用した実行時情報へのアクセス

- Webサービス・コンテキストへのアクセスに関するガイドライン

- JwsContextのメソッド

- Stubインタフェースを使用した実行時情報へのアクセス

- ステートレス・セッションEJBを実装すべき場合

- JWSファイルでEJBを実装する場合のプログラミングのガイドライン

- EJBを実装するJWSファイルの例

- ユーザー定義のJavaデータ型のプログラミング

- 例外のスロー

- JWSファイルからの別のWebサービスの呼出し

- JWSアノテーションおよびAPIによるその他の機能のプログラミング

- MTOM/XOPを使用したバイナリ・データの送信

- SOAP添付ファイルのストリーミング

- SOAP 1.2の使用

- トランザクション内で実行する操作の指定

- HttpServletRequest/Responseオブジェクトの取得

- JWSプログラミングのベスト・プラクティス

5 データ・バインディングの理解

- データ・バインディングの概要

- サポートされる組込みデータ型

- 組込みデータ型のXML-to-Javaマッピング

- 組込みデータ型のJava-to-XMLマッピング

- サポートされるユーザー定義のデータ型

- サポートされるユーザー定義のXMLデータ型

- サポートされるユーザー定義のJavaデータ型

6 JAX-RPC Webサービス・クライアントの開発

- JAX-RPC Webサービス・クライアントの概要

- JAX-RPCを使用したWebサービスの呼出し

- Webサービスを呼び出すクライアントの例

- Java SEクライアントからのWebサービスの呼出し

- クライアントのアーティファクトを生成するためのclientgen Antタスクの使用

- Webサービスに関する情報の取得

- Webサービスを呼び出すJavaクライアント・アプリケーション・コードの記述

- クライアント・アプリケーションのコンパイルと実行

- JavaクライアントのサンプルAntビルド・ファイル

- 別のWebサービスからのWebサービスの呼出し

- Webサービス・クライアントのサンプルbuild.xmlファイル

- Webサービスを呼び出すサンプルJWSファイル

- Webサービス呼出し時のスタンドアロン・クライアントJARファイルの使用

- Webサービス呼出し時のプロキシ・サーバーの使用

- HttpTransportInfo APIを使用したプロキシ・サーバーの指定

- システム・プロパティを使用したプロキシ・サーバーの指定

- Webサービスを再デプロイする際にクライアント側で考慮すべき事項

- WebLogic Webサービスのスタブ・プロパティ

- レスポンスSOAPメッセージの文字エンコーディングの設定

第III部 JAX-RPC Webサービスの高度な機能の開発

7 非同期リクエスト-レスポンスを使用したWebサービスの呼出し

- 非同期リクエスト-レスポンス機能の概要

- 非同期リクエスト-レスポンスの使用: 主な手順

- 非同期WebサービスのホストWebLogic Serverインスタンスの構成

- 非同期のJWSファイルの記述

- Webサービスの非同期な呼出しのコーディングに関するガイドライン

- 非同期の呼出し前および呼出し後におけるコンテキストの使用

- 同期呼出しのサンプル

- 非同期リクエスト-レスポンスを使用する場合のbuild.xmlファイルの更新

- 内部非同期サービスの無効化

- 非同期のリクエスト・レスポンスとプロキシ・サーバーの使用

8 Webサービスの信頼性のあるメッセージングの使用

- Webサービスの信頼性のあるメッセージングの概要

- WS-Policyを使用した信頼性のあるメッセージング・ポリシーのアサーションの指定

- 信頼性のあるメッセージ・シーケンスのライフサイクルの管理

- Webサービスの信頼性のあるメッセージングの使用: 主な手順

- 前提条件

- 宛先WebLogic Serverインスタンスの構成

- ソースWebLogic Serverインスタンスの構成

- Webサービスの信頼性のあるメッセージングのWS-Policyファイルの作成

- WS-ReliableMessagingポリシー・アサーション・バージョン1.1を使用したカスタムWS-Policyファイルの作成

- WS-ReliableMessagingポリシー・アサーション・バージョン1.0を使用したカスタムWS-Policyファイルの作成(非推奨)

- 複数のポリシー選択肢の使用

- 信頼性のあるJWSファイルに関するプログラミングのガイドライン

- @Policyアノテーションの使用

- @Onewayアノテーションの使用

- @BufferQueueアノテーションの使用

- @ReliabilityBufferアノテーションの使用

- 信頼性のあるWebサービスの信頼性のあるメッセージングの構成

- 管理コンソールの使用

- WLSTの使用

- 信頼性のあるWebサービスを呼び出すJWSファイルに関するプログラミングのガイドライン

- 信頼性のあるWebサービスのクライアント用build.xmlファイルの更新

- 信頼性のあるメッセージングとMTOMの使用

- 信頼性のあるWebサービスを再デプロイする際にクライアント側で考慮すべき事項

- 信頼性のあるメッセージングとプロキシ・サーバーの使用

9 会話型Webサービスの作成

- 会話型Webサービスの概要

- 会話型Webサービスの作成: 主な手順

- 会話型JWSファイルに関するプログラミングのガイドライン

- 会話型Webサービスを呼び出すJWSファイルに関するプログラミングのガイドライン

- ConversationUtilsユーティリティ・クラス

- 会話型Webサービスのクライアント用build.xmlファイルの更新

- 会話型Webサービスを呼び出すためのスタンドアロンJavaクライアントの更新

- 会話型Webサービスの.NETクライアントの例

- ConversationService.javaファイル

- Service.csファイル

- build.xmlファイル

- 会話型Webサービスを再デプロイする際にクライアント側で考慮すべき事項

10 バッファ付きWebサービスの作成

- バッファ付きWebサービスの概要

- バッファ付きWebサービスの作成: 主な手順

- バッファ付きWebサービスのホストWebLogic Serverインスタンスの構成

- バッファ付きJWSファイルに関するプログラミングのガイドライン

- バッファ付きWebサービスを呼び出すJWSファイルのプログラミング

- バッファ付きWebサービスのクライアント用build.xmlファイルの更新

11 非同期機能の併用

- 非同期機能の併用

- 信頼性のある会話型Webサービスを実装するJWSファイルの例

- 信頼性のある会話型Webサービスを非同期で呼び出すクライアントWebサービスの例

12 コールバックによるクライアントへのイベントの通知

- コールバックの概要

- コールバックの実装の概要と用語

- コールバックのプログラミング: 主な手順

- ターゲットWebサービスのプログラミングのガイドライン

- コールバック・クライアントWebサービスのプログラミングのガイドライン

- コールバック・インタフェースのプログラミングのガイドライン

- クライアントWebサービスのbuild.xmlファイルの更新

13 接続プロトコルとしてのJMSトランスポートの使用

- JMSトランスポートの使用の概要

- Javaから開始するJMSトランスポートの使用: 主な手順

- WSDLから開始するJMSトランスポートの使用: 主な手順

- JMSトランスポートWebサービスのホストWebLogic Serverインスタンスの構成

- @WLJmsTransport JWSアノテーションの使用

- jwsc Antタスクの<WLJmsTransport>子要素の使用

- JMSトランスポートを使用するためのWSDLの更新

- JMSトランスポートを使用したWebLogic Webサービスの呼出し

- デフォルトのサービス・アドレスURLのオーバーライド

- デフォルトのTextMessageのかわりとしてのJMS BytesMessageの使用

- WSDLファイルへのHTTPアクセスの無効化

14 SOAPメッセージ・ハンドラの作成と使用

- SOAPメッセージ・ハンドラの概要

- SOAPメッセージ・ハンドラのWebサービスへの追加: 主な手順

- SOAPメッセージ・ハンドラおよびハンドラ・チェーンの設計

- GenericHandlerクラスの作成

- Handler.init()メソッドの実装

- Handler.destroy()メソッドの実装

- Handler.getHeaders()メソッドの実装

- Handler.handleRequest()メソッドの実装

- Handler.handleResponse()メソッドの実装

- Handler.handleFault()メソッドの実装

- SAAJを使用したSOAPリクエスト・メッセージおよびレスポンス・メッセージの直接操作

- SOAPPartオブジェクト

- AttachmentPartオブジェクト

- SOAPメッセージ・ハンドラで画像添付ファイルの操作

- JWSファイルでのハンドラの構成

- @javax.jws.HandlerChain

- @javax.jws.soap.SOAPMessageHandlers

- ハンドラ・チェーン構成ファイルの作成

- Webサービスのコンパイルと再ビルド

- クライアント側SOAPメッセージ・ハンドラの作成と使用

- クライアント側SOAPメッセージ・ハンドラの使用: 主な手順

- クライアント側ハンドラ・クラスの例

- クライアント側SOAPハンドラの構成ファイルの作成

- クライアント側ハンドラの構成ファイル用XMLスキーマ

- クライアント側SOAPハンドラの構成ファイルのclientgenへの指定

15 Database Webサービスの使用

- Database Webサービスの概要

- Databaseコールイン

- Databaseコールアウト

- SQLとXMLの間のタイプ・マッピング

- Webサービスのコールインに対するSQLからXMLタイプへのマッピング

- Webサービス・コールアウトに対するXMLからSQLタイプへのマッピング

A 信頼性のあるメッセージング用にパッケージ化されているWS-Policyファイル

- DefaultReliability1.1.xml (WS-Policyファイル)

- Reliability1.1_SequenceTransportSecurity.xml (WS-Policyファイル)

- Reliability1.1_SequenceSTR.xml (WS-Policyファイル)

- Reliability1.0_1.1.xml (WS-Policy.xmlファイル)

- DefaultReliability.xml (WS-Policyファイル) [非推奨]

- LongRunningReliability.xml (WS-Policyファイル) [非推奨]

はじめに

ここでは、このガイド『Oracle WebLogic Server JAX-RPC Webサービスの開発』で使用されるアクセシビリティ機能および表記規則について説明します。

ドキュメントのアクセシビリティについて

Oracleのアクセシビリティについての詳細情報は、Oracle Accessibility ProgramのWebサイトhttp://www.oracle.com/pls/topic/lookup?ctx=acc&id=docaccを参照してください。

Oracleサポートへのアクセス

サポートをご購入のOracleのお客様は、My Oracle Supportにアクセスして電子サポートを受けることができます。詳細情報はhttp://www.oracle.com/pls/topic/lookup?ctx=acc&id=infoか、聴覚に障害があるお客様はhttp://www.oracle.com/pls/topic/lookup?ctx=acc&id=trsを参照してください。

表記規則

このドキュメントでは次の表記規則を使用します。

規則

意味

太字

太字は、操作に関連するGraphical User Interface要素、または本文中で定義されている用語および用語集に記載されている用語を示します。

斜体

イタリックは、ユーザーが特定の値を指定するプレースホルダー変数を示します。

固定幅フォント

固定幅フォントは、段落内のコマンド、URL、サンプル内のコード、画面に表示されるテキスト、または入力するテキストを示します。

このガイドでの新しい情報

次のトピックでは、Oracle Fusion Middleware 12c (12.2.1)におけるWebLogic Java API for XML-based RPC (JAX-RPC) Webサービスの新機能と変更点について説明し、追加情報へのリンクを提供します。

12c (12.2.1)の新機能と変更された機能

JAX-RPC APIはWebLogic Server 12.2.1で非推奨になりました。

12c (12.1.3)の新機能と変更された機能

Oracle Fusion Middleware 12c (12.1.3)について、このドキュメントに記載されている新機能および変更された機能はありません。

12c (12.1.2)での新機能と変更された機能

このドキュメントにおける、Oracle Fusion Middleware 12c (12.1.2)の新機能と変更された機能は次のとおりです。

- 12c (12.2.1)では、Oracle Fusion Middlewareリリース11gて提供されていた次のガイドの内容が、1つのドキュメントにまとめられています。

- Oracle WebLogic Server JAX-RPC Webサービス・スタート・ガイド

- Oracle WebLogic Server JAX-RPC Webサービスの高度な機能のプログラミング

- 基本的なJAX-RPCクライアント側機能をサポートする、新しいスタンドアロンWebサービス・クライアントJARファイル。「Webサービス呼出し時のスタンドアロン・クライアントJARファイルの使用」を参照してください。

第I部

概要

第I部では、Java API for XML-based RPC (JAX-RPC)を使用するWebLogic Webサービスの開発について説明します。

ここで説明するトピックは次のとおりです。

- 第1章「JAX-RPC Webサービスの概要」

- 第2章「JAX-RPC Webサービス開発者向けサンプル」

1 JAX-RPC Webサービスの概要

この章では、Java API for XML RPC (JAX-RPC)を使用してWebLogic Webサービスをプログラミングするソフトウェア開発者向けのトピックをまとめた表を示します。

JAX-RPCは、XMLベースのリモート・プロシージャ呼出し(RPC)を行うためのJava APIを定義した仕様です。特に、これらのAPIは、SOAP 1.1(分散型環境で情報を交換するためのXMLベースのプロトコル)を使用して、Webサービスを呼び出したり、Webサービスからレスポンスを取得したりするのに使用されます。詳細は、http://java.net/projects/jax-rpc/を参照してください。

次の表に、このガイドの内容をまとめます。

表1-1 内容のまとめ

章

内容

第2章「JAX-RPC Webサービス開発者向けサンプル」

一般的なユース・ケースとサンプルを確認および実行します。

第3章「JAX-RPC Webサービスの開発」

WebLogic開発環境でのWebサービスの開発。

第4章「JWSファイルのプログラミング」

Webサービスを実装するJWSファイルのプログラミング。

第5章「データ・バインディングの理解」

Java Architecture for XML Binding (JAXB)データ・バインディングを使用します。

第6章「JAX-RPC Webサービス・クライアントの開発」

Javaクライアントまたは別のWebサービスからWebサービスを呼び出します。

第7章「非同期リクエスト-レスポンスを使用したWebサービスの呼出し」

Webサービスを非同期的に呼び出します。

第8章「Webサービスの信頼性のあるメッセージングの使用」

WS-ReliableMessaging仕様に準拠して信頼性のあるWebサービスを作成してから、そのWebサービスを呼び出すクライアントWebサービスを作成します。

第9章「会話型Webサービスの作成」

クライアントと通信する会話型Webサービスを作成します。

第10章「バッファ付きWebサービスの作成」

WS-ReliableMessaging仕様に準拠した信頼性のあるWebサービスよりも単純なタイプのバッファ付きWebサービスを作成します。

第11章「非同期機能の併用」

信頼性のあるメッセージング、非同期リクエスト-レスポンス、会話などの非同期機能を単一のWebサービスで一緒に使用します。

第12章「コールバックによるクライアントへのイベントの通知」

コールバックをプログラミングしてイベントの発生をWebサービスのクライアントに通知します。

第13章「接続プロトコルとしてのJMSトランスポートの使用」

Webサービスの呼出し時の接続プロトコルとして、デフォルトのHTTP/SではなくJMSを指定します。

第14章「SOAPメッセージ・ハンドラの作成と使用」

WebサービスのSOAPメッセージ・ハンドラを作成および構成します。

第15章「Database Webサービスの使用」

データベースWebサービスを作成します。

WebLogic Webサービスの概要、規格、サンプルおよび関連ドキュメントは、『Oracle WebLogic Server WebLogic Webサービスの理解』を参照してください。

WebLogic Webサービスのセキュリティについては、『Oracle WebLogic Server WebLogic Webサービスの保護』を参照してください。

このドキュメントおよびその他のドキュメントの用語の定義については、「用語集」を参照してください。

2 JAX-RPC Webサービス開発者向けサンプル

この章では、Java API for XML-based RPC (JAX-RPC)を使用したWebLogic Webサービスの一般的なユース・ケースとサンプルについて説明します。

この章の内容は次のとおりです。

- 簡単なHelloWorld Webサービスの作成

- ユーザー定義のデータ型を使用するWebサービスの作成

- WSDLファイルからのWebサービスの作成

- Java SEクライアントからのWebサービスの呼出し

- WebLogic WebサービスからのWebサービスの呼出し

各ユース・ケースでは、簡単なWebLogic Webサービスを作成する手順や、デプロイ済のWebサービスから操作を呼び出す手順を示します。これらの例には基本的なJavaコードとAnt build.xmlファイルが含まれており、それらをユーザーの開発環境で使用してサンプルを再現することや、現在の開発環境とは別の環境で指示に従ってサンプルを作成して実行することができます。

ユース・ケースではサンプルで使用されるプロセスやツールについては詳しく説明していません。詳細は、以降の章を参照してください。

簡単なHelloWorld Webサービスの作成

この項では、1つの操作を含む非常に簡単なWebサービスの作成方法について説明します。Webサービスを実装するJava Webサービス(JWS)・ファイルでは必須のJWSアノテーション@WebServiceを1つのみ使用しています。JWSファイルは、JWSメタデータ・アノテーションを使用してWebサービスの形式を指定した標準のJavaファイルです。メタデータ・アノテーションはJDK 5.0で導入され、Webサービス・ファイルにアノテーションを付けるために使用される一連のアノテーションはJWSアノテーションと呼ばれます。WebLogic Webサービスは標準のJWSアノテーションを使用します。サポートされるJWSアノテーションの完全なリストは、『Oracle WebLogic Server WebLogic Webサービス・リファレンス』のWebサービスのアノテーション・サポートに関する項を参照してください。

次の例では、1つの操作sayHelloWorldを含むHelloWorldServiceというWebサービスを作成する方法を示します。簡単にするために、操作は入力された文字列値を戻すものとします。

1. WebLogic Server環境を設定します。
コマンド・ウィンドウを開いて、ドメイン・ディレクトリのbinサブディレクトリにあるsetDomainEnv.cmd (Windows)またはsetDomainEnv.sh (UNIX)スクリプトを実行します。WebLogic Serverドメインのデフォルトの場所はORACLE_HOME/user_projects/domains/domainNameです(ORACLE_HOMEはOracle WebLogic Serverのインストール時にOracleホームとして指定したディレクトリ、domainNameはドメインの名前です)。

2. 次のようにプロジェクト・ディレクトリを作成します。

prompt> mkdir /myExamples/hello_world

3. プロジェクト・ディレクトリの下に、srcディレクトリと、JWSファイル(この手順で後述)のパッケージ名に対応するサブディレクトリを作成します。

prompt> cd /myExamples/hello_world
prompt> mkdir src/examples/webservices/hello_world

4. Webサービスを実装するJWSファイルを作成します。
任意のJava IDEまたはテキスト・エディタを開いて、「サンプルHelloWorldImpl.java JWSファイル」で指定されたJavaコードを使用してHelloWorldImpl.javaというJavaファイルを作成します。

サンプルJWSファイルでは、1つのパブリック・メソッドsayHelloWorld(String)を含むHelloWorldImplというJavaクラスが示されています。@WebServiceアノテーションは、JavaクラスがHelloWorldServiceというWebサービスを実装することを指定しています。デフォルトでは、すべてのパブリック・メソッドが操作として公開されます。

5. src/examples/webservices/hello_worldディレクトリにHelloWorldImpl.javaファイルを保存します。

6. プロジェクト・ディレクトリ(myExamples/hello_world/src)内に標準のAnt build.xmlファイルを作成し、taskdef Antタスクを追加して、jwscタスクの完全修飾Javaクラス名を指定します。

<project name="webservices-hello_world" default="all">
<taskdef name="jwsc"
classname="weblogic.wsee.tools.anttasks.JwscTask" />
</project>

この手順で説明される追加のターゲット(clean、undeploy、client、およびrunなど)が含まれている、完全なサンプルbuild.xmlファイルについては、「HelloWorldImpl.javaのサンプルAntビルド・ファイル」を参照してください。完全なbuild.xmlファイルでは、EARディレクトリの名前を常にハード・コード化して使用するのではなく、${ear-dir}などのプロパティも使用しています。

7. 次のようなjwsc Antタスクの呼出しを、build-serviceターゲット内にラップして、build.xmlファイルに追加します。

<target name="build-service">
<jwsc
srcdir="src"
destdir="output/helloWorldEar">
<jws file="examples/webservices/hello_world/HelloWorldImpl.java"
type="JAXRPC"/>
</jwsc>
</target>

jwsc WebLogic WebサービスAntタスクは、補助的なアーティファクト(デプロイメント記述子、ユーザー定義のデータ型のシリアライゼーション・クラス、WSDLファイルなど)を生成し、ユーザーが作成および生成したJavaコードをコンパイルして、すべてのアーティファクトを、後でWebLogic Serverにデプロイされるエンタープライズ・アプリケーションEARにアーカイブ化します。

8. コマンド・ラインでbuild-serviceターゲットを指定して、jwsc Antタスクを実行します。

prompt> ant build-service

output/helloWorldEarディレクトリを見て、jwsc Antタスクによって生成されたファイルとアーティファクトを確認します。

9. WebサービスをデプロイするWebLogic Serverインスタンスを起動します。

10. WebLogic Server管理コンソールまたはwldeploy Antタスクを使用して、エンタープライズ・アプリケーションにパッケージ化されたWebサービスをWebLogic Serverにデプロイします。いずれの場合でも、outputディレクトリにあるhelloWorldEarエンタープライズ・アプリケーションをデプロイします。
wldeploy Antタスクを使用するには、以下のターゲットをbuild.xmlファイルに追加します。

<taskdef name="wldeploy"
classname="weblogic.ant.taskdefs.management.WLDeploy"/>
<target name="deploy">
<wldeploy action="deploy"
name="helloWorldEar" source="output/helloWorldEar"
user="${wls.username}" password="${wls.password}"
verbose="true"
adminurl="t3://${wls.hostname}:${wls.port}"
targets="${wls.server.name}" />
</target>

wls.username、wls.password、wls.hostname、wls.port、およびwls.server.nameの値は、ご使用のWebLogic Serverインスタンスの対応する値で置き換えます。

deployターゲットを実行して、WARファイルをデプロイします。

prompt> ant deploy

11. ブラウザでWSDLを呼び出して、Webサービスが正しくデプロイされていることをテストします。

http://host:port/HelloWorldImpl/HelloWorldImpl?WSDL

WLHttpTransport JWSアノテーションのcontextPathおよびserviceUri属性の値を使用してURLを構築します。ただし、このユース・ケースのJWSファイルにはWLHttpTransportアノテーションが含まれていないので、contextPathおよびserviceUri属性のデフォルト値(JWSファイル内のJavaクラスの名前)を使用します。これらの属性は、次の「ユーザー定義のデータ型を使用したWebサービスの作成」の例で明示的に設定されます。各自のWebLogic Serverインスタンスに適合したホスト名およびポートを選択してください。

build.xmlファイルでclean、build-service、undeploy、deployの各ターゲットを使用すると、開発プロセスの一環としてWebサービスの更新、再ビルド、アンデプロイおよび再デプロイを繰り返し実行できます。

Webサービスを実行するには、そのWebサービスを呼び出すクライアントを作成する必要があります。Webサービスを呼び出すJavaクライアント・アプリケーションの作成例については、「Java SEクライアントからのWebサービスの呼出し」を参照してください。

サンプルHelloWorldImpl.java JWSファイル

package examples.webservices.hello_world;
// Import the @WebService annotation
import javax.jws.WebService;
@WebService(name="HelloWorldPortType", serviceName="HelloWorldService")
/**
* This JWS file forms the basis of simple Java-class implemented WebLogic
* Web Service with a single operation: sayHelloWorld
*/
public class HelloWorldImpl {
// By default, all public methods are exposed as Web Services operation
public String sayHelloWorld(String message) {
try {
System.out.println("sayHelloWorld:" + message);
} catch (Exception ex) { ex.printStackTrace(); }

return "Here is the message: '" + message + "'";
}
}

HelloWorldImpl.javaのサンプルAntビルド・ファイル

以下のbuild.xmlファイルでは、プロパティを使用してファイルを簡素化しています。

<project name="webservices-hello_world" default="all">
<!-- set global properties for this build -->
<property name="wls.username" value="weblogic" />
<property name="wls.password" value="weblogic" />
<property name="wls.hostname" value="localhost" />
<property name="wls.port" value="7001" />
<property name="wls.server.name" value="myserver" />
<property name="ear.deployed.name" value="helloWorldEar" />
<property name="example-output" value="output" />
<property name="ear-dir" value="${example-output}/helloWorldEar" />
<property name="clientclass-dir" value="${example-output}/clientclasses" />
<path id="client.class.path">
<pathelement path="${clientclass-dir}"/>
<pathelement path="${java.class.path}"/>
</path>
<taskdef name="jwsc"
classname="weblogic.wsee.tools.anttasks.JwscTask" />
<taskdef name="clientgen"
classname="weblogic.wsee.tools.anttasks.ClientGenTask" />
<taskdef name="wldeploy"
classname="weblogic.ant.taskdefs.management.WLDeploy"/>
<target name="all" depends="clean,build-service,deploy,client" />
<target name="clean" depends="undeploy">
<delete dir="${example-output}"/>
</target>
<target name="build-service">
<jwsc
srcdir="src"
destdir="${ear-dir}">
<jws file="examples/webservices/hello_world/HelloWorldImpl.java"
type="JAXRPC"/>
</jwsc>
</target>
<target name="deploy">
<wldeploy action="deploy" name="${ear.deployed.name}"
source="${ear-dir}" user="${wls.username}"
password="${wls.password}" verbose="true"
adminurl="t3://${wls.hostname}:${wls.port}"
targets="${wls.server.name}" />
</target>
<target name="undeploy">
<wldeploy action="undeploy" name="${ear.deployed.name}"
failonerror="false"
user="${wls.username}" password="${wls.password}" verbose="true"
adminurl="t3://${wls.hostname}:${wls.port}"
targets="${wls.server.name}" />
</target>
<target name="client">
<clientgen
wsdl="http://${wls.hostname}:${wls.port}/HelloWorldImpl/HelloWorldImpl?WSDL"
destDir="${clientclass-dir}"
packageName="examples.webservices.hello_world.client"
type="JAXRPC"/>
<javac
srcdir="${clientclass-dir}" destdir="${clientclass-dir}"
includes="**/*.java"/>
<javac
srcdir="src" destdir="${clientclass-dir}"
includes="examples/webservices/hello_world/client/**/*.java"/>
</target>
<target name="run">
<java classname="examples.webservices.hello_world.client.Main"
fork="true" failonerror="true" >
<classpath refid="client.class.path"/>
<arg
line="http://${wls.hostname}:${wls.port}/HelloWorldImpl/HelloWorldImpl"  />
</java> </target>
</project>

ユーザー定義のデータ型を使用するWebサービスの作成

前のユース・ケースでは、Webサービス操作のパラメータと戻り値として、単純データ型Stringのみを使用していました。次の例では、ユーザー定義のデータ型(特にBasicStructというJavaBean)を操作のパラメータおよび戻り値として使用するWebサービスの作成方法を示します。

Webサービスでユーザー定義のデータ型を使用する場合、データ型のJavaソースを作成して、それをJWSファイル内で適切に使用する以外に、プログラマが実際にすべきことはほとんどありません。jwsc Antタスクは、JWSファイルにユーザー定義のデータ型がある場合、XML表現(SOAPメッセージで使用)とJava表現(WebLogic Serverで使用)との間でデータを変換するのに必要な、すべてのデータ・バインディング・アーティファクトを自動的に生成します。データ・バインディング・アーティファクトには、Javaユーザー定義データ型に相当するXMLスキーマ、JAX-RPCの型マッピング・ファイルなどがあります。

次の手順は「簡単なHelloWorld Webサービスの作成」に記載されている手順によく似ています。そのため、手順では必要なステップをすべて示していますが、簡単なHelloWorldサンプルとは異なるステップのみの詳細を説明しています。

1. WebLogic Server環境を設定します。
コマンド・ウィンドウを開いて、ドメイン・ディレクトリのbinサブディレクトリにあるsetDomainEnv.cmd (Windows)またはsetDomainEnv.sh (UNIX)スクリプトを実行します。WebLogic Serverドメインのデフォルトの場所はORACLE_HOME/user_projects/domains/domainNameです(ORACLE_HOMEはOracle WebLogic Serverのインストール時にOracleホームとして指定したディレクトリ、domainNameはドメインの名前です)。

2. プロジェクト・ディレクトリを作成します。

prompt> mkdir /myExamples/complex

3. プロジェクト・ディレクトリの下に、srcディレクトリと、JWSファイル(この手順で後述)のパッケージ名に対応するサブディレクトリを作成します。

prompt> cd /myExamples/complex
prompt> mkdir src/examples/webservices/complex

4. BasicStruct JavaBeanのソースを作成します。
任意のJava IDEまたはテキスト・エディタを開いて、「サンプルBasicStruct JavaBean」で指定されたJavaコードを使用して BasicStruct.javaというJavaファイルをプロジェクト・ディレクトリに作成します。

5. BasicStruct.javaファイルをプロジェクト・ディレクトリのsrc/examples/webservices/complexサブディレクトリに保存します。

6. 「サンプルComplexImpl.java JWSファイル」で指定されたJavaコードを使用して、Webサービスを実装するJWSファイルを作成します。
このサンプルJWSファイルでは、複数のJWSアノテーションを使用しています。@WebMethodでは、メソッドがWebサービス操作として公開されることを明示的に指定し、操作名をデフォルトのメソッド名echoStructからechoComplexTypeに変更します。@WebParamと@WebResultでは、パラメータと戻り値を構成します。@SOAPBindingでは、Webサービスのタイプを指定します。@WLHttpTransportでは、Webサービスの呼出しに使用されるURIを指定します。また、ComplexImpl.java JWSファイルではexamples.webservice.complex.BasicStructクラスをインポートして、echoStruct()メソッドのパラメータと戻り値としてユーザー定義データ型のBasicStructを使用します。

JWSファイルの作成に関するより詳細な情報については、第4章「JWSファイルのプログラミング」を参照してください。

7. ComplexImpl.javaファイルをプロジェクト・ディレクトリのsrc/examples/webservices/complexサブディレクトリに保存します。

8. プロジェクト・ディレクトリ内に標準のAnt build.xmlファイルを作成し、taskdef Antタスクを追加して、jwscタスクの完全修飾クラス名を指定します。

<project name="webservices-complex" default="all">
<taskdef name="jwsc"
classname="weblogic.wsee.tools.anttasks.JwscTask" />
</project>

完全なサンプルbuild.xmlファイルについては、「ComplexImpl.java JWSファイルのサンプルAntビルド・ファイル」を参照してください。

9. 次のようなjwsc Antタスクの呼出しを、build-serviceターゲット内にラップして、build.xmlファイルに追加します。

<target name="build-service">
<jwsc
srcdir="src"
destdir="output/ComplexServiceEar" >
<jws file="examples/webservices/complex/ComplexImpl.java"
type="JAXRPC">
<WLHttpTransport
contextPath="complex" serviceUri="ComplexService"
portName="ComplexServicePort"/>
</jws>
</jwsc>
</target>

上記の例で注目すべき点は以下のとおりです。

- <jws>要素のtype属性では、Webサービスのタイプ(JAX-WSまたはJAX-RPC)が指定されています。

- jwsc Antタスクの<jws>要素の<WLHttpTransport>子要素では、HTTP/Sトランスポートを介してWebサービスを呼び出す際に使用されるURLのコンテキスト・パスとサービスURIセクションに加え、生成されるWSDLのポートの名前も指定されています。この値は、@WLHttpTransport属性を使用してJWSファイルで指定されている値をオーバーライドします。コンテキスト・パスの定義の詳細は、「WebLogic Webサービスのコンテキスト・パスの定義」を参照してください。

10. jwsc Antタスクを使用します。

prompt> ant build-service

output/ComplexServiceEarディレクトリを見て、jwsc Antタスクによって生成されたファイルとアーティファクトを確認します。

11. WebサービスをデプロイするWebLogic Serverインスタンスを起動します。

12. WebLogic Server管理コンソールまたはwldeploy Antタスクを使用して、ComplexServiceEarエンタープライズ・アプリケーションにパッケージ化されたWebサービスをWebLogic Serverにデプロイします。例:

prompt> ant deploy

13. WebLogic Server管理コンソールまたはwldeploy Antタスクを使用して、エンタープライズ・アプリケーションにパッケージ化されたWebサービスをWebLogic Serverにデプロイします。いずれの場合でも、outputディレクトリにあるComplexServiceEarエンタープライズ・アプリケーションをデプロイします。
wldeploy Antタスクを使用するには、以下のターゲットをbuild.xmlファイルに追加します。

<taskdef name="wldeploy"
classname="weblogic.ant.taskdefs.management.WLDeploy"/>
<target name="deploy">
<wldeploy action="deploy"
name="ComplexServiceEar" source="output/ComplexServiceEar"
user="${wls.username}" password="${wls.password}"
verbose="true"
adminurl="t3://${wls.hostname}:${wls.port}"
targets="${wls.server.name}" />
</target>

wls.username、wls.password、wls.hostname、wls.port、およびwls.server.nameの値は、ご使用のWebLogic Serverインスタンスの対応する値で置き換えます。

deployターゲットを実行して、WARファイルをデプロイします。

prompt> ant deploy

14. ブラウザでWSDLを呼び出して、Webサービスが正しくデプロイされていることをテストします。

http://host:port/complex/ComplexService?WSDL

Webサービスを実行するには、そのWebサービスを呼び出すクライアントを作成する必要があります。Webサービスを呼び出すJavaクライアント・アプリケーションの作成例については、「Java SEクライアントからのWebサービスの呼出し」を参照してください。

サンプルBasicStruct JavaBean

package examples.webservices.complex;
/**
* Defines a simple JavaBean called BasicStruct that has integer, String,
* and String[] properties
*/
public class BasicStruct {
// Properties
private int intValue;
private String stringValue;
private String[] stringArray;
// Getter and setter methods
public int getIntValue() {
return intValue;
}
public void setIntValue(int intValue) {
this.intValue = intValue;
}
public String getStringValue() {
return stringValue;
}
public void setStringValue(String stringValue) {
this.stringValue = stringValue;
}
public String[] getStringArray() {
return stringArray;
}
public void setStringArray(String[] stringArray) {
this.stringArray = stringArray;
}
public String toString() {
return "IntValue="+intValue+", StringValue="+stringValue;
}
}

サンプルComplexImpl.java JWSファイル

package examples.webservices.complex;
// Import the standard JWS annotation interfaces
import javax.jws.WebMethod;
import javax.jws.WebParam;
import javax.jws.WebResult;
import javax.jws.WebService;
import javax.jws.soap.SOAPBinding;
// Import the WebLogic-specific JWS annotation interface
import weblogic.jws.WLHttpTransport;
// Import the BasicStruct JavaBean
import examples.webservices.complex.BasicStruct;
// Standard JWS annotation that specifies that the portType name of the Web
// Service is "ComplexPortType", its public service name is "ComplexService",
// and the targetNamespace used in the generated WSDL is "http://example.org"
@WebService(serviceName="ComplexService", name="ComplexPortType",
targetNamespace="http://example.org")
// Standard JWS annotation that specifies this is a document-literal-wrapped
// Web Service
@SOAPBinding(style=SOAPBinding.Style.DOCUMENT,
use=SOAPBinding.Use.LITERAL,
parameterStyle=SOAPBinding.ParameterStyle.WRAPPED)
// WebLogic-specific JWS annotation that specifies the context path and service
// URI used to build the URI of the Web Service is "complex/ComplexService"
@WLHttpTransport(contextPath="complex", serviceUri="ComplexService",
portName="ComplexServicePort")
/**
* This JWS file forms the basis of a WebLogic Web Service.  The Web Services
* has two public operations:
*
*  - echoInt(int)
*  - echoComplexType(BasicStruct)
*
* The Web Service is defined as a "document-literal" service, which means
* that the SOAP messages have a single part referencing an XML Schema element
* that defines the entire body.
*/
public class ComplexImpl {
// Standard JWS annotation that specifies that the method should be exposed
// as a public operation.  Because the annotation does not include the
// member-value "operationName", the public name of the operation is the
// same as the method name: echoInt.
//
// The WebResult annotation specifies that the name of the result of the
// operation in the generated WSDL is "IntegerOutput", rather than the
// default name "return".   The WebParam annotation specifies that the input
// parameter name in the WSDL file is "IntegerInput" rather than the Java
// name of the parameter, "input".
@WebMethod()
@WebResult(name="IntegerOutput",
targetNamespace="http://example.org/complex")
public int echoInt(
@WebParam(name="IntegerInput",
targetNamespace="http://example.org/complex")
int input)
{
System.out.println("echoInt '" + input + "' to you too!");
return input;
}
// Standard JWS annotation to expose method "echoStruct" as a public operation
// called "echoComplexType"
// The WebResult annotation specifies that the name of the result of the
// operation in the generated WSDL is "EchoStructReturnMessage",
// rather than the default name "return".
@WebMethod(operationName="echoComplexType")
@WebResult(name="EchoStructReturnMessage",
targetNamespace="http://example.org/complex")
public BasicStruct echoStruct(BasicStruct struct)
{
System.out.println("echoComplexType called");
return struct;
}
}

ComplexImpl.java JWSファイルのサンプルAntビルド・ファイル

以下のbuild.xmlファイルでは、プロパティを使用してファイルを簡素化しています。

<project name="webservices-complex" default="all">
<!-- set global properties for this build -->
<property name="wls.username" value="weblogic" />
<property name="wls.password" value="weblogic" />
<property name="wls.hostname" value="localhost" />
<property name="wls.port" value="7001" />
<property name="wls.server.name" value="myserver" />
<property name="ear.deployed.name" value="complexServiceEAR" />
<property name="example-output" value="output" />
<property name="ear-dir" value="${example-output}/complexServiceEar" />
<property name="clientclass-dir" value="${example-output}/clientclass" />
<path id="client.class.path">
<pathelement path="${clientclass-dir}"/>
<pathelement path="${java.class.path}"/>
</path>
<taskdef name="jwsc"
classname="weblogic.wsee.tools.anttasks.JwscTask" />
<taskdef name="clientgen"
classname="weblogic.wsee.tools.anttasks.ClientGenTask" />
<taskdef name="wldeploy"
classname="weblogic.ant.taskdefs.management.WLDeploy"/>
<target name="all" depends="clean,build-service,deploy,client"/>
<target name="clean" depends="undeploy">
<delete dir="${example-output}"/>
</target>
<target name="build-service">
<jwsc
srcdir="src"
destdir="${ear-dir}"
keepGenerated="true"
>
<jws file="examples/webservices/complex/ComplexImpl.java"
type="JAXRPC">
<WLHttpTransport
contextPath="complex" serviceUri="ComplexService"
portName="ComplexServicePort"/>
</jws>
</jwsc>
</target>
<target name="deploy">
<wldeploy action="deploy"
name="${ear.deployed.name}"
source="${ear-dir}" user="${wls.username}"
password="${wls.password}" verbose="true"
adminurl="t3://${wls.hostname}:${wls.port}"
targets="${wls.server.name}"/>
</target>
<target name="undeploy">
<wldeploy action="undeploy" failonerror="false"
name="${ear.deployed.name}"
user="${wls.username}" password="${wls.password}" verbose="true"
adminurl="t3://${wls.hostname}:${wls.port}"
targets="${wls.server.name}"/>
</target>
<target name="client">
<clientgen
wsdl="http://${wls.hostname}:${wls.port}/complex/ComplexService?WSDL"
destDir="${clientclass-dir}"
packageName="examples.webservices.complex.client"
type="JAXRPC"/>
<javac
srcdir="${clientclass-dir}" destdir="${clientclass-dir}"
includes="**/*.java"/>
<javac
srcdir="src" destdir="${clientclass-dir}"
includes="examples/webservices/complex/client/**/*.java"/>
</target>
<target name="run" >
<java fork="true"
classname="examples.webservices.complex.client.Main"
failonerror="true" >
<classpath refid="client.class.path"/>
<arg line="http://${wls.hostname}:${wls.port}/complex/ComplexService"
/>
</java>
</target>
</project>

WSDLファイルからのWebサービスの作成

Webサービスの作成に関するもう1つの一般的なユース・ケースは、既存のWSDLファイル(黄金のWSDLとも呼ばれます)から開始することです。WSDLファイルはWebサービスがどのようなものかを指定するパブリック・コントラクトであり、サポートされる操作のリスト、各操作のシグネチャと形式、操作を呼び出すときに使用されるプロトコルとトランスポート、データをトランスポートするときに使用されるXMLスキーマ・データ型などを指定します。WSDLファイルに基づいて、WebLogic Serverにデプロイできるように、Webサービスを実装するアーティファクトを生成します。wsdlc Antタスクを使用して次のアーティファクトを生成します。

- WSDLファイルで記述されたWebサービスを実装するJWSサービス・エンドポイント・インタフェース(SEI)。

- 生成されるJWS SEIの不完全な(途中まで作成済みの)実装が含まれるJWS実装ファイル。このファイルは開発者がカスタマイズする必要があります。

- Webサービスのパラメータと戻り値をXML表現とJava表現の間で変換するために、WebLogic Serverによって使用されるデータ・バインディング・アーティファクト。

- (オプション)生成されるJWS SEIのJavadoc。

注意:
更新することになるwsdlc Antタスクによって生成されるファイルは、JWS実装ファイルのみです。JWS SEIおよびデータ・バインディング・アーティファクトが含まれるJARファイルを更新する必要はありません。

一般に、wsdlc Antタスクを1回実行して、生成されるJWS SEIファイルとデータ・バインディング・アーティファクトを含むJARファイルを生成し、その後で、インタフェースを実装する生成済JWSファイルをコーディングして、Webサービスのビジネス・ロジックを追加します。特に、Webサービス操作を実装するメソッドに、操作の動作に必要なJavaコードを追加し、JWSアノテーションを追加します。

JWS実装ファイルをコーディングしたら、前の項で説明したのと同じ手順に従って、jwsc Antタスクを実行してデプロイ可能なWebサービスを生成します。相違点は、compiledWsdl属性を使用して、wsdlc Antタスクによって生成されるJARファイル(JWS SEIファイルとデータ・バインディング・アーティファクトを含む)を指定することのみです。

次の簡単な例は、「サンプルWSDLファイル」に示したWSDLファイルからWebサービスを作成する方法を示しています。このWebサービスには、郵便番号を渡されると気温を返すgetTempという1つの操作が含まれています。

1. WebLogic Server環境を設定します。
コマンド・ウィンドウを開いて、ドメイン・ディレクトリのbinサブディレクトリにあるsetDomainEnv.cmd (Windows)またはsetDomainEnv.sh (UNIX)スクリプトを実行します。WebLogic Serverドメインのデフォルトの場所はORACLE_HOME/user_projects/domains/domainNameです(ORACLE_HOMEはOracle WebLogic Serverのインストール時にOracleホームとして指定したディレクトリ、domainNameはドメインの名前です)。

2. 作業ディレクトリを作成します。

prompt> mkdir /myExamples/wsdlc

3. WSDLファイルをコンピュータ上のアクセス可能なディレクトリに置きます。
この例では、WSDLファイルはTemperatureService.wsdlという名前で/myExamples/wsdlc/wsdl_filesディレクトリにあると仮定しています。ファイルの完全なリストについては、「サンプルWSDLファイル」を参照してください。

4. プロジェクト・ディレクトリ内に標準のAnt build.xmlファイルを作成し、taskdef Antタスクを追加して、wsdlcタスクの完全修飾Javaクラス名を指定します。

<project name="webservices-wsdlc" default="all">
<taskdef name="wsdlc"
classname="weblogic.wsee.tools.anttasks.WsdlcTask"/>
</project>

この手順で説明される追加のターゲット(clean、undeploy、client、およびrunなど)が含まれている、完全なサンプルbuild.xmlファイルについては、「TemperatureServiceのサンプルAntビルド・ファイル」を参照してください。完全なbuild.xmlファイルでは、EARディレクトリの名前を常にハード・コード化して使用するのではなく、${ear-dir}などのプロパティも使用しています。

5. 次のようなwsdlc Antタスクの呼出しを、generate-from-wsdlターゲット内にラップして、build.xmlファイルに追加します。

<target name="generate-from-wsdl">
<wsdlc
srcWsdl="wsdl_files/TemperatureService.wsdl"
destJwsDir="output/compiledWsdl"
destImplDir="output/impl"
packageName="examples.webservices.wsdlc" />
</target>

このサンプルwsdlcタスクでは、JWS SEIとデータ・バインディング・アーティファクトを含むJARファイルを、カレント・ディレクトリ下のoutput/compiledWsdlディレクトリに生成します。また、JWS SEIの部分的な実装ファイル(TemperaturePortTypeImpl.java)をoutput/impl/examples/webservices/wsdlcディレクトリに生成します(このディレクトリは、destImplDirで指定されたoutputディレクトリと、パッケージ名で指定されたディレクトリ階層を組み合せたものです)。生成されたすべてのJWSファイルはexamples.webservices.wsdlcパッケージにパッケージ化されます。

6. コマンド・ラインでgenerate-from-wsdlターゲットを指定して、wsdlc Antタスクを実行します。

prompt> ant generate-from-wsdl

wsdlc Antタスクによってアーティファクトとファイルが生成されたことを調べるには、outputディレクトリを確認します。

7. 任意のJava IDEまたはテキスト・エディタを使用して、生成されたoutput/impl/examples/webservices/wsdlc/TemperaturePortTypeImpl.java JWS実装ファイルを更新し、必要な処理を行うようにメソッドにJavaコードを追加します。
例については「サンプルTemperaturePortType Java実装ファイル」を参照してください。追加されたJavaコードが太字になっています。生成されたJWS実装ファイルには@WebServiceおよび@WLHttpTransportアノテーションの値が自動的に含まれており、その値は元のWSDLファイルの値に対応しています。

注意:
「WSDLから開始する」ユース・ケースのJWS実装ファイルに追加できるJWSアノテーションには制限があります。詳細は、『Oracle WebLogic Server WebLogic Webサービス・リファレンス』のwsdlcに関する項を参照してください。

簡単にするために、サンプルのTemperaturePortTypeImpl.javaにあるgetTemp()メソッドは、ハード・コード化された数字を返します。実際のファイルの場合、このメソッドの実装では、特定の郵便番号で現在の気温をルックアップします。

8. 更新したTemperaturePortTypeImpl.javaファイルを永続的なディレクトリ(プロジェクト・ディレクトリの下のsrcディレクトリなど。パッケージ名に対応する子ディレクトリも作成します)にコピーします。

prompt> cd /examples/wsdlc
prompt> mkdir src/examples/webservices/wsdlc
prompt> cp output/impl/examples/webservices/wsdlc/TemperaturePortTypeImpl.java \
src/examples/webservices/wsdlc/TemperaturePortTypeImpl.java

9. 更新されたJWS実装クラスに対してjwsc Antタスクを実行するbuild-serviceターゲットを、build.xmlファイルに追加します。jwscのcompiledWsdl属性を使用して、wsdlc Antタスクによって生成されるJARファイルの名前を指定します。

<taskdef name="jwsc"
classname="weblogic.wsee.tools.anttasks.JwscTask" />
<target name="build-service">
<jwsc
srcdir="src"
destdir="${ear-dir}">
<jws file="examples/webservices/wsdlc/TemperaturePortTypeImpl.java"
compiledWsdl="${compiledWsdl-dir}/TemperatureService_wsdl.jar"
type="JAXRPC">
<WLHttpTransport
contextPath="temp" serviceUri="TemperatureService"
portName="TemperaturePort">
</WLHttpTransport>
</jws>
</jwsc>
</target>

上記の例で注目すべき点は以下のとおりです。

- <jws>要素のtype属性では、Webサービスのタイプ(JAX-WSまたはJAX-RPC)が指定されています。

- jwsc Antタスクの<jws>要素の<WLHttpTransport>子要素では、HTTP/Sトランスポートを介してWebサービスを呼び出す際に使用されるURLのコンテキスト・パスとサービスURIセクションに加え、生成されるWSDLのポートの名前も指定されています。この値は、@WLHttpTransport属性を使用してJWSファイルで指定されている値をオーバーライドします。

10. build-serviceターゲットを実行してデプロイ可能なWebサービスを生成します。

prompt> ant build-service

JWSファイルを更新して再ビルドする場合、このターゲットを再実行します。

11. WebサービスをデプロイするWebLogic Serverインスタンスを起動します。

12. WebLogic Server管理コンソールまたはwldeploy Antタスクを使用して、エンタープライズ・アプリケーションにパッケージ化されたWebサービスをWebLogic Serverにデプロイします。いずれの場合でも、outputディレクトリにあるwsdlcEarエンタープライズ・アプリケーションをデプロイします。
wldeploy Antタスクを使用するには、以下のターゲットをbuild.xmlファイルに追加します。

<taskdef name="wldeploy"
classname="weblogic.ant.taskdefs.management.WLDeploy"/>
<target name="deploy">
<wldeploy action="deploy" name="wsdlcEar"
source="output/wsdlcEar" user="${wls.username}"
password="${wls.password}" verbose="true"
adminurl="t3://${wls.hostname}:${wls.port}"
targets="${wls.server.name}" />
</target>

wls.username、wls.password、wls.hostname、wls.port、およびwls.server.nameの値は、ご使用のWebLogic Serverインスタンスの対応する値で置き換えます。

deployターゲットを実行して、WARファイルをデプロイします。

prompt> ant deploy

13. ブラウザでWSDLを呼び出して、Webサービスが正しくデプロイされていることをテストします。

http://host:port/temp/TemperatureService?WSDL

上記のURLのコンテキスト・パスとサービスURIの部分は元の黄金のWSDLで指定されています。WebLogic Serverインスタンスのホスト名とポートを使用します。デプロイされたWSDLファイルと元のWSDLファイルは、エンドポイント・アドレスのホストとポート以外は同じであることに注目してください。

build.xmlファイルでclean、build-service、undeploy、deployの各ターゲットを使用すると、開発プロセスの一環としてWebサービスの更新、再ビルド、アンデプロイおよび再デプロイを繰り返し実行できます。

Webサービスを実行するには、そのWebサービスを呼び出すクライアントを作成する必要があります。Webサービスを呼び出すJavaクライアント・アプリケーションの作成例については、「Java SEクライアントからのWebサービスの呼出し」を参照してください。

サンプルWSDLファイル

<?xml version="1.0"?>
<definitions
name="TemperatureService"
targetNamespace="http://www.xmethods.net/sd/TemperatureService.wsdl"
xmlns:tns="http://www.xmethods.net/sd/TemperatureService.wsdl"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns="http://schemas.xmlsoap.org/wsdl/" >
<message name="getTempRequest">
<part name="zip" type="xsd:string"/>
</message>
<message name="getTempResponse">
<part name="return" type="xsd:float"/>
</message>
<portType name="TemperaturePortType">
<operation name="getTemp">
<input message="tns:getTempRequest"/>
<output message="tns:getTempResponse"/>
</operation>
</portType>
<binding name="TemperatureBinding" type="tns:TemperaturePortType">
<soap:binding style="document"
transport="http://schemas.xmlsoap.org/soap/http"/>
<operation name="getTemp">
<soap:operation soapAction=""/>
<input>
<soap:body use="literal"
namespace="urn:xmethods-Temperature" />
</input>
<output>
<soap:body use="literal"
namespace="urn:xmethods-Temperature" />
</output>
</operation>
</binding>
<service name="TemperatureService">
<documentation>
Returns current temperature in a given U.S. zipcode
</documentation>
<port name="TemperaturePort" binding="tns:TemperatureBinding">
<soap:address
location="http://localhost:7001/temp/TemperatureService"/>
</port>
</service>
</definitions>

サンプルTemperaturePortType Java実装ファイル

package examples.webservices.wsdlc;
import javax.jws.WebService;
import weblogic.jws.*;
/**
* TemperaturePortTypeImpl class implements web service endpoint
* interface TemperaturePortType */
@WebService(
serviceName="TemperatureService",
targetNamespace="http://www.xmethods.net/sd/TemperatureService.wsdl"
endpointInterface="examples.webservices.wsdlc.TemperaturePortType)
@WLHttpTransport(
contextPath="temp",
serviceUri="TemperatureService",
portName="TemperaturePort")
public class TemperaturePortTypeImpl implements examples.webservices.wsdlc.TemperaturePortType {
public TemperaturePortTypeImpl() { }
public float getTemp(java.lang.String zip) {
return 1.234f;
}
}

TemperatureServiceのサンプルAntビルド・ファイル

以下のbuild.xmlファイルでは、プロパティを使用してファイルを簡素化しています。

<project default="all">
<!-- set global properties for this build -->
<property name="wls.username" value="weblogic" />
<property name="wls.password" value="weblogic" />
<property name="wls.hostname" value="localhost" />
<property name="wls.port" value="7001" />
<property name="wls.server.name" value="myserver" />
<property name="ear.deployed.name" value="wsdlcEar" />
<property name="example-output" value="output" />
<property name="compiledWsdl-dir" value="${example-output}/compiledWsdl" />
<property name="impl-dir" value="${example-output}/impl" />
<property name="ear-dir" value="${example-output}/wsdlcEar" />
<property name="clientclass-dir" value="${example-output}/clientclasses" />
<path id="client.class.path">
<pathelement path="${clientclass-dir}"/>
<pathelement path="${java.class.path}"/>
</path>
<taskdef name="wsdlc"
classname="weblogic.wsee.tools.anttasks.WsdlcTask"/>
<taskdef name="jwsc"
classname="weblogic.wsee.tools.anttasks.JwscTask" />
<taskdef name="clientgen"
classname="weblogic.wsee.tools.anttasks.ClientGenTask" />
<taskdef name="wldeploy"
classname="weblogic.ant.taskdefs.management.WLDeploy"/>
<target name="all"
depends="clean,generate-from-wsdl,build-service,deploy,client" />
<target name="clean" depends="undeploy">
<delete dir="${example-output}"/>
</target>
<target name="generate-from-wsdl">
<wsdlc
srcWsdl="wsdl_files/TemperatureService.wsdl"
destJwsDir="${compiledWsdl-dir}"
destImplDir="${impl-dir}"
packageName="examples.webservices.wsdlc" />
</target>
<target name="build-service">
<jwsc
srcdir="src"
destdir="${ear-dir}">
<jws file="examples/webservices/wsdlc/TemperaturePortTypeImpl.java"
compiledWsdl="${compiledWsdl-dir}/TemperatureService_wsdl.jar"
type="JAXRPC">
<WLHttpTransport
contextPath="temp" serviceUri="TemperatureService"
portName="TemperaturePort"/>
</jws>
</jwsc>
</target>
<target name="deploy">
<wldeploy action="deploy" name="${ear.deployed.name}"
source="${ear-dir}" user="${wls.username}"
password="${wls.password}" verbose="true"
adminurl="t3://${wls.hostname}:${wls.port}"
targets="${wls.server.name}" />
</target>
<target name="undeploy">
<wldeploy action="undeploy" name="${ear.deployed.name}"
failonerror="false"
user="${wls.username}" password="${wls.password}" verbose="true"
adminurl="t3://${wls.hostname}:${wls.port}"
targets="${wls.server.name}" />
</target>
<target name="client">
<clientgen
wsdl="http://${wls.hostname}:${wls.port}/temp/TemperatureService?WSDL"
destDir="${clientclass-dir}"
packageName="examples.webservices.wsdlc.client"
type="JAXRPC">
<javac
srcdir="${clientclass-dir}" destdir="${clientclass-dir}"
includes="**/*.java"/>
<javac
srcdir="src" destdir="${clientclass-dir}"
includes="examples/webservices/wsdlc/client/**/*.java"/>
</target>
<target name="run">
<java classname="examples.webservices.wsdlc.client.TemperatureClient"
fork="true" failonerror="true" >
<classpath refid="client.class.path"/>
<arg
line="http://${wls.hostname}:${wls.port}/temp/TemperatureService" />
</java>
</target>
</project>

Java SEクライアントからのWebサービスの呼出し

注意:
この項で説明するように、WebLogic Serverで実行されている(WebLogic Serverクラスパスにアクセスする)任意のJava SEまたはJava EEアプリケーションからWebサービスを呼び出すことができます。WebLogic Serverのライブラリにアクセスできない環境で実行されているスタンドアロンJavaアプリケーションのサポートの詳細は、「Webサービス呼出し時のスタンドアロン・クライアントJARファイルの使用」を参照してください。

クライアント・アプリケーションからデプロイ済のWebサービスの操作を呼び出す場合、WebサービスはWebLogic Serverにデプロイされている場合と、.NETなどの他のアプリケーション・サーバーにデプロイされている場合があります。知る必要があるのは、パブリック・コントラクト・ファイル、つまりWSDLのURLのみです。

Javaクライアント・アプリケーションを記述する他に、clientgen WebLogic WebサービスAntタスクを実行して、クライアント・アプリケーションがWebサービス操作を呼び出すために必要なアーティファクトも生成する必要があります。次のようなアーティファクトがあります。

- 呼出しの対象となる特定のWebサービスに対するJAX-RPC StubおよびServiceインタフェース実装のJavaクラス。

- WSDLファイルで指定されたユーザー定義XMLスキーマ・データ型のJavaクラス。

- Javaのユーザー定義のデータ型と、WSDLファイル内で指定されたそのデータ型に対応するXMLスキーマ型の間のマッピングに関する情報を格納するJAX-RPCマッピング・デプロイメント記述子ファイル。

- WSDLファイルのクライアント側のコピー。

次の例では、「ユーザー定義のデータ型を使用するWebサービスの作成」で説明している、ComplexService WebLogic WebサービスのechoComplexType操作を呼び出すJavaクライアント・アプリケーションを作成する方法を示します。echoComplexType操作は、ユーザー定義のデータ型であるBasicStructをパラメータおよび戻り型として使用します。

注意:
この手順では、ComplexService Webサービスを作成してデプロイ済であると仮定しています。

1. WebLogic Server環境を設定します。
コマンド・ウィンドウを開いて、ドメイン・ディレクトリのbinサブディレクトリにあるsetDomainEnv.cmd (Windows)またはsetDomainEnv.sh (UNIX)スクリプトを実行します。WebLogic Serverドメインのデフォルトの場所はORACLE_HOME/user_projects/domains/domainNameです(ORACLE_HOMEはOracle WebLogic Serverのインストール時にOracleホームとして指定したディレクトリ、domainNameはドメインの名前です)。

2. プロジェクト・ディレクトリを作成します。

prompt> mkdir /myExamples/simple_client

3. プロジェクト・ディレクトリの下に、srcディレクトリと、Javaクライアント・アプリケーション(この手順で後述)のパッケージ名に対応するサブディレクトリを作成します。

prompt> cd /myExamples/simple_client
prompt> mkdir src/examples/webservices/simple_client

4. プロジェクト・ディレクトリ内に標準のAnt build.xmlファイルを作成し、taskdef Antタスクを追加して、clientgenタスクの完全修飾Javaクラス名を指定します。

<project name="webservices-simple_client" default="all">
<taskdef name="clientgen"
classname="weblogic.wsee.tools.anttasks.ClientGenTask" />
</project>

完全なサンプルbuild.xmlファイルについては、「Javaクライアント・アプリケーションをビルドするためのサンプルAntビルド・ファイル」を参照してください。完全なbuild.xmlファイルでは、クライアント・クラスの出力ディレクトリの名前を常にハード・コードして使用するのではなく、${clientclass-dir}などのプロパティを使用します。

5. 次のようなclientgenおよびjavac Antタスクの呼出しを、build-clientターゲット内にラップして、build.xmlファイルに追加します。

<target name="build-client">
<clientgen
wsdl="http://${wls.hostname}:${wls.port}/complex/ComplexService?WSDL"
destDir="output/clientclass"
packageName="examples.webservices.simple_client"
type="JAXRPC"/>
<javac
srcdir="output/clientclass" destdir="output/clientclass"
includes="**/*.java"/>
<javac
srcdir="src" destdir="output/clientclass"
includes="examples/webservices/simple_client/*.java"/>
</target>

clientgen Antタスクでは、デプロイされたComplexService WebサービスのWSDLを使用して必要なアーティファクトを生成し、指定されたパッケージ名を使用してそれらをoutput/clientclassディレクトリに格納します。変数は、WebサービスをホストしているWebLogic Serverインスタンスの実際のホスト名とポートに置き換えてください。

clientgen Antタスクはexamples.webservices.complex.BasicStruct JavaBeanクラスも自動的に生成します。このクラスは、WSDLで指定されたユーザー定義のデータ型のJava表現です。

build-clientターゲットでは、clientgenの他に標準のjavac Antタスクも指定して、次の手順で説明する簡単なJavaプログラムを含む、すべてのJavaコードをクラス・ファイルにコンパイルします。

clientgen AntタスクのdestFile属性を使用すると、生成されたJavaファイルを自動的にコンパイルして、すべてのアーティファクトをJARファイルにパッケージ化できます。詳細と例については、『Oracle WebLogic Server WebLogic Webサービス・リファレンス』のclientgenに関する項を参照してください。

6. echoComplexType操作を呼び出すJavaクライアント・アプリケーション・ファイルを作成します。
任意のJava IDEまたはテキスト・エディタを開いて、「サンプルJavaクライアント・アプリケーション」で指定されたコードを使用してMain.javaというJavaファイルを作成します。

Mainクライアント・アプリケーションは、1つの引数(WebサービスのWSDL URL)を取ります。アプリケーションは標準JAX-RPCのガイドラインに従って、clientgenによって生成されたServiceインタフェースのWebサービス固有の実装を使用してWebサービスの操作を呼び出します。また、アプリケーションは、clientgen Antタスクで生成されたBasicStructユーザー定義データ型をインポートして使用します(このデータ型はechoStruct操作のパラメータおよび戻り値として使用されます)。詳細は、第6章「JAX-RPC Webサービス・クライアントの開発」を参照してください。

7. Main.javaファイルをメイン・プロジェクト・ディレクトリのsrc/examples/webservices/simple_clientサブディレクトリに保存します。

8. コマンド・ラインでbuild-clientターゲットを指定して、clientgenおよびjavac Antタスクを実行します。

prompt> ant build-client

output/clientclassディレクトリを見て、clientgen Antタスクによって生成されたファイルとアーティファクトを確認します。

9. Mainアプリケーションの実行に使用される以下のターゲットをbuild.xmlファイルに追加します。

<path id="client.class.path">
<pathelement path="output/clientclass"/>
<pathelement path="${java.class.path}"/>
</path>
<target name="run" >
<java fork="true"
classname="examples.webservices.simple_client.Main"
failonerror="true" >
<classpath refid="client.class.path"/>
<arg line="http://${wls.hostname}:${wls.port}/complex/ComplexService" />
</java>
</target>

runターゲットはMainアプリケーションを呼び出し、デプロイされたWebサービスのWSDL URLを1つの引数として渡します。classpath要素では、<path>タスクで作成される参照を使用して、CLASSPATHにclientclassディレクトリが追加されます。

10. runターゲットを実行してechoComplexType操作を呼び出します。

prompt> ant run

呼出しに成功すると、次のような最終出力が表示されます。

run:
[java] echoComplexType called. Result: 999, Hello Struct

build.xmlファイルのbuild-clientおよびrunターゲットを使用して、開発プロセスの一環としてJavaクライアント・アプリケーションを繰返し更新、再ビルド、および実行できます。

サンプルJavaクライアント・アプリケーション

以下に、echoComplexType操作を呼び出す簡単なJavaクライアント・アプリケーションを示します。

package examples.webservices.simple_client;
import java.rmi.RemoteException;
import javax.xml.rpc.ServiceException;
// import the BasicStruct class, used as a param and return value of the
// echoComplexType operation. The class is generated automatically by
// the clientgen Ant task.
import examples.webservices.complex.BasicStruct;
/**
* This is a simple Java client application that invokes the
* echoComplexType operation of the ComplexService web service.
*/
public class Main {
public static void main(String[] args)
throws ServiceException, RemoteException {
ComplexService service = new ComplexService_Impl (args[0] + "?WSDL" );
ComplexPortType port = service.getComplexServicePort();
BasicStruct in = new BasicStruct();
in.setIntValue(999);
in.setStringValue("Hello Struct");
BasicStruct result = port.echoComplexType(in);
System.out.println("echoComplexType called. Result: " + result.getIntValue() + ", " + result.getStringValue());
}
}

Javaクライアント・アプリケーションをビルドするためのサンプルAntビルド・ファイル

次のbuild.xmlファイルでは、Javaクライアント・アプリケーションをビルドするタスクが定義されています。この例では、プロパティを使用してファイルを簡素化しています。

<project name="webservices-simple_client" default="all">
<!-- set global properties for this build -->
<property name="wls.hostname" value="localhost" />
<property name="wls.port" value="7001" />
<property name="example-output" value="output" />
<property name="clientclass-dir" value="${example-output}/clientclass" />
<path id="client.class.path">
<pathelement path="${clientclass-dir}"/>
<pathelement path="${java.class.path}"/>
</path>
<taskdef name="clientgen"
classname="weblogic.wsee.tools.anttasks.ClientGenTask" />
<target name="clean" >
<delete dir="${clientclass-dir}"/>
</target>
<target name="all" depends="clean,build-client,run" />
<target name="build-client">
<clientgen
type="JAXRPC"
wsdl="http://${wls.hostname}:${wls.port}/complex/ComplexService?WSDL"
destDir="${clientclass-dir}"
packageName="examples.webservices.simple_client"/>
<javac
srcdir="${clientclass-dir}" destdir="${clientclass-dir}"
includes="**/*.java"/>
<javac
srcdir="src" destdir="${clientclass-dir}"
includes="examples/webservices/simple_client/*.java"/>
</target>
<target name="run" >
<java fork="true"
classname="examples.webservices.simple_client.Main"
failonerror="true" >
<classpath refid="client.class.path"/>
<arg line="http://${wls.hostname}:${wls.port}/complex/ComplexService" />
</java>
</target>
</project>

WebLogic WebサービスからのWebサービスの呼出し

デプロイ済のWebLogic Webサービス内からWebサービス(WebLogic、.NETなど)を呼び出すこともできます。

WebサービスをWebLogic Webサービスから呼び出すための手順は、「Java SEクライアントからのWebサービスの呼出し」で説明している手順と似ていますが、クライアント・スタブを生成するclientgen Antタスクを実行するのではなく、jwsc Antタスク内で<jws>の<clientgen>子要素を使用する点が異なります。jwsc Antタスクでは、生成されたクライアント・スタブが自動的に呼出し側のWebサービスのWARファイルにパッケージ化されるため、即座にWebサービスからアクセスできるようになります。その後で、標準JAX-RPCのプログラミング・ガイドラインに従って、他のWebサービスを呼び出すWebサービスを実装するJWSファイルを作成します。

次の例では、「ユーザー定義のデータ型を使用するWebサービスの作成」で説明したComplexService WebサービスのechoComplexType操作を呼び出すJWSファイルを記述する方法を示します。

注意:
ComplexService Webサービスは正常にデプロイ済であると想定しています。

1. WebLogic Server環境を設定します。
コマンド・ウィンドウを開いて、ドメイン・ディレクトリのbinサブディレクトリにあるsetDomainEnv.cmd (Windows)またはsetDomainEnv.sh (UNIX)スクリプトを実行します。WebLogic Serverドメインのデフォルトの場所はORACLE_HOME/user_projects/domains/domainNameです(ORACLE_HOMEはOracle WebLogic Serverのインストール時にOracleホームとして指定したディレクトリ、domainNameはドメインの名前です)。

2. プロジェクト・ディレクトリを作成します。

prompt> mkdir /myExamples/service_to_service

3. プロジェクト・ディレクトリの下に、srcディレクトリと、JWSおよびクライアント・アプリケーション・ファイル(この手順で後述)のパッケージ名に相当するサブディレクトリを作成します。

prompt> cd /myExamples/service_to_service
prompt> mkdir src/examples/webservices/service_to_service

4. ComplexService Webサービスを呼び出すWebサービスを実装するJWSファイルを作成します。
任意のJava IDEまたはテキスト・エディタを開いて、「サンプルClientServiceImpl.java JWSファイル」で指定されたJavaコードを使用してClientServiceImpl.javaというJavaファイルを作成します。

サンプルJWSファイルでは、1つのパブリック・メソッドcallComplexService()を含むClientServiceImplというJavaクラスが示されています。このJavaクラスでは、後でjwsc Antタスクで生成されるJAX-RPCスタブと、BasicStruct Java Bean(同じくclientgenで生成されるもので、ComplexService WebサービスのechoComplexType操作のパラメータと戻り値のデータ型)をインポートします。

ClientServiceImpl Javaクラスでは1つのメソッドcallComplexService()を定義しており、このメソッドはComplexService WebサービスのechoComplexType操作に渡されるBasicStructと、ComplexService WebサービスのURLという2つのパラメータを取ります。メソッドは標準のJAX-RPC APIを使用し、jwscによって生成されたスタブを使用してComplexServiceのServiceとPortTypeを取得した後、echoComplexType操作を呼び出します。

5. ClientServiceImpl.javaファイルをsrc/examples/webservices/service_to_serviceディレクトリに保存します。

6. プロジェクト・ディレクトリ内に標準のAnt build.xmlファイルを作成して、次のタスクを追加します。

<project name="webservices-service_to_service" default="all">
<taskdef name="jwsc"
classname="weblogic.wsee.tools.anttasks.JwscTask" />
</project>

taskdefタスクでは、jwsc Antタスクの完全なクラス名を定義しています。

この手順で説明される追加のターゲット(clean、deploy、undeploy、client、runなど)が含まれている、完全なサンプルbuild.xmlファイルについては、「ClientServiceをビルドするためのサンプルAntビルド・ファイル」を参照してください。完全なbuild.xmlファイルでは、EARディレクトリの名前を常にハード・コード化して使用するのではなく、${ear-dir}などのプロパティも使用しています。

7. 次のようなjwsc Antタスクの呼出しを、build-serviceターゲット内にラップして、build.xmlファイルに追加します。

<target name="build-service">
<jwsc
srcdir="src"
destdir="output/ClientServiceEar" >
<jws
file="examples/webservices/service_to_service/ClientServiceImpl.java"
type="JAXRPC">
<WLHttpTransport
contextPath="ClientService" serviceUri="ClientService"
portName="ClientServicePort"/>
<clientgen
type="JAXRPC"
wsdl="http://${wls.hostname}:${wls.port}/complex/ComplexService?WSDL"
packageName="examples.webservices.complex" />
</jws>
</jwsc>
</target>

この例では、jwsc Antタスクの<jws>要素の<clientgen>子要素で、jwscがJWSファイルをコンパイルするだけでなく、WSDLファイルに記述されているWebサービスを呼び出すために必要なクライアント・アーティファクトも生成およびコンパイルすることを指定しています。

この例では、パッケージ名はexamples.webservices.complexに設定され、これはクライアント・アプリケーションのパッケージ名examples.webservices.simple_clientとは異なります。そのため、クライアント・アプリケーションの適切なクラス・ファイルをインポートする必要があります。

import examples.webservices.complex.BasicStruct;
import examples.webservices.complex.ComplexPortType;
import examples.webservices.complex.ComplexService;

パッケージ名がクライアント・アプリケーションと同じパッケージ名に設定されている場合、インポートの呼出しは省略できます。

8. コマンド・ラインでbuild-serviceターゲットを指定して、jwsc Antタスクを実行します。

prompt> ant build-service

9. WebサービスをデプロイするWebLogic Serverインスタンスを起動します。

10. WebLogic Server管理コンソールまたはwldeploy Antタスクを使用して、エンタープライズ・アプリケーションにパッケージ化されたWebサービスをWebLogic Serverにデプロイします。いずれの場合でも、outputディレクトリにあるClientServiceEarエンタープライズ・アプリケーションをデプロイします。
wldeploy Antタスクを使用するには、以下のターゲットをbuild.xmlファイルに追加します。

<taskdef name="wldeploy"
classname="weblogic.ant.taskdefs.management.WLDeploy"/>
<target name="deploy">
<wldeploy action="deploy" name="ClientServiceEar"
source="ClientServiceEar" user="${wls.username}"
password="${wls.password}" verbose="true"
adminurl="t3://${wls.hostname}:${wls.port}"
targets="${wls.server.name}" />
</target>

wls.username、wls.password、wls.hostname、wls.port、およびwls.server.nameの値は、ご使用のWebLogic Serverインスタンスの対応する値で置き換えます。

deployターゲットを実行して、WARファイルをデプロイします。

prompt> ant deploy

11. ブラウザでWSDLを呼び出して、Webサービスが正しくデプロイされていることをテストします。

http://host:port/ClientService/ClientService?WSDL

Webサービスを呼び出すJavaクライアント・アプリケーションの作成例については、「Java SEクライアントからのWebサービスの呼出し」を参照してください。

サンプルClientServiceImpl.java JWSファイル

echoComplexType操作を呼び出す簡単なWebサービス・クライアント・アプリケーションを次に示します。

package examples.webservices.service_to_service;
import java.rmi.RemoteException;
import javax.xml.rpc.ServiceException;
import javax.jws.WebService;
import javax.jws.WebMethod;
import weblogic.jws.WLHttpTransport;
// Import the BasicStruct data type, generated by clientgen and used
// by the ComplexService Web Service
import examples.webservices.complex.BasicStruct;
// Import the JAX-RPC Stubs for invoking the ComplexService Web Service.
// Stubs generated by clientgen
import examples.webservices.service_to_service.ComplexPortType;
import examples.webservices.service_to_service.ComplexService_Impl;
import examples.webservices.service_to_service.ComplexService;
@WebService(name="ClientPortType", serviceName="ClientService",
targetNamespace="http://examples.org")
@WLHttpTransport(contextPath="ClientService", serviceUri="ClientService",
portName="ClientServicePort")
public class ClientServiceImpl {
@WebMethod()
public String callComplexService(BasicStruct input, String serviceUrl)
throws ServiceException, RemoteException
{
// Create service and port stubs to invoke ComplexService
ComplexService service = new ComplexService_Impl(serviceUrl + "?WSDL");
ComplexPortType port = service.getComplexServicePort();
// Invoke the echoComplexType operation of ComplexService
BasicStruct result = port.echoComplexType(input);
System.out.println("Invoked ComplexPortType.echoComplexType." );
return "Invoke went okay!  Here's the result: '" + result.getIntValue() + ",  " + result.getStringValue() + "'";
}
}

ClientServiceをビルドするためのサンプルAntビルド・ファイル

次のbuild.xmlファイルでは、クライアント・アプリケーションをビルドするタスクが定義されています。この例では、プロパティを使用してファイルを簡素化しています。

以下のbuild.xmlファイルでは、プロパティを使用してファイルを簡素化しています。

<project name="webservices-service_to_service" default="all">
<!-- set global properties for this build -->
<property name="wls.username" value="weblogic" />
<property name="wls.password" value="weblogic" />
<property name="wls.hostname" value="localhost" />
<property name="wls.port" value="7001" />
<property name="wls.server.name" value="myserver" />
<property name="ear.deployed.name" value="ClientServiceEar" />
<property name="example-output" value="output" />
<property name="ear-dir" value="${example-output}/ClientServiceEar" />
<property name="clientclass-dir" value="${example-output}/clientclasses" />
<path id="client.class.path">
<pathelement path="${clientclass-dir}"/>
<pathelement path="${java.class.path}"/>
</path>
<taskdef name="jwsc"
classname="weblogic.wsee.tools.anttasks.JwscTask" />
<taskdef name="clientgen"
classname="weblogic.wsee.tools.anttasks.ClientGenTask" />
<taskdef name="wldeploy"
classname="weblogic.ant.taskdefs.management.WLDeploy"/>
<target name="all" depends="clean,build-service,deploy,client" />
<target name="clean" depends="undeploy">
<delete dir="${example-output}"/>
</target>
<target name="build-service">
<jwsc
srcdir="src"
destdir="${ear-dir}" >
<jws
file="examples/webservices/service_to_service/ClientServiceImpl.java"
type="JAXRPC">
<WLHttpTransport
contextPath="ClientService" serviceUri="ClientService"
portName="ClientServicePort"/>
<clientgen
type="JAXRPC"
wsdl="http://${wls.hostname}:${wls.port}/complex/ComplexService?WSDL"
packageName="examples.webservices.complex" />
</jws>
</jwsc>
</target>
<target name="deploy">
<wldeploy action="deploy" name="${ear.deployed.name}"
source="${ear-dir}" user="${wls.username}"
password="${wls.password}" verbose="true"
adminurl="t3://${wls.hostname}:${wls.port}"
targets="${wls.server.name}" />
</target>
<target name="undeploy">
<wldeploy action="undeploy" name="${ear.deployed.name}"
failonerror="false"
user="${wls.username}"
password="${wls.password}" verbose="true"
adminurl="t3://${wls.hostname}:${wls.port}"
targets="${wls.server.name}" />
</target>
<target name="client">
<clientgen
wsdl="http://${wls.hostname}:${wls.port}/ClientService/ClientService?WSDL"
destDir="${clientclass-dir}"
packageName="examples.webservices.service_to_service.client"
type="JAXRPC"/>
<javac
srcdir="${clientclass-dir}" destdir="${clientclass-dir}"
includes="**/*.java"/>
<javac
srcdir="src" destdir="${clientclass-dir}"
includes="examples/webservices/service_to_service/client/**/*.java"/>
</target>
<target name="run">
<java classname="examples.webservices.service_to_service.client.Main"
fork="true"
failonerror="true" >
<classpath refid="client.class.path"/>
<arg
line="http://${wls.hostname}:${wls.port}/ClientService/ClientService"/>
</java>
</target>
</project>

第II部

基本的なJAX-RPC Webサービスの開発

第II部では、Java API for XML-based RPC (JAX-RPC)を使用して基本的なWebLogic Webサービスを開発する方法について説明します。

ここで説明するトピックは次のとおりです。

- 第3章「JAX-RPC Webサービスの開発」

- 第4章「JWSファイルのプログラミング」

- 第5章「データ・バインディングの理解」

3 JAX-RPC Webサービスの開発

この章では、Java API for XML-based RPC (JAX-RPC)を使用したWebLogic Webサービスの反復的な開発プロセスについて説明します。

この章の内容は次のとおりです。

- WebLogic Webサービス・プログラミング・モデルの概要

- Webサービス機能用のドメイン構成

- Javaから開始するWebLogic Webサービスの開発: 主な手順

- WSDLファイルから開始するWebLogic Webサービスの開発: 主な手順

- 基本的なAnt build.xmlファイルの作成

- jwsc WebLogic WebサービスAntタスクの実行

- wsdlc WebLogic WebサービスAntタスクの実行

- wsdlcで生成される途中まで作成済みのJWS実装クラス・ファイルの更新

- WebLogic Webサービスのデプロイとアンデプロイ

- WebサービスのWSDLの参照

- 動的なWSDLで指定されたサーバー・アドレスの構成

- Webサービスのテスト

- WebサービスのWebLogic分割開発ディレクトリ環境への統合

WebLogic Webサービス・プログラミング・モデルの概要

WebLogic Webサービスのプログラミング・モデルはJWSファイル(JWSアノテーションを使用してWebサービスの形式や動作を指定したJavaファイル)と、JWSファイルを実行するAntタスクを中心に展開されます。JWSアノテーションは、JDKのバージョン5.0で導入されたメタデータ機能(http://www.jcp.org/en/jsr/detail?id=175にあるJSR-175により指定されています)に基づいており、Web Services Metadata for the Java Platform仕様(JSR-181) (http://www.jcp.org/en/jsr/detail?id=181に記載されています)で定義されている標準のアノテーションのほかに、追加のアノテーションを含みます。サポートされるJWSアノテーションの完全なリストは、『Oracle WebLogic Server WebLogic Webサービス・リファレンス』のWebサービスのアノテーション・サポートに関する項を参照してください。このプログラミング・モデルの詳細は、『Oracle WebLogic Server WebLogic Webサービスの理解』を参照してください。

以下の項では、Webサービスを繰返し開発する主要な手順を、Javaから開始する場合、または既存のWSDLファイルから開始する場合について説明します。

- Javaから開始するWebLogic Webサービスの開発: 主な手順

- WSDLファイルから開始するWebLogic Webサービスの開発: 主な手順

反復的な開発とは、希望どおりに動作するまで、Webサービスを繰返しコーディング、コンパイル、パッケージ化、デプロイ、およびテストできるように、開発環境を設定することです。WebLogic Webサービス・プログラミング・モデルでは、Antタスクを使用して、反復的な開発のほとんどの手順を実行します。一般に、すべての手順に対応するターゲットを含んだ1つのbuild.xmlファイルを作成して、そのターゲットを繰返し実行します。JWSファイルを新しいJavaコードで更新したら、その更新が期待どおりに動作することをテストします。

Webサービスを開発するために、この項で説明したコマンド・ライン・ツールの他に、Oracle JDeveloperなどのIDEも使用できます。詳細は、『Oracle WebLogic Server WebLogic Webサービスの理解』のOracle IDEを使用したWebサービスの構築に関する項を参照してください。

Webサービス機能用のドメイン構成

WebLogic Serverドメインを作成したら、構成ウィザードでWebサービス固有の拡張テンプレートを使用してドメインを更新し、特定のWebLogic Webサービス機能で必要になるリソースを自動的に構成できます。この拡張テンプレートの使用は必須ではありませんが、これを使用することでJMSおよびJDBCリソースの構成を大幅に簡略化できます。

Webサービス拡張テンプレートを使用すると、以下の機能で必要になるリソースを自動的に構成できます。

- Webサービスの信頼性のあるメッセージング

- バッファリング

- JMSトランスポート

注意:
Webサービスのリソースを含まないドメインは、Webサービス以外のシナリオおよび非同期のリクエスト/レスポンスが含まれないWebサービス・シナリオにおいて、適切に起動および実行されます。ただし、サーバー・ログに、非同期リソースが構成されていないこと、およびWebサービスの非同期レスポンス・サービスが完全にデプロイされていないことを示すINFOメッセージが表示されます。

次の各手順は、Webサービスの高度な機能を使用するようにドメインを自動的に構成するためのドメインの作成方法および拡張方法を示しています。構成ウィザードを使用してWebLogic Serverドメインを作成および更新する詳細な手順については、構成ウィザードを使用したWebLogicドメインの作成を参照してください。

高度なWebサービス機能用に自動的に構成されるドメインを作成するには:

1. 構成ウィザードを起動します。

2. 「ようこそ」ウィンドウで、「新しいWebLogicドメインの作成」を選択します。

3. 「次へ」をクリックします。

4. 「以下の製品をサポートするために、自動的に構成されたドメインを生成する」を選択し、「WebLogic Advanced Web Services for JAX-RPC Extension」を選択します。

5. 「次へ」をクリックします。

6. ドメインの名前と場所を入力し、「次へ」をクリックします。

7. 管理者ユーザーの名前とパスワードを構成し、「次へ」をクリックします。

8. サーバーの起動モードとJDKを構成し、「次へ」をクリックします。

9. JMSサービス、ファイル・ストア、その他の機能をさらに構成する場合は、「オプションの構成を選択」画面で項目を選択します。通常はこれは行いません。
それ以外の場合は、すべての項目が選択解除された状態で、「次へ」をクリックします。

10. 「構成のサマリー」画面が表示されたら、ドメインの詳細を検証して「作成」をクリックします。

11. 終了するには「完了」をクリックします。

既存のドメインを拡張してこれらのWebサービス機能用に自動的に構成するには:

1. 構成ウィザードを起動します。

2. 「ようこそ」ウィンドウで、「既存のWebLogicドメインの拡張」を選択します。

3. 「次へ」をクリックします。

4. 拡張テンプレートを適用するドメインを選択します。

5. 「次へ」をクリックします。

6. 「以下の追加製品をサポートするために、自動的にドメインを拡張する」を選択し、「WebLogic Advanced Web Services for JAX-RPC Extension」を選択します。

7. 「次へ」をクリックします。

8. JMSサービスやファイル・ストアをさらに構成する場合は、「オプションの構成を選択」画面で項目を選択します。通常はこれは行いません。
それ以外の場合は、すべての項目が選択解除された状態で、「次へ」をクリックします。

9. 拡張するドメインが正しいことを確認して「拡張」をクリックします。

10. 終了するには「完了」をクリックします。

Javaから開始するWebLogic Webサービスの開発: 主な手順

この節では、Javaから開始してWebLogic Webサービスを開発する一般的な手順について説明します。つまり、JWSファイルを最初からコーディングして、サービスについて記述するWSDLファイルを後で生成するという手順です。このプロセスの具体的な例については、第2章「JAX-RPC Webサービス開発者向けサンプル」を参照してください。

以下に示すのは推奨の手順に過ぎません。独自の開発環境を設定してある場合は、WebLogic Webサービスを開発するために既存の環境を更新する際のガイドとして、この手順を利用できます。

注意:
この手順では、WebLogic Webサービスの分割開発ディレクトリ環境は使用しません。この開発環境を使用していて、Webサービスの開発をそこに統合する場合の詳細は、「WebサービスのWebLogic分割開発ディレクトリ環境への統合」を参照してください。

表3-1 Javaから開始するWebサービスの開発手順

#

手順

説明

1

環境を設定します。

コマンド・ウィンドウを開いて、ドメイン・ディレクトリのbinサブディレクトリにあるsetDomainEnv.cmd (Windows)またはsetDomainEnv.sh (UNIX)コマンドを実行します。WebLogic Serverドメインのデフォルトの場所はORACLE_HOME/user_projects/domains/domainNameです(ORACLE_HOMEはOracle WebLogic Serverのインストール時にOracleホームとして指定したディレクトリ、domainNameはドメインの名前です)。

2

プロジェクト・ディレクトリを作成します。

JWSファイル、ユーザー定義のデータ型のJavaソース、Ant build.xmlファイルが格納されるプロジェクト・ディレクトリを作成します。このディレクトリには自由に名前を付けることができます。

3

Webサービスを実装するJWSファイルを作成します。

「JWSファイルのプログラミング: 一般的な手順」を参照してください。

4

ユーザー定義のデータ型を作成する(オプション)

Webサービスでユーザー定義のデータ型を使用する場合は、その型を記述したJavaBeanを作成します。「ユーザー定義のJavaデータ型のプログラミング」を参照してください。

5

基本のAntビルド・ファイルbuild.xmlを作成します。

「基本的なAnt build.xmlファイルの作成」を参照してください。

6

JWSファイルに対してjwsc Antタスクを実行します。

ソース・コード、データ・バインディング・アーティファクト、デプロイメント記述子などがjwsc Antタスクによって出力ディレクトリ内に生成されます。この出力ディレクトリには、エンタープライズ・アプリケーションのディレクトリ構造も生成されます。この展開されたディレクトリは、後で反復的な開発プロセスの一環としてWebLogic Serverにデプロイします。「jwsc WebLogic WebサービスAntタスクの実行」を参照してください。

7

WebサービスをWebLogic Serverにデプロイします。

「WebLogic Webサービスのデプロイとアンデプロイ」を参照してください。

8

WebサービスのWSDLを参照します。

WebサービスのWSDLを参照して、Webサービスが適切にデプロイされたことを確認します。「WebサービスのWSDLの参照」を参照してください。

9

Webサービスをテストします。

「Webサービスのテスト」を参照してください。

10

Webサービスを編集する(オプション)

Webサービスに変更を加えるには、JWSファイルを更新し、「WebLogic Webサービスのデプロイとアンデプロイ」の説明のとおりにWebサービスをアンデプロイしてから、jwsc Antタスクの実行(ステップ6)から始まる手順を繰り返します。

Webサービスを呼び出すクライアント・アプリケーションの作成方法については、第4章「JWSファイルのプログラミング」を参照してください。

WSDLファイルから開始するWebLogic Webサービスの開発: 主な手順

この項では、既存のWSDLファイルに基づいてWebLogic Webサービスを開発する一般的な手順について説明します。このプロセスの具体的な例については、第3章「JAX-RPC Webサービスの開発」を参照してください。

以下に示すのは推奨の手順に過ぎません。独自の開発環境を設定してある場合は、WebLogic Webサービスを開発するために既存の環境を更新する際のガイドとして、この手順を利用できます。

この手順では既存のWSDLファイルがすでにあることを前提としています。

注意:
この手順では、WebLogic Webサービスの分割開発ディレクトリ環境は使用しません。この開発環境を使用していて、Webサービスの開発をそこに統合する場合の詳細は、「WebサービスのWebLogic分割開発ディレクトリ環境への統合」を参照してください。

表3-2 Javaから開始するWebサービスの開発手順

#

手順

説明

1

環境を設定します。

コマンド・ウィンドウを開いて、ドメイン・ディレクトリのbinサブディレクトリにあるsetDomainEnv.cmd (Windows)またはsetDomainEnv.sh (UNIX)コマンドを実行します。WebLogic Serverドメインのデフォルトの場所はORACLE_HOME/user_projects/domains/domainNameです(ORACLE_HOMEはOracle WebLogic Serverのインストール時にOracleホームとして指定したディレクトリ、domainNameはドメインの名前です)。

2

プロジェクト・ディレクトリを作成します。

生成されるアーティファクトやAnt build.xmlファイルが格納されるプロジェクト・ディレクトリを作成します。

3

基本のAntビルド・ファイルbuild.xmlを作成します。

「基本的なAnt build.xmlファイルの作成」を参照してください。

4

WSDLファイルを、build.xml Antビルド・ファイルから読取り可能なディレクトリに置きます。

たとえば、WSDLファイルをプロジェクト・ディレクトリのwsdl_files子ディレクトリに置くことができます。

5

WSDLファイルに対してwsdlc Antタスクを実行します。

JWSサービス・エンドポイント・インタフェース(SEI)、途中まで作成済みのJWSクラス・ファイル、XMLスキーマ・データ型を表すJavaBeanなどが、wsdlc Antタスクによって出力ディレクトリ内に生成されます。「wsdlc WebLogic WebサービスAntタスクの実行」を参照してください。

6

wsdlc Antタスクにより生成された途中まで作成済みのJWSファイルを更新します。

wsdlc Antタスクでは途中まで作成済のJWSファイルが生成されます。Webサービスが希望どおりに動作するようにするには、独自のビジネス・コードを追加する必要があります。「wsdlcで生成される途中まで作成済のJWS実装クラス・ファイルの更新」を参照してください。

7

JWSファイルに対してjwsc Antタスクを実行します。

wsdlc Antタスクによって生成されたアーティファクトと更新したJWS実装ファイルを指定して、Webサービスを実装するエンタープライズ・アプリケーションを生成します。「jwsc WebLogic WebサービスAntタスクの実行」を参照してください。

8

WebサービスをWebLogic Serverにデプロイします。

「WebLogic Webサービスのデプロイとアンデプロイ」を参照してください。

9

WebサービスのWSDLを参照します。

WebサービスのWSDLを参照して、Webサービスが適切にデプロイされたことを確認します。「WebサービスのWSDLの参照」を参照してください。

デプロイ済みWebサービスのWSDLを呼び出すときに使用するURLは、基本的に、元のWSDL内の<address>要素のlocation属性の値と同じです(ただし、ホストとポートの値が、サービスをデプロイしたWebLogic Serverインスタンスのホストとポートに対応する場合を除きます)。これは、wsdlc AntタスクがJWS実装ファイル内の@WLHttpTransportアノテーションのcontextPathおよびserviceURIの値を生成し、それらの値を合わせると、元のWSDLで指定されたエンドポイント・アドレスと同じURIが構成されるため。

10

Webサービスをテストします。

「Webサービスのテスト」を参照してください。

11

Webサービスを編集する(オプション)

Webサービスに変更を加えるには、JWSファイルを更新し、「WebLogic Webサービスのデプロイとアンデプロイ」の説明のとおりにWebサービスをアンデプロイしてから、jwsc Antタスクの実行(ステップ6)から始まる手順を繰り返します。

Webサービスを呼び出すクライアント・アプリケーションの作成方法については、第6章「JAX-RPC Webサービス・クライアントの開発」を参照してください。

基本的なAnt build.xmlファイルの作成

Antでは、XMLで記述されたビルド・ファイル(デフォルト名はbuild.xml)を使用します。このファイルには、<project>ルート要素と、Webサービス開発プロセスのさまざまな段階を指定した1つまたは複数のターゲットが含まれています。各ターゲットには、1つまたは複数のタスク、または実行可能なコードが含まれています。この節では、基本的なAntビルド・ファイルの作成方法について説明し、その後の節では、Webサービス開発プロセスのさまざまな段階(jwsc Antタスクを実行してJWSファイルを処理する、WebサービスをWebLogic Serverにデプロイする、など)の実行方法を指定したターゲットをビルド・ファイルに追加する方法について説明します。

以下のスケルトンのbuild.xmlファイルでは、以降の項で追加される他のすべてのターゲットを呼び出す、デフォルトのallターゲットを指定しています。

<project default="all">
<target name="all"
depends="clean,build-service,deploy" />
<target name="clean">
<delete dir="output" />
</target>
<target name="build-service">
<!--add jwsc and related tasks here -->
</target>
<target name="deploy">
<!--add wldeploy task here -->
</dftarget>
</project>

jwsc WebLogic WebサービスAntタスクの実行

jwsc Antタスクは、JWSアノテーションを含むJWSファイルを入力として取り、WebLogic Webサービスの作成に必要なアーティファクトをすべて生成します。JWSファイルは、最初から自分でコーディングしたものでも、wsdlc Antタスクによって生成されたものでもかまいません。jwscによって生成されるアーティファクトには、次のものがあります。

- JSR-109 Webサービスのクラス・ファイル。

- 必要な全デプロイメント記述子。以下を含みます。

- 標準のWebサービス・デプロイメント記述子(webservices.xml)およびWebLogic固有のWebサービス・デプロイメント記述子(weblogic-webservices.xml)。

- JAX-RPCマッピング・ファイル。

- Javaクラス実装のWebサービスweb.xmlおよびweblogic.xml。

- EJB実装のWebサービスejb-jar.xmlおよびweblogic-ejb-jar.xml。

- Earデプロイメント記述子ファイルapplication.xmlおよびweblogic-application.xml。

- Webサービス操作のパラメータまたは戻り値として使用されるJavaユーザー定義データ型のXMLスキーマ表現。

- Webサービスの内容を外部に公開する形で記述したWSDLファイル。

これらのアーティファクトは、wsdlc Antタスクによってすでに生成され、JARファイル内にパッケージ化されているため、wsdlc Antタスクによって生成されたJWSファイルに対してjwsc Antタスクを実行しても、jwscタスクによってはアーティファクトは生成されません。この場合、jwsc Antタスクの属性を使用して、このwsdlc生成JARファイルを指定します。

必要なアーティファクトをすべて生成した後、jwsc Antタスクは、Javaファイル(JWSファイルも含む)をコンパイルし、コンパイルされたクラスと生成されたアーティファクトを、デプロイ可能なJARアーカイブ・ファイルにパッケージ化して、最後に、そのJARファイルを格納する、展開されたエンタープライズ・アプリケーション・ディレクトリを作成します。

jwsc Antタスクを使用して次の高度なタスクを実行できます。

- 複数のJWSファイルを一度に処理します。生成されたWebサービスをそれぞれ別のWebアプリケーションWARファイルにパッケージ化するか、すべてのWebサービスをグループ化して1つのWARファイルにパッケージ化するかを選択できます。

- 第3章「Webサービスの呼出しに使用されるトランスポートの指定」で説明されているように、クライアント・アプリケーションがWebサービスを呼び出すときに使用できるトランスポート(HTTP/HTTPS/JMS)を指定します。既存の@WLXXXTransportアノテーションをすべてオーバーライドすることも可能です。

- JWSファイル内で呼び出す他のWebサービスのJAX-RPCクライアント・スタブを自動的に生成します。

- 新しいエンタープライズ・アプリケーションまたはWebアプリケーションを生成するのではなく、既存のアプリケーションを更新します。

jwsc Antタスクを実行するには、以下のtaskdefおよびbuild-serviceターゲットをbuild.xmlファイルに追加します。

<taskdef name="jwsc"
classname="weblogic.wsee.tools.anttasks.JwscTask" />
<target name="build-service">
<jwsc
srcdir="src_directory"
destdir="ear_directory"
>
<jws file="JWS_file"
compiledWsdl="WSDLC_Generated_JAR"
type="WebService_type"/>
</jwsc>
</target>

各項目の説明は次のとおりです。

- ear_directory - 生成されたすべてのアーティファクトを格納するエンタープライズ・アプリケーション・ディレクトリ。

- src_directory - JWSファイルのパッケージ名に対応するサブディレクトリを含む最上位ディレクトリ。

- JWS_file - src_directory属性の値に対して相対的なJWSファイルのパス名。

- WSDLC_Generated_JAR - JWS SEIと、既存のWSDLファイルに対応するデータ・バインディング・アーティファクトが含まれる、wsdlc Antタスクによって生成されたJARファイル。

注意:
この属性は、「WSDLから開始する」ユース・ケースでのみ指定します。この手順は「WSDLファイルから開始するWebLogic Webサービスの開発: 主な手順」で説明されています。

- WebService_type - Webサービスの種類。この値は、JAXWSまたはJAXRPCに設定できます。

必須のtaskdef要素では、jwsc Antタスクの完全修飾クラス名を指定します。

jwsc Antタスクのsrcdirおよびdestdir属性のみが必須です。つまり、デフォルトでは、JWSファイルが参照するJavaファイル(JavaBean入力パラメータやユーザー定義の例外など)はJWSファイルと同じパッケージ内にあると想定されています。これに当てはまらない場合は、sourcepath属性を使用して、これらの他のJavaファイルの最上位ディレクトリを指定します。

jwsc Antタスクの詳細および例については、『Oracle WebLogic Server WebLogic Webサービス・リファレンス』のjwscに関する項を参照してください。

Webサービスの呼出しに使用されるトランスポートの指定

jwscの<jws>子要素には、Webサービスの呼出しに使用するトランスポート(HTTP/SまたはJMS)を指定するための、次に示すオプションの子要素があります。

- WLHttpTransport: 生成されたWSDLのポート名に加え、HTTP/SトランスポートでWebサービスを呼び出すために使用するコンテキスト・パスおよびURLのサービスURIセクションを指定します。

- WLJMSTransport: JMSトランスポートでWebサービスを呼び出すために使用するコンテキスト・パスおよびURLのサービスURIセクションと、生成されたWSDLのポート名を指定します。また、JMSトランスポート用に構成済のJMSキュー名および接続ファクトリ名も指定します。

次のガイドラインで、jwsc Antタスクのトランスポート要素の使用方法について説明します。

- jwscに対して指定したトランスポートは、JWSファイル内のすべての対応するトランスポート・アノテーションを常にオーバーライドします。また、トランスポート要素の対応する属性を明示的に指定していない場合でも、トランスポート・アノテーションのすべての属性は無視されます。この場合、トランスポート要素属性のデフォルト値が使用されます。

- 特定のJWSファイルに対して両方のトランスポート要素を指定できます。ただし、指定できるのは、特定のトランスポート要素の1つのインスタンスのみです。たとえば、特定のJWSファイルに2つの異なる<WLHttpTransport>要素を指定することはできませんが、<WLHttpTransport>要素と<WLJmsTransport>要素をそれぞれ1つずつ指定することはできます。

- serviceURI属性の値は、<WLJMSTransport>と<WLHttpTransport>の両方を指定する際、同じにすることができます。

- 特定のJWSファイルに関連付けられるすべてのトランスポートでは、同じcontextPath属性値を指定する必要があります。

- 特定のJWSファイルに複数のトランスポート要素を指定する場合、各要素のportName属性の値は、すべての要素において一意である必要があります。つまり、複数のトランスポート子要素を<jws>に追加する場合、この属性を明示的に指定する必要があることを意味します。これは、要素のデフォルト値は常に同じになるため、jwsc Antタスクの実行時にエラーが発生するためです。

- jwsc Antタスクに対するトランスポート要素のいずれかまたはJWSファイルのトランスポート・アノテーションとしてトランスポートを指定しなかった場合、WebサービスのデフォルトURLは、WLHttpTransport要素のデフォルト値と一致します。

JAX-RPC Webサービスの場合、JWSファイルをプログラミングする際、クライアントがWebサービスを呼び出すのに使用するトランスポートを指定するために、特に@weblogic.jws.WLHttpTransportまたは@weblogic.jws.WLJMSTransportという形式のアノテーションを使用できます。JWSファイルでは、特定のトランスポート・アノテーションの1つのインスタンスのみを指定できます。たとえば、2つの異なる@WLHttpTransportアノテーションを指定することはできませんが、@WLHttpTransportアノテーションと@WLJmsTransportアノテーションをそれぞれ1つずつ指定することはできます。ただし、JWSファイルを記述している時点では、どのトランスポートがニーズに適しているかを判断できない可能性があります。そのため、トランスポートはビルド時に指定するのが一般的に最適な方法です。

WebLogic Webサービスのコンテキスト・パスの定義

WebLogic Webサービスのコンテキスト・パス(コンテキスト・ルートとも呼ばれます)は、様々な場所で指定できます。この項では、サービスのコンテキスト・パスが複数の場所で設定されている場合でも、構成に基づいてサービスの正しいコンテキスト・パスを判別する方法について説明します。

この説明では、Webサービスのコンテキスト・パスとは、WebサービスURLのhost:port部分の後にくる文字列を指します。たとえば、WebLogic WebサービスのデプロイされたWSDLが次のとおりであるとします。

http://hostname:7001/financial/GetQuote?WSDL

financialが、このWebサービスのコンテキスト・パスです。

次に、コンテキスト・パスを指定できるすべての場所の優先順位を、重要度の高い順番で示します。

1. <module>要素および<jws>要素のcontextPath属性(jwsc Antタスクの直接の子として使用される場合)

2. <jws>の<WLXXXTransport>子要素のcontextPath属性。

3. @WLXXXTransport JWSアノテーションのcontextPath属性(「Webサービスのコンテキスト・パスとサービスURIの指定(@WLHttpTransportアノテーション)」を参照)

4. コンテキスト・パスのデフォルト値(JWSファイルの名前。ただし、拡張子は付きません)

たとえば、JAX-RPC JWSファイルで@WLHttpTransportアノテーションを指定し、そのcontextPath属性をfinancialに設定したものと仮定します。この時、build.xmlファイルのjwsc Antタスクにおいてその他のcontextPath属性を指定していない場合、Webサービスのコンテキスト・パスはfinancialになります。

ここで、そのbuild.xmlファイルを更新し、<WLHttpTransport>子要素を、JWSファイルを指定する<jws>要素に追加し、そのcontextPath属性をfinanceに設定したものと仮定します。今度は、Webサービスのコンテキスト・パスはfinanceになります。ただし、次に<module>要素の下で<jws>要素とその子<WLHttpTransport>要素をグループ化し、そのcontextPath属性をmoneyに設定すると、Webサービスのコンテキスト・パスはmoneyになります。

JWSファイルまたはjwsc AntタスクにおいてcontextPath属性を1つも指定しない場合、Webサービスのコンテキスト・パスはデフォルト値(*.java拡張子の付かないJWSファイルの名前)になります。

複数の<jws>要素を1つの<module>要素の下でグループ化し、前述の他のオプションを使用してコンテキスト・パスを設定しない場合、<module>のcontextPath属性で、モジュール内のすべてのWebサービスで使用される共通のコンテキスト・パスを指定する必要があります。そうしないと、モジュール内のすべてのWebサービスのデフォルト・コンテキスト・パスが異なってしまいます(実装するJWSファイルの名前が異なることに起因します)が、1つのWARファイル内で異なるコンテキスト・パスを使用することはできません。

jwscの使用例

以下のbuild.xmlの抜粋では、JWSファイルに対してjwsc Antタスクを実行する基本的な例を示します。

<taskdef name="jwsc"
classname="weblogic.wsee.tools.anttasks.JwscTask" />
<target name="build-service">
<jwsc
srcdir="src"
destdir="output/helloWorldEar">
<jws
file="examples/webservices/hello_world/HelloWorldImpl.java"
type="JAXRPC"/>
</jwsc>
</target>

この例では、

- カレント・ディレクトリに対して相対的なoutput/helloWorldEarに、エンタープライズ・アプリケーションが展開形式で生成されます。

- JWSファイルはHelloWorldImpl.javaという名前で、カレント・ディレクトリに対して相対的なsrc/examples/webservices/hello_worldディレクトリにあります。つまり、JWSファイルはパッケージexamples.webservices.helloWorld内にあります。

- JAX-RPC Webサービスが生成されます。

以下の例は前の例と似ていますが、compiledWsdl属性を使用して、wsdlcが生成したアーティファクト(「WSDLから開始する」ユース・ケース)を含むJARファイルを指定している点が異なります。

<taskdef name="jwsc"
classname="weblogic.wsee.tools.anttasks.JwscTask" />
<target name="build-service">
<jwsc
srcdir="src"
destdir="output/wsdlcEar">
<jws
file="examples/webservices/wsdlc/TemperaturePortTypeImpl.java"
compiledWsdl="output/compiledWsdl/TemperatureService_wsdl.jar"
type="JAXRPC"/>
</jwsc>
</target>

この例では、TemperaturePortTypeImpl.javaファイルが、独自のビジネス・ロジックを含めて更新した、途中まで作成されていたJWSファイルです。compiledWsdl属性が指定されてJARファイルを指し示しているので、jwsc Antタスクでは、JARに含まれているアーティファクトを再生成することはありません。

このタスクを実際に実行するには、コマンド・ラインで次のように入力します。

prompt> ant build-service

wsdlc WebLogic WebサービスAntタスクの実行

wsdlc AntタスクはWSDLファイルを入力として取り、WebLogic Webサービスの実装を構成するアーティファクトを生成します。次のようなアーティファクトがあります。

- WSDLファイルで記述されたWebサービスを実装するJWSサービス・エンドポイント・インタフェース(SEI)。

- 生成されるJWS SEIの不完全な(途中まで作成済みの)実装が含まれるJWS実装ファイル。このファイルは開発者がカスタマイズする必要があります。

- Webサービスのパラメータと戻り値をXML表現とJava表現の間で変換するために、WebLogic Serverによって使用されるデータ・バインディング・アーティファクト。

- (オプション)生成されるJWS SEIのJavadoc。

wsdlc AntタスクはJWS SEIとデータ・バインディング・アーティファクトを一緒にJARファイルにパッケージ化します。このJARファイルを後でjwsc Antタスクに指定します。このJARファイルを更新する必要はありません。更新するファイルはJWS実装クラスのみです。

wsdlc Antタスクを実行するには、以下のtaskdefおよびgenerate-from-wsdlターゲットをbuild.xmlファイルに追加します。

<taskdef name="wsdlc"
classname="weblogic.wsee.tools.anttasks.WsdlcTask"/>
<target name="generate-from-wsdl">
<wsdlc
srcWsdl="WSDL_file"
destJwsDir="JWS_interface_directory"
destImplDir="JWS_implementation_directory"
packageName="Package_name"
type="WebService_type"/>
</target>

各項目の説明は次のとおりです。

- WSDL_file - 部分的な実装を生成する元となるWSDLファイルの名前(絶対パスまたは相対パスを含めます)。

- JWS_interface_directory - JWS SEIおよびデータ・バインディング・アーティファクトを含むJARファイルの生成先となるディレクトリ。
生成されるJARファイルの名前はWSDLFile_wsdl.jar (WSDLFileはWSDLファイルのルート名)。たとえば、file属性に対して指定したWSDLファイルの名前がMyService.wsdlの場合、生成されるJARファイルはMyService_wsdl.jarとなります。

- JWS_implementation_directory - 途中まで作成済みのJWS実装ファイルの生成先となる最上位ディレクトリ。ファイルはパッケージ名に対応するサブディレクトリ階層に生成されます。
生成されるJWSファイルの名前はPortTypeImpl.javaです。PortTypeは、Webサービスを生成するWSDLファイル内の<portType>要素のname属性です。たとえば、ポート・タイプ名がMyServicePortTypeの場合、JWS実装ファイルはMyServicePortTypeImpl.javaという名前になります。

- Package_name - 生成されるJWS SEIおよび実装ファイルの生成先となるパッケージ。この属性を指定しない場合、wsdlc Antタスクは、WSDLのtargetNamespaceに基づいてパッケージ名を生成します。

- WebService_type - Webサービスの種類。この値は、JAXWSまたはJAXRPCに設定できます。

必須のtaskdef要素では、wsdlc Antタスクの完全修飾クラス名を指定します。

wsdlc Antタスクでは、srcWsdlおよびdestJwsDir属性のみが必須です。ただし、通常は、プログラミングを容易にするために、途中まで作成済みのJWSファイルを生成します。WSDLファイルのtargetNamespaceが、読取り可能なパッケージ名への変換に適していない場合に備えて、パッケージ名を明示的に指定することをお薦めします。

以下のbuild.xmlの抜粋では、WSDLファイルに対してwsdlc Antタスクを実行する例を示します。

<taskdef name="wsdlc"
classname="weblogic.wsee.tools.anttasks.WsdlcTask"/>
<target name="generate-from-wsdl">
<wsdlc
srcWsdl="wsdl_files/TemperatureService.wsdl"
destJwsDir="output/compiledWsdl"
destImplDir="impl_output"
packageName="examples.webservices.wsdlc"
type="JAXRPC" />
</target>

この例では、

- 既存のWSDLファイルはTemperatureService.wsdlという名前で、build.xmlファイルを格納するディレクトリのwsdl_filesサブディレクトリにあります。

- JWS SEIとデータ・バインディング・アーティファクトを含むJARファイルはoutput/compiledWsdlディレクトリに生成され、JARファイルの名前はTemperatureService_wsdl.jarです。

- 生成されるJWSファイルのパッケージ名はexamples.webservices.wsdldです。

- 途中まで作成済みのJWSファイルは、カレント・ディレクトリに対して相対的なimpl_output/examples/webservices/wsdlcディレクトリに生成されます。

- WSDLファイル内のポート・タイプ名がTemperaturePortTypeの場合、JWS実装ファイルの名前はTemperaturePortTypeImpl.javaになります。

- JAX-RPC Webサービスが生成されます。

このタスクを実際に実行するには、コマンド・ラインで次のように入力します。

prompt> ant generate-from-wsdl

詳細は、『Oracle WebLogic Server WebLogic Webサービス・リファレンス』のwsdlcに関する項を参照してください。

wsdlcで生成される途中まで作成済みのJWS実装クラス・ファイルの更新

wsdlc Antタスクは、destImplDir属性で指定されたディレクトリに、途中まで作成済みのJWS実装ファイルを生成します。ファイルの名前はPortTypeImpl.javaです(PortTypeは元のWSDLにあるportTypeの名前)。このクラス・ファイルには、独自のビジネス・ロジックを除いて、Webサービスへコンパイルするために必要なすべてのものが含まれています。

JWSクラスは、WSDLファイルに対応するJWS Webサービス・エンドポイント・インタフェースを実装しています。このJWS SEIもwsdlcによって生成され、他のアーティファクト(WSDL内のXMLスキーマ・データ型のJava表現など)が含まれているJARファイル内に置かれています。JWSクラスのパブリック・メソッドはWSDLファイル内の操作に対応しています。

wsdlc Antタスクは、JWS実装クラスに@WebServiceおよび@WLHttpTransportアノテーションを自動的に含めます。属性の値はWSDL内の関連する値に対応しています。たとえば、@WebServiceのserviceName属性は、WSDLファイル内の<service>要素のname属性と同じです。@WLHttpTransportのcontextPathおよびserviceUri属性は共に、WSDL内の<address>要素のlocation属性で指定されたエンドポイント・アドレスを構成します。

JWSファイルを更新するときは、該当のWebサービス操作が希望どおりに動作するように、メソッドにJavaコードを追加します。通常、生成されるJWSファイルには、コードを追加すべき場所に次のようなコメントがあります。

//replace with your impl here

また、他のJWSアノテーションをファイルに追加することもできますが、以下のような制限があります。

- JWS実装ファイルに含めることができる標準(JSR-181)のjavax.jwsパッケージのアノテーションは、@WebService、@HandlerChain、@SOAPMessageHandler、および@SOAPMessageHandlersのみです。javax.jwsパッケージの他のJWSアノテーションを指定し、JWSファイルをWebサービスにコンパイルしようとすると、jwsc Antタスクはエラーを返します。

- @WebServiceアノテーションでは、serviceName、endpointInterface、およびtargetNamespace属性のみを指定できます。まれに、WSDLファイルに複数の<service>要素が指定されていることがあります。その場合は、serviceName属性を使用して、wsdlc Antタスクで使用していたものとは別の<service> WSDL要素を指定します。wsdlc Antタスクで生成されたJWS SEIを指定するには、endpointInterface属性を使用します。WSDLサービスのネームスペースを指定するには、targetNamespace属性を使用します。JWS SEIネームスペースと異なるネームスペースを指定できます。

- 必要に応じて、WebLogic固有のJWSアノテーションを指定することができます。

JWSファイルを更新したら、wsdlcの出力ディレクトリにそのまま置いておかないで、正式なソースの場所に移動することをお薦めします。

以下の例は、「サンプルWSDLファイル」のWSDLからwsdlcが生成したJWS実装ファイルです。太字のテキストは、Webサービスの1つの操作(getTemp)を実装するJavaコードを追加する場所を示しています。

package examples.webservices.wsdlc;
import javax.jws.WebService;
import weblogic.jws.*;
/**
* TemperaturePortTypeImpl class implements web service endpoint interface
* TemperaturePortType */
@WebService(
serviceName="TemperatureService",
endpointInterface="examples.webservices.wsdlc.TemperaturePortType")
@WLHttpTransport(
contextPath="temp",
serviceUri="TemperatureService",
portName="TemperaturePort")
public class TemperaturePortTypeImpl implements TemperaturePortType {
public TemperaturePortTypeImpl() {
}
public float getTemp(java.lang.String zipcode)
{
//replace with your impl here
return 0;
}
}

WebLogic Webサービスのデプロイとアンデプロイ

Webサービスはエンタープライズ・アプリケーションとしてパッケージ化されるので、Webサービスのデプロイとは、該当するEARファイルまたは展開されたディレクトリをデプロイすることになります。

WebLogic Server管理コンソールの使用からweblogic.Deployer Javaユーティリティの使用まで、WebLogicアプリケーションのデプロイには多様な方法があります。開発環境とは異なり、本番環境にアプリケーションをデプロイする際には、他にも様々な問題を考慮する必要があります。デプロイメントの詳細は、『Oracle WebLogic Serverへのアプリケーションのデプロイ』を参照してください。

このガイドでは、開発の性質上、Webサービスの2つのデプロイ方法についてのみ説明します。

- wldeploy Antタスクを使用したWebサービスのデプロイ

- 管理コンソールを使用したWebサービスのデプロイ

wldeploy Antタスクを使用したWebサービスのデプロイ

反復的な開発プロセスの一環としてWebサービスをデプロイする最も簡単な方法は、wldeploy WebLogic Antタスクを実行するターゲットを、jwsc Antタスクが含まれる同じbuild.xmlファイルに追加することです。Javaコードを追加してサービスを再生成するたびに、サービスの再デプロイとテストを繰返し行えるように、Webサービスをデプロイするターゲットとアンデプロイするターゲットの両方を追加することができます。

wldeploy Antタスクを使用するには、以下のターゲットをbuild.xmlファイルに追加します。

<target name="deploy">
<wldeploy action="deploy"
name="DeploymentName"
source="Source" user="AdminUser"
password="AdminPassword"
adminurl="AdminServerURL"
targets="ServerName"/>
</target>

各項目の説明は次のとおりです。

- DeploymentName - エンタープライズ・アプリケーションのデプロイメント名、または、WebLogic Server管理コンソールでデプロイメントのリストに表示される名前。

- Source - デプロイするエンタープライズ・アプリケーションのEARファイルまたは展開されたディレクトリの名前。デフォルトでは、jwsc Antタスクが展開されたエンタープライズ・アプリケーション・ディレクトリを生成します。

- AdminUser - 管理ユーザー名。

- AdminPassword - 管理パスワード。

- AdminServerURL - 管理サーバーのUrl。通常はt3://localhost:7001です。

- ServerName - WebサービスをデプロイするWebLogic Serverインスタンスの名前。

たとえば、以下のwldeployタスクでは、エンタープライズ・アプリケーションの展開されたディレクトリ(カレント・ディレクトリに対して相対的なoutput/ComplexServiceEarにある)がmyServer WebLogic Serverインスタンスにデプロイされることを指定します。デプロイメント名はComplexServiceEarです。

<target name="deploy">
<wldeploy action="deploy"
name="ComplexServiceEar"
source="output/ComplexServiceEar" user="weblogic"
password="weblogic" verbose="true"
adminurl="t3://localhost:7001"
targets="myserver"/>
</target>

Webサービスを実際にデプロイするには、コマンド・ラインでdeployターゲットを実行します。

prompt> ant deploy

ソース・コードに変更を加えてからWebサービスを再デプロイできるように、Webサービスを簡単にアンデプロイするターゲットを追加することもできます。

<target name="undeploy">
<wldeploy action="undeploy"
name="ComplexServiceEar"
user="weblogic"
password="weblogic" verbose="true"
adminurl="t3://localhost:7001"
targets="myserver"/>
</target>

Webサービスをアンデプロイするときは、source属性を指定する必要はなく、名前によってアンデプロイします。

管理コンソールを使用したWebサービスのデプロイ

WebLogic Server管理コンソールを使用してWebサービスをデプロイするには、最初に、ブラウザで次のURLを使用してWebサービスを呼び出します。

http://host:port/console

各項目の説明は次のとおりです。

- host WebLogic Serverが動作しているコンピュータの名前。

- port - WebLogic Serverがリスニングしているポート番号(デフォルト値は7001です)。

次にデプロイメント・アシスタントを使用して、エンタープライズ・アプリケーションをデプロイします。WebLogic Server管理コンソールの詳細は、Oracle WebLogic Server管理コンソール・オンライン・ヘルプを参照してください。

WebサービスのWSDLの参照

WebサービスのWSDLをブラウザで表示して、Webサービスが適切にデプロイされていることを確認できます。

次のURLは、WebサービスのWSDLをブラウザで表示する方法を示しています。

http://host:port/contextPath/serviceUri?WSDL

各項目の説明は次のとおりです。

- host - WebLogic Serverが動作しているコンピュータの名前(localhostなど)。

- port - WebLogic Serverがリスニングしているポート番号(デフォルト値は7001です)。

- contextPath - Webサービスのコンテキスト・ルート。コンテキスト・ルートを設定する場所としては、@WLHttpTransportアノテーションのcontextPath属性、jwscの<WLHttpTransport>、<module>、または<jws>要素があり、オーバーライドの順位が決まっています。第3章「WebLogic Webサービスのコンテキスト・パスの定義」を参照してください。

- serviceUri - Webサービスを実装するJWSファイルの@WLHttpTransport JWSアノテーションのserviceUri属性の値、またはjwsc Antタスクの<WLHttpTransport>子要素の値です; 前者より後者が優先されます。JWSファイルまたはjwsc AntタスクにおいてserviceUri属性を何も指定しない場合、WebサービスのserviceUriはデフォルト値(*.java拡張子の付かないJWSファイルの名前)になります。

たとえば、Webサービスを実装するJWSファイルで以下の@WLHttpTransportアノテーションを指定したとします。

...
@WLHttpTransport(contextPath="complex",
serviceUri="ComplexService",
portName="ComplexServicePort")
/**
* This JWS file forms the basis of a WebLogic Web Service.
*
*/
public class ComplexServiceImpl {
...

ここでは、jwsc Antタスクの<WLHttpTransport>要素と同等の属性を設定し、contextPathまたはserviceURIの値をオーバーライドしないこととします。そして、Webサービスがarielというホストのデフォルトのポート番号(7001)で実行されているとすると、そのWebサービスのWSDLを表示するURLは次のようになります。

http://ariel:7001/complex/ComplexService?WSDL

動的なWSDLで指定されたサーバー・アドレスの構成

デプロイ済のWebサービスのWSDL(動的なWSDLともいいます)には、特定のWebサービス・ポートにアドレス(URI)を割り当てる<address>要素が含まれています。たとえば、次に示すWSDLの抜粋には、ComplexServiceというデプロイ済みのWebLogic Webサービスの一部が記述されています。

<definitions name="ComplexServiceDefinitions"
targetNamespace="http://example.org">
...
<service name="ComplexService">
<port binding="s0:ComplexServiceSoapBinding" name="ComplexServicePort">
<s1:address location="http://myhost:7101/complex/ComplexService"/>
</port>
</service>
</definitions>

この例では、ComplexService WebサービスにComplexServicePortというポートが含まれており、そのアドレスはhttp://myhost:7101/complex/ComplexServiceとなっています。

WebLogic Serverは、このアドレスのcomplex/ComplexServiceの部分を、@WLXXXTransportアノテーションまたはjwsc要素のcontextPathおよびserviceURI属性を調べることによって決定します(「WebサービスのWSDLの参照」に説明があります)。しかし、WebLogic Serverがアドレスのプロトコルおよびホスト部分(この例ではhttp://myhost:7101)を決定するために使用する方法は、次で説明するとおり、より複雑です。この項では、わかりやすいように、アドレスのプロトコルとホストの部分をまとめてサーバー・アドレスと呼ぶことにします。

WebLogic Serverがデプロイ済みのWebサービスの動的なWSDL内にパブリッシュするサーバー・アドレスは、そのWebサービスをHTTP/SやJMSで呼び出せるかどうか、プロキシ・サーバーを構成しているかどうか、Webサービスがクラスタにデプロイされているかどうか、Webサービスが実際にはコールバック・サービスであるかどうかによって異なります。

以下では、これらの構成の違いに応じたサーバー・アドレスの決定方法について説明します。また、ニーズに合わせて構成を変更するための手順説明へのリンクも示します。

- Webサービスがコールバック・サービスでなく、HTTP/Sを使用して呼び出せる場合

- Webサービスがコールバック・サービスでなく、JMSトランスポートを使用して呼び出せる場合

- Webサービスがコールバック・サービスである場合

- Webサービスがプロキシ・サーバーを使用して呼び出せる場合

なお、ここでは、クラスタとスタンドアロン・サーバーを、WebLogic Server管理コンソールを使用して構成することを前提としています。

Webサービスがコールバック・サービスでなく、HTTP/Sを使用して呼び出せる場合

1. Webサービスがクラスタにデプロイされており、クラスタのFrontend Host、Frontend HTTP Port、およびFrontend HTTPS Portが設定されている場合は、動的なWSDLのサーバー・アドレスにこれらの値が使用されます。
Oracle WebLogic Server管理コンソール・オンライン・ヘルプのクラスタのHTTP設定の構成に関する項を参照してください。

2. 上記のクラスタ値は設定されていないが、Webサービスがデプロイされている個々のサーバーでFrontend Host、Frontend HTTP Port、およびFrontend HTTPS Portの値が設定されている場合は、サーバー・アドレスにこれらの値が使用されます。
Oracle WebLogic Server管理コンソール・オンライン・ヘルプのHTTPプロトコルの構成に関する項を参照してください。

3. これらの値がクラスタにも個々のサーバーにも設定されていない場合は、動的なWSDL内のWSDLリクエストのサーバー・アドレスが使用されます。

Web Serviceがコールバック・サービスでなく、JMSトランスポートを使用して呼び出せる場合

1. Webサービスがクラスタにデプロイされており、Cluster Addressが設定されている場合は、動的なWSDLのサーバー・アドレスにこの値が使用されます。
Oracle WebLogic Server管理コンソール・オンライン・ヘルプのクラスタの構成に関する項を参照してください。

2. クラスタ値が設定されていないか、Webサービスがスタンドアロン・サーバーにデプロイされており、WebサービスがデプロイされているサーバーのListen Addressが設定されている場合は、サーバー・アドレスにこの値が使用されます。
Oracle WebLogic Server管理コンソール・オンライン・ヘルプのリスニング・アドレスの構成に関する項を参照してください。

Webサービスがコールバック・サービスである場合

1. コールバック・サービスがクラスタにデプロイされており、クラスタのFrontend Host、Frontend HTTP Port、およびFrontend HTTPS Portが設定されている場合は、動的なWSDLのサーバー・アドレスにこれらの値が使用されます。
Oracle WebLogic Server管理コンソール・オンライン・ヘルプのクラスタのHTTP設定の構成に関する項を参照してください。

2. コールバック・サービスがクラスタまたはスタンドアロン・サーバーにデプロイされており、上記のクラスタ値は設定されていないが、コールバック・サービスがデプロイされている個々のサーバーでFrontend Host、Frontend HTTP Port、およびFrontend HTTPS Portの値が設定されている場合は、サーバー・アドレスにこれらの値が使用されます。
Oracle WebLogic Server管理コンソール・オンライン・ヘルプのHTTPプロトコルの構成に関する項を参照してください。

3. コールバック・サービスがクラスタにデプロイされており、上記のどの値も設定されていないがCluster Addressが設定されている場合は、サーバー・アドレスにこの値が使用されます。
Oracle WebLogic Server管理コンソール・オンライン・ヘルプのクラスタの構成に関する項を参照してください。

4. 上記のどの値も設定されていないが、コールバック・サービスがデプロイされているサーバーのListen Addressが設定されている場合は、サーバー・アドレスにこの値が使用されます。
Oracle WebLogic Server管理コンソール・オンライン・ヘルプのリスニング・アドレスの構成に関する項を参照してください。

Webサービスがプロキシ・サーバーを使用して呼び出せる場合

必須ではありませんが、Webサービスがデプロイされているクラスタまたは個々のサーバーのいずれかのFrontend Host、FrontEnd HTTP Port、およびFrontend HTTPS Portがプロキシ・サーバーを指すように明示的に設定することをお薦めします。

Oracle WebLogic Server管理コンソール・オンライン・ヘルプのクラスタのHTTP設定の構成またはHTTPプロトコルの構成に関する項を参照してください。

Webサービスのテスト

WebLogic Webサービスのデプロイメントが完了したら、WebLogic Server管理コンソールに含まれているWebサービス・テスト・クライアントを使用して、コードを記述することなくサービスをテストできます。複合型を持つWebサービスや、WebLogic Serverの高度な機能(会話など)を使用するWebサービスも含めて、Webサービスを素早く簡単にテストできます。テスト・クライアントはリクエストの完全なログを自動的に保持しているので、ユーザーは以前の呼出しに戻って結果を表示することができます。

デプロイしたWebサービスをWebLogic Server管理コンソールを使用してテストするには、次の手順に従います。

1. 次のURLを使用して、ブラウザでWebLogic Server管理コンソールを呼び出します。

http://host:port/console

各項目の説明は次のとおりです。

- host WebLogic Serverが動作しているコンピュータの名前。

- port - WebLogic Serverがリスニングしているポート番号(デフォルト値は7001です)。

2. Oracle WebLogic Server管理コンソール・オンライン・ヘルプのWebサービスのテストに関する項で説明されている手順に従います。

WebサービスのWebLogic分割開発ディレクトリ環境への統合

この項では、Webサービスの開発をWebLogic分割開発ディレクトリ環境に統合する方法について説明します。このWebLogic機能について理解していること、標準のJava Platform, Enterprise Edition (Java EE)バージョン5アプリケーションおよびモジュール(EJBやWebアプリケーションなど)の開発用にこのタイプの環境を設定済みであること、Webサービスの開発が含まれるようにbuild.xmlファイルを更新しようとしていることを前提としています。

WebLogic分割開発ディレクトリ環境の詳細は、『Oracle WebLogic Serverアプリケーションの開発』のアプリケーションの分割開発ディレクトリの作成に関する項およびWebLogic Serverと一緒にオプションでインストールされるsplitdir/helloWorldEarサンプルを参照してください。サンプルは、ORACLE_HOME/\wlserver\samples\server\examples\src\examples\splitdirディレクトリにあります。ORACLE_HOMEはWebLogic Serverがインストールされているディレクトリを示します。WebLogic Serverのサンプル・コードの詳細は、『Oracle WebLogic Serverの理解』のサンプル・アプリケーションとサンプル・コードに関する項を参照してください。

1. メイン・プロジェクト・ディレクトリ内に、Webサービスを実装するJWSファイルを格納するためのディレクトリを作成します。
たとえば、メイン・プロジェクト・ディレクトリが/src/helloWorldEarである場合、/src/helloWorldEar/helloWebServiceというディレクトリを作成します。

prompt> mkdir /src/helloWorldEar/helloWebService

2. helloWebServiceディレクトリの下に、JWSファイルのパッケージ名に対応するディレクトリ階層を作成します。
たとえば、JWSファイルがexamples.splitdir.helloパッケージにパッケージ化されている場合は、examples/splitdir/helloというディレクトリ階層を作成します。

prompt> cd /src/helloWorldEar/helloWebService
prompt> mkdir examples/splitdir/hello

3. メイン・プロジェクト・ディレクトリに作成したWebサービスのサブディレクトリ(この例では/src/helloWorldEar/helloWebService/examples/splitdir/hello)にJWSファイルを置きます。

4. エンタープライズ・アプリケーションをビルドするbuild.xmlファイル内に、「jwsc WebLogic WebサービスAntタスクの実行」の説明に従ってjwsc WebLogic WebサービスAntタスクの呼出しを追加して、Webサービスをビルドする新しいターゲットを作成します。
jwscのsrcdir属性は、JWSファイルを格納する最上位ディレクトリ(この例ではhelloWebService)を指すようにします。jwscのdestdir属性は、wlcompileに指定するのと同じ宛先ディレクトリを指すようにします。次の例を参照してください。

<target name="build.helloWebService">
<jwsc
srcdir="helloWebService"
destdir="destination_dir"
keepGenerated="yes" >
<jws file="examples/splitdir/hello/HelloWorldImpl.java"
type="JAXRPC" />
</jwsc>
</target>

この例のdestination_dirは、他の分割開発ディレクトリ環境のAntタスク(wlappcやwlcompileなど)も使用する宛先ディレクトリを表します。

5. Webサービス関連のターゲットを呼び出すように、build.xmlファイルのメインのbuildターゲットを更新します。

<!-- Builds the entire helloWorldEar application -->
<target name="build"
description="Compiles helloWorldEar application and runs appc"
depends="build-helloWebService,compile,appc" />

注意:
エンタープライズ・アプリケーションを実際にビルドするときは、wlappc Antタスクを実行する前に、jwsc Antタスクを実行するようにしてください。wlappcを正常に実行するには、jwscによって生成されるアーティファクトの一部が必要になるためです。この例の場合は、appcターゲットよりも前にbuild-helloWebServiceターゲットを指定する必要があります。

6. wlcompileおよびwlappc Antタスクを使用してエンタープライズ・アプリケーション全体をコンパイルおよび検証する場合は、両方のAntタスクでWebサービスのソース・ディレクトリを除外するようにしてください。これは、jwsc AntタスクでWebサービスのコンパイルとパッケージ化をすでに扱っているからです。例:

<target name="compile">
<wlcompile srcdir="${src.dir}" destdir="${dest.dir}"
excludes="appStartup,helloWebService">
...
</wlcomplile>
...
</target>
<target name="appc">
<wlappc source="${dest.dir}" deprecation="yes" debug="false"
excludes="helloWebService"/>
</target>

7. META-INFプロジェクト・ソース・ディレクトリにあるapplication.xmlファイルを更新して、<web>モジュールを追加し、jwsc Antタスクによって生成されるWARファイルの名前を指定します。
たとえば、helloWorld Webサービスのapplication.xmlファイルに以下のように追加します。

<application>
...
<module>
<web>
<web-uri>examples/splitdir/hello/HelloWorldImpl.war</web-uri>
<context-root>/hello</context-root>
</web>
</module>
...
</application>

注意:
jwsc Antタスクでは通常、Webサービスを実装するJWSファイルからWebアプリケーションWARファイルが生成されます。ただし、JWSファイルにjavax.ejb.SessionBeanが明示的に実装されている場合は例外です。その場合は、application.xmlファイルに<ejb>モジュール要素を追加する必要があります。

これで、分割開発ディレクトリ環境は、Webサービスの開発を含むように更新されました。エンタープライズ・アプリケーション全体を再ビルドしてデプロイするときに、WebサービスもEARの一部としてデプロイされます。Webサービスは、「WebサービスのWSDLの参照」で説明されている標準的な方法で呼び出します。

4 JWSファイルのプログラミング

この章では、Java API for XML-based RPC (JAX-RPC)を使用したWebLogic Webサービスを実装するJWSファイルのプログラミング方法について説明します。

この章の内容は次のとおりです。

- JWSファイルとJWSアノテーションの概要

- JWSファイルのJava要件

- JWSファイルのプログラミング: 一般的な手順

- Webサービスの実行時情報へのアクセス

- ステートレス・セッションEJBを実装すべき場合

- ユーザー定義のJavaデータ型のプログラミング

- 例外のスロー

- JWSファイルからの別のWebサービスの呼出し

- JWSアノテーションおよびAPIによるその他の機能のプログラミング

- JWSプログラミングのベスト・プラクティス

JWSファイルとJWSアノテーションの概要

WebLogic Webサービスをゼロからプログラミングする方法は2つあります。

1. JSR-181、JAX-WS仕様、およびWebLogic Webサービス・プログラミング・モデルで規定されているように、標準のEJBまたはJavaクラスにWebサービスJavaアノテーションを付けます。

2. デプロイメント記述子、WSDLファイル、データ・マッピング記述子、データ・バインディング・アーティファクト(ユーザー定義のデータ型用)など、JSR-109で指定されている様々なXML記述子ファイルやアーティファクトと、標準のEJBまたはJavaクラスを結合します。

Oracleでは、上記のオプション1を実行することを強くお薦めします。ユーザー自身がXMLメタデータ記述子を作成しなくても、必要な記述子やアーティファクトはJWSにユーザーが含めたアノテーションに基づいてWebLogic Antタスクおよびランタイムによって生成されます。このプロセスの方がはるかに簡単なだけでなく、Webサービスの情報が多数のJavaファイルやXMLファイル内に分散されず、JWSファイルで集中管理されます。

アノテーション付きのJava Webサービス(JWS)ファイルは、Webサービスの中核部分です。このファイルにはWebサービスの動作を決定するJavaコードが含まれています。JWSファイルは、Javaメタデータ・アノテーションを使用してWebサービスの形式や特性を指定した、通常のJavaクラス・ファイルです。JWSファイルでは、Web Services Metadata for the Java Platform仕様(JSR-181)(http://www.jcp.org/en/jsr/detail?id=181を参照)で定義される標準的なJWSアノテーションに加え、作成中のWebサービスの種類(JAX-WSまたはJAX-RPC)に基づいたその他のアノテーション・セットの使用が可能です。JAX-WS WebサービスおよびJAX-RPC Webサービスに対してサポートされているJWSアノテーションの完全なリストについては、『Oracle WebLogic Server WebLogic Webサービス・リファレンス』のWebサービスのアノテーション・サポートに関する項を参照してください。

JWSファイルをプログラミングする際は、基本的なWebサービス機能をプログラミングするためにアノテーションを含めます。アノテーションは、JWSファイル内の様々なレベル、様々なターゲットで使用されます。一部のアノテーションは、JWSファイル全体に適用されることを示すためにクラス・レベルで使用されます。それ以外のアノテーションには、メソッド・レベルで使用するものや、パラメータ・レベルで使用するものがあります。

JWSファイルのJava要件

JWSファイルをプログラミングする場合は、Web Services Metadata for the Java Platform仕様(JSR-181)(http://www.jcp.org/en/jsr/detail?id=181)で指定された一連の要件に従う必要があります。特に、Webサービスを実装するJavaクラスは、次の要件に従う必要があります。

- パブリック・クラスでなければなりません。finalクラスやabstractクラスとして宣言することはできません。

- デフォルトのパブリック・コンストラクタを持つ必要があります。

- finalize()メソッドは定義できません。

- 少なくとも、クラス・レベルで@WebService JWSアノテーションを指定して、そのJWSファイルがWebサービスを実装することを指定する必要があります。

- @WebService.endpointInterfaceアノテーションを使用して、サービス・エンドポイント・インタフェースを参照できます。この場合は、サービス・エンドポイント・インタフェースが存在することを前提としています。JWSファイルでは@WebService.endpointInterface、@WebService.serviceName、および@WebService.targetNamespace以外のJWSアノテーションを指定することはできません。

- JWSファイルにサービス・エンドポイント・インタフェースが実装されていない場合は、java.lang.Objectから継承されたもの以外のすべてのパブリック・メソッドが、Webサービス操作として公開されます。この動作は、@WebMethodアノテーションを使用して、公開するパブリック・メソッドを明示的に指定することによって、オーバーライドできます。@WebMethodアノテーションが存在する場合は、それが適用されるメソッドのみが公開されます。

JWSファイルのプログラミング: 一般的な手順

次の手順では、Webサービスを実装するJWSファイルをプログラミングするための一般的な手順を説明します。

注意:
JWSファイルを作成してあり、そこにJWSアノテーションを追加する予定であることを前提としています。

各JWSアノテーションの詳細は、『Oracle WebLogic Server WebLogic Webサービス・リファレンス』のJWSアノテーション・リファレンスに関する項を参照してください。他のJWSアノテーションを使用して、より高度な機能(Webサービスの信頼性のあるメッセージング、会話、SOAPメッセージ・ハンドラなど)をプログラミングする方法については、第II部「JAX-RPC Webサービスの高度な機能の開発」を参照してください。

表4-1 JWSファイルのプログラミング手順

#

手順

説明

1

JWSファイルで使用する標準のJWSアノテーションをインポートします。

標準のJWSアノテーションはjavax.jwsまたはjavax.jws.soapパッケージにあります。例:

import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.jws.soap.SOAPBinding;

2

JWSファイルで使用するWebLogic固有のアノテーションをインポートします。

WebLogic固有のアノテーションはweblogic.jwsパッケージにあります。例:

import weblogic.jws.WLHttpTransport;

3

必須の標準@WebService JWSアノテーションをクラス・レベルで追加して、JavaクラスがWebサービスを公開することを指定します。

「JWSファイルがWebサービスを実装することの指定(@WebServiceアノテーション)」を参照してください。

4

標準の@SOAPBinding JWSアノテーションをクラス・レベルで追加して、WebサービスとSOAPメッセージ・プロトコルの間のマッピングを指定します。(オプション)

特に、このアノテーションを使用して、Webサービスがドキュメント・リテラルか、RPCエンコードかなどを指定します。「WebサービスとSOAPメッセージ・プロトコルのマッピングの指定(@SOAPBindingアノテーション)」を参照してください。

このJWSアノテーションは必須ではありませんが、JWSファイルで明示的に指定し、クライアント・アプリケーションがWebサービスの呼出しに使用するSOAPバインディングのタイプを明確にすることをお薦めします。

5

WebLogic固有の@WLHttpTransport JWSアノテーションをクラス・レベルで追加して、Webサービスを呼び出すURLで使用されるコンテキスト・パスとサービスURIを指定します。(オプション)

「Webサービスのコンテキスト・パスとサービスURIの指定(@WLHttpTransportアノテーション)」を参照してください。

このJWSアノテーションは必須ではありませんが、JWSファイルで明示的に指定し、クライアント・アプリケーションがWebサービスの呼出しに使用するURLを明確にすることをお薦めします。

6

パブリック操作として公開するJWSファイルの各メソッドで標準の@WebMethodアノテーションを追加する(オプション)

必要に応じて、標準の@Onewayアノテーションを使用し、その操作が入力パラメータだけを取り、値を返さないことを指定します。「JWSメソッドをパブリック操作として公開することの指定(@WebMethodおよび@OneWayアノテーション)」を参照してください。

7

@WebParamアノテーションを追加し、公開される操作の入力パラメータの名前をカスタマイズする(オプション)

「操作のパラメータとWSDL要素のマッピングのカスタマイズ(@WebParamアノテーション)」を参照してください。

8

@WebResultアノテーションを追加し、公開される操作の戻り値の名前と動作をカスタマイズする(オプション)

「操作の戻り値とWSDL要素のマッピングのカスタマイズ(@WebResultアノテーション)」を参照してください。

9

独自のビジネス・コードを追加します。

Webサービスが希望どおりに動作するように、独自のビジネス・コードをメソッドに追加します。

JWSファイルの例

次のサンプルJWSファイルでは、簡単なWebサービスの実装方法を示します。

package examples.webservices.simple;
// Import the standard JWS annotation interfaces
import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.jws.soap.SOAPBinding;
// Import the WebLogic-specific JWS annotation interfaces
import weblogic.jws.WLHttpTransport;
// Standard JWS annotation that specifies that the porType name of the Web
// Service is "SimplePortType", the service name is "SimpleService", and the
// targetNamespace used in the generated WSDL is "http://example.org"
@WebService(name="SimplePortType", serviceName="SimpleService",
targetNamespace="http://example.org")
// Standard JWS annotation that specifies the mapping of the service onto the
// SOAP message protocol.  In particular, it specifies that the SOAP messages
// are document-literal-wrapped.
@SOAPBinding(style=SOAPBinding.Style.DOCUMENT,
use=SOAPBinding.Use.LITERAL,
parameterStyle=SOAPBinding.ParameterStyle.WRAPPED)
// WebLogic-specific JWS annotation that specifies the context path and
// service URI used to build the URI of the Web Service is
// "simple/SimpleService"
@WLHttpTransport(contextPath="simple", serviceUri="SimpleService",
portName="SimpleServicePort")
/**
* This JWS file forms the basis of simple Java-class implemented WebLogic
* Web Service with a single operation: sayHello
*
*/
public class SimpleImpl {
// Standard JWS annotation that specifies that the method should be exposed
// as a public operation.  Because the annotation does not include the
// member-value "operationName", the public name of the operation is the
// same as the method name: sayHello.
@WebMethod()
public String sayHello(String message) {
System.out.println("sayHello:" + message);
return "Here is the message: '" + message + "'";
}
}

JWSファイルがWebサービスを実装することの指定(@WebServiceアノテーション)

次のコードの抜粋のように、標準の@WebServiceアノテーションを使用して、JWSファイルがWebサービスを実装することをクラス・レベルで指定します。

@WebService(name="SimplePortType", serviceName="SimpleService",
targetNamespace="http://example.org")

この例では、Webサービスの名前はSimplePortTypeであり、jwsc Antタスクによって生成されるWSDLファイルのwsdl:portType要素に後でマップされます。サービス名はSimpleServiceであり、生成されるWSDLファイルのwsdl:service要素にマップされます。生成されるWSDLで使用されるターゲット・ネームスペースはhttp://example.orgです。

@WebServiceアノテーションの以下の追加の属性を指定することもできます。

- endpointInterface - 既存のサービス・エンドポイント・インタフェース・ファイルの完全修飾名。このアノテーションによって、実装からインタフェース定義を切り離すことができます。この属性を指定した場合、jwsc Antタスクはそのインタフェースを生成しません。そのインタフェースは作成されていて、CLASSPATHに入っていると想定します。

- portname - wsdl:port内で使用される名前。

@WebServiceアノテーションの属性はいずれも必須ではありません。各属性のデフォルト値については、Web Services Metadata for the Java Platform (JSR 181)仕様(http://www.jcp.org/en/jsr/detail?id=181)を参照してください。

WebサービスとSOAPメッセージ・プロトコルのマッピングの指定(@SOAPBindingアノテーション)

ここでは、WebサービスをSOAPメッセージ・プロトコルで使用できるようにします。そのためには、JWSファイル内にクラス・レベルで標準の@SOAPBindingアノテーションを含めて、WebサービスのSOAPバインディング(RPCエンコードまたはdocument-literal-wrappedなど)を指定します(次のコードの抜粋を参照)。

@SOAPBinding(style=SOAPBinding.Style.DOCUMENT,
use=SOAPBinding.Use.LITERAL,
parameterStyle=SOAPBinding.ParameterStyle.WRAPPED)

この例で、Webサービスはdocument-wrapped-styleエンコーディングとリテラル・メッセージ書式を使用しており、@SOAPBindingアノテーションを使用しない場合でも、これらはデフォルトの書式となります。

WebLogic固有の@weblogic.jws.soap.SOAPBindingアノテーションを使用して、メソッド・レベルのSOAPバインディングを指定することもできます。属性は、標準の@javax.jws.soap.SOAPBindingアノテーションと同じです。

(style=SOAPBinding.Style.DOCUMENT属性と一緒に) parameterStyle属性を使用して、Webサービス操作のパラメータが、SOAPメッセージ本文全体を表すかどうか、操作と同じ名前の最上位要素内にラップされる要素かどうかを指定します。

表4-2 @SOAPBindingアノテーションの属性

属性

指定できる値

デフォルト値

style

SOAPBinding.Style.RPC
SOAPBinding.Style.DOCUMENT

SOAPBinding.Style.DOCUMENT

use

SOAPBinding.Use.LITERAL
SOAPBinding.Use.ENCODED

SOAPBinding.Use.LITERAL

parameterStyle

SOAPBinding.ParameterStyle.BARE
SOAPBinding.ParameterStyle.WRAPPED

SOAPBinding.ParameterStyle.WRAPPED

Webサービスのコンテキスト・パスとサービスURIの指定(@WLHttpTransportアノテーション)

WebLogic固有の@WLHttpTransportアノテーションを使用して、HTTPトランスポートでWebサービスを呼び出すために使用するURLのコンテキスト・パスとサービスURIの部分、および生成されるWSDL内のポート名を指定します(次のコードの抜粋を参照)。

@WLHttpTransport(contextPath="simple", serviceUri="SimpleService",
portName="SimpleServicePort")

この例では、jwsc Antタスクによって生成されるWSDLファイル内のポート名(具体的には<port>要素のname属性)はSimpleServicePortです。HTTPを介してWebサービスを呼び出すために使用するURLには、次の例のように、simpleというコンテキスト・パスとSimpleServiceというサービスURIが含まれます。

http://host:port/simple/SimpleService

このアノテーションやその他のWebLogic固有のアノテーションに関するリファレンス・ドキュメントについては、『WebLogic Webサービス・リファレンス』の「JWSアノテーション・リファレンス」を参照してください。

JWSメソッドをパブリック操作として公開することの指定(@WebMethodおよび@OneWayアノテーション)

次のコードの抜粋で示すように、標準の@WebMethodアノテーションを使用して、JWSファイルのメソッドをWebサービスのパブリック操作として公開することを指定します。

public class SimpleImpl {
@WebMethod(operationName="sayHelloOperation")
public String sayHello(String message) {
System.out.println("sayHello:" + message);
return "Here is the message: '" + message + "'";
}
...

この例では、SimpleImpl JWSファイルのsayHello()メソッドが、Webサービスのパブリック操作として公開されます。ただし、operationName属性では、WSDLファイル内の操作のパブリック名はsayHelloOperationになることを指定しています。operationName属性を指定しない場合は、メソッドの名前が操作のパブリック名になります。

action属性を使用して操作のアクションを指定することもできます。SOAPをバインディングとして使用する場合、action属性の値によって、SOAPメッセージ内のSOAPActionヘッダーの値が決まります。

標準の@Onewayアノテーションを使用して、操作が呼出し側アプリケーションに値を返さないことを指定できます。次の例を参照してください。

public class OneWayImpl {
@WebMethod()
@Oneway()
public void ping() {
System.out.println("ping operation");
}
...

操作が一方向であることを指定する場合、実装するメソッドはvoidを返す必要があります。パラメータとしてホルダー・クラスを使用したり、チェック済み例外をスローしたりすることはできません。

@WebMethodアノテーションの属性はいずれも必須ではありません。@WebMethodおよび@Onewayアノテーションに関する追加情報や、各属性のデフォルト値については、Web Services Metadata for the Java Platform (JSR 181)仕様(http://www.jcp.org/en/jsr/detail?id=181)を参照してください。

JWSファイル内のどのパブリック・メソッドにも@WebMethodアノテーションを付けていない場合、デフォルトではすべてのパブリック・メソッドがWebサービス操作として公開されます。

操作のパラメータとWSDL要素のマッピングのカスタマイズ(@WebParamアノテーション)

次のコードの抜粋で示すように、標準の@WebParamアノテーションを使用して、Webサービス操作の入力パラメータと生成されるWSDLファイルの要素間のマッピングのカスタマイズや、パラメータ動作の指定を行います。

public class SimpleImpl {
@WebMethod()
@WebResult(name="IntegerOutput",
targetNamespace="http://example.org/docLiteralBare")
public int echoInt(
@WebParam(name="IntegerInput",
targetNamespace="http://example.org/docLiteralBare")
int input)
{
System.out.println("echoInt '" + input + "' to you too!");
return input;
}
...

この例では、生成されるWSDLファイル内のechoInt操作のパラメータ名はIntegerInputになります。JWSファイルに@WebParamアノテーションがない場合、生成されるWSDLファイル内のパラメータ名は、メソッドのパラメータ名inputと同じになります。targetNamespace属性は、パラメータのXMLネームスペースがhttp://example.org/docLiteralBareであることを指定します。この属性は、パラメータとXML要素がマップされる、ドキュメント・スタイルのSOAPバインディングを使用する場合にのみ有効です。

@WebParamアノテーションの以下の追加の属性を指定することもできます。

- mode - パラメータの入出力の方向(WebParam.Mode.IN、WebParam.Mode.OUT、またはWebParam.Mode.INOUT)。OUTおよびINOUTモードは、Holder型のJAX-RPC定義に準拠するパラメータ型に対してのみ指定できます。OUTおよびINOUTモードは、RPC形式の操作、またはヘッダーにマップされるパラメータでのみサポートされます。

- header - trueに設定した場合、パラメータの値はデフォルトの本文からではなくSOAPヘッダーから取得されることを指定する、ブール型の属性。

@WebParamアノテーションの属性はいずれも必須ではありません。各属性のデフォルト値については、Web Services Metadata for the Java Platform (JSR 181)仕様(http://www.jcp.org/en/jsr/detail?id=181)を参照してください。

操作の戻り値とWSDL要素のマッピングのカスタマイズ(@WebResultアノテーション)

次のコードの抜粋で示すように、標準の@WebResultアノテーションを使用して、Webサービス操作の戻り値と生成されるWSDLファイル内の対応する要素との間のマッピングをカスタマイズします。

public class Simple {
@WebMethod()
@WebResult(name="IntegerOutput",
targetNamespace="http://example.org/docLiteralBare")
public int echoInt(
@WebParam(name="IntegerInput",
targetNamespace="http://example.org/docLiteralBare")
int input)
{
System.out.println("echoInt '" + input + "' to you too!");
return input;
}
...

この例では、生成されるWSDLファイル内のechoInt操作の戻り値の名前はIntegerOutputになります。JWSファイルに@WebResultアノテーションがない場合、生成されるWSDLファイル内の戻り値の名前は、ハード・コード化された名前returnになります。targetNamespace属性は、戻り値のXMLネームスペースがhttp://example.org/docLiteralBareであることを指定します。この属性は、戻り値とXML要素がマップされる、ドキュメント・スタイルのSOAPバインディングを使用する場合にのみ有効です。

@WebResultアノテーションの属性はいずれも必須ではありません。各属性のデフォルト値については、Web Services Metadata for the Java Platform (JSR 181)仕様(http://www.jcp.org/en/jsr/detail?id=181)を参照してください。

Webサービスの実行時情報へのアクセス

次の各項では、Webサービスの実行時情報へのアクセス方法について説明します。

- JwsContextを使用した実行時情報へのアクセス: Webサービス・コンテキストを使用して、JWSファイル内のサービスの実行時情報にアクセスし、その情報を変更します。

- Stubインタフェースを使用した実行時情報へのアクセス: クライアント・ファイル内のStubインタフェース上のプロパティを取得および設定します。

JwsContextを使用した実行時情報へのアクセス

JWSファイルを実装したWebLogic Webサービスをクライアント・アプリケーションが呼び出すと、WebLogic Serverでコンテキストが自動的に作成され、Webサービスはこのコンテキストを使用してサービスに関する実行時情報にアクセスし、場合によっては変更することもできます。この情報の大半は、現在の会話が終了したかどうか、現在の会話のプロパティ値、実行時の会話のプロパティの変更など、会話に関連しています。(会話および実装方法の詳細は、第9章「会話型Webサービスの作成」を参照してください)コンテキストを介してアクセス可能な情報の一部は、Webサービスの呼出しに使用されたプロトコル(HTTP/SまたはJMS)、SOAPメッセージ・リクエスト内にあったSOAPヘッダーなど、より一般的な情報で構成されています。

次の項で説明するように、JWSファイル内のアノテーションおよびWebLogic WebサービスAPIを使用して、実行時のコンテキスト情報にアクセスできます。

Webサービス・コンテキストへのアクセスに関するガイドライン

コンテキストを使用して、Webサービスの呼出しに使用されていたプロトコルを特定する簡単なサンプルJWSファイルを次に示します。太字のコードについては、例の後のプログラミングのガイドラインで説明しています。

package examples.webservices.jws_context;
import javax.jws.WebMethod;
import javax.jws.WebService;
import weblogic.jws.WLHttpTransport;
import weblogic.jws.Context;
import weblogic.wsee.jws.JwsContext;
import weblogic.wsee.jws.Protocol;
@WebService(name="JwsContextPortType", serviceName="JwsContextService",
targetNamespace="http://example.org")
@WLHttpTransport(contextPath="contexts", serviceUri="JwsContext",
portName="JwsContextPort")
/**
* Simple web service to show how to use the @Context annotation.
*/
public class JwsContextImpl {
@Context
private JwsContext ctx;
@WebMethod()
public String getProtocol() {
Protocol protocol = ctx.getProtocol();
System.out.println("protocol: " + protocol);
return "This is the protocol: " + protocol;
}
}

JWSファイルで、次のガイドライン(前述の例の太字で示されたコード)を使用して、Webサービスの実行時コンテキストにアクセスします。

- @weblogic.jws.Context JWSアノテーションをインポートします。

import weblogic.jws.Context;

- weblogic.wsee.jws.JwsContext APIと、使用する他の関連API (例ではweblogic.wsee.jws.Protocol APIも使用)をインポートします。

import weblogic.wsee.jws.JwsContext;
import weblogic.wsee.jws.Protocol;

- データ型weblogic.wsee.jws.JwsContextのプライベート変数に、フィールド・レベルの@Context JWSアノテーションを指定します。

@Context
private JwsContext ctx;

WebLogic Serverでは、Webサービスの初回の呼出しの際に、実行時にJwsContextの実装を指定するアノテーションを付加された変数(この場合はctx)が自動的に割り当てられます。これにより、この変数を後で使用する場合、コード内で明示的に初期化する必要がありません。

JwsContextクラスのメソッドを使用して、Webサービスの実行時情報にアクセスします。次の例では、Webサービスの呼出しに使用されたプロトコルを取得する方法を示します。

Protocol protocol = ctx.getProtocol();

使用できるメソッドの詳細なリストについては、「JwsContextのメソッド」を参照してください。

JwsContextのメソッド

次の表に、JWSファイル内でWebサービスの実行時情報にアクセスするために使用可能なJwsContextのメソッドの説明を示します。

表4-3 JwsContextのメソッド

メソッド

戻り値

説明

isFinished()

boolean

現在の会話が終了しているか、またはまだ続いているかを示すブール値を返します。

このメソッドは、会話形式のWebサービス、つまり、@Conversationまたは@Conversationalアノテーションが指定されているWebサービスでのみ使用します。

finishConversation()

void

現在の会話を終了します。

このメソッドは、@Conversation (Conversation.Phase.FINISH) JWSアノテーションを指定されたメソッドをクライアント・アプリケーションが呼び出すことと同じになります。

このメソッドは、会話形式のWebサービス、つまり、@Conversationまたは@Conversationalアノテーションが指定されているWebサービスでのみ使用します。

setMaxAge(java.util.Date)

void

会話の新しい最大存続期間を絶対日付のDateに設定します。この日付パラメータが過去の日付である場合、WebLogic Serverは直ちに会話を終了します。

このメソッドは、会話のデフォルトの最大存続期間を指定する、@ConversationalアノテーションのmaxAge属性に相当します。このメソッドを使用して、実行時にこのデフォルト値をオーバーライドします。

このメソッドは、会話形式のWebサービス、つまり、@Conversationまたは@Conversationalアノテーションが指定されているWebサービスでのみ使用します。

setMaxAge(String)

void

Stringの期間(1 dayなど)を指定して、会話の新しい最大存続期間を設定します。

Stringパラメータの有効な値は、数字と以下のいずれかの語です。

- seconds

- minutes

- hours

- days

- years

たとえば、最大存続期間を10分に設定するには、次の構文を使用します。

ctx.setMaxAge("10 minutes")

このメソッドは、会話のデフォルトの最大存続期間を指定する、@ConversationalアノテーションのmaxAge属性に相当します。このメソッドを使用して、実行時にこのデフォルト値をオーバーライドします。

このメソッドは、会話形式のWebサービス、つまり、@Conversationまたは@Conversationalアノテーションが指定されているWebサービスでのみ使用します。

getMaxAge()

long

許容される会話の最大存続期間を秒単位で返します。

このメソッドは、会話形式のWebサービス、つまり、@Conversationまたは@Conversationalアノテーションが指定されているWebサービスでのみ使用します。

getCurrentAge()

long

会話の現在の存続期間を秒単位で返します。

このメソッドは、会話形式のWebサービス、つまり、@Conversationまたは@Conversationalアノテーションが指定されているWebサービスでのみ使用します。

resetIdleTime()

void

現在の会話の最後のアクティビティ以降の秒数を測定するタイマーをリセットします。

このメソッドは、会話形式のWebサービス、つまり、@Conversationまたは@Conversationalアノテーションが指定されているWebサービスでのみ使用します。

setMaxIdleTime(long)

void

クライアントの動作がないためにWebLogic Serverが会話を終了するまでに、会話がアイドル状態を維持できる秒数を設定します。

このメソッドは、会話のデフォルトのアイドル時間を指定する、@ConversationalアノテーションのmaxIdleTime属性に相当します。このメソッドを使用して、実行時にこのデフォルト値をオーバーライドします。

このメソッドは、会話形式のWebサービス、つまり、@Conversationまたは@Conversationalアノテーションが指定されているWebサービスでのみ使用します。

setMaxIdleTime(String)

void

クライアントの動作がないためにWebLogic Serverが会話を終了するまでに、会話がアイドル状態を維持できる秒数をStringとして設定します。

Stringパラメータの有効な値は、数字と以下のいずれかの語です。

- seconds

- minutes

- hours

- days

- years

たとえば、最大アイドル時間を10分に設定するには、次の構文を使用します。

ctx.setMaxIdleTime("10 minutes")

このメソッドは、会話のデフォルトのアイドル時間を指定する、@ConversationalアノテーションのmaxIdleTime属性に相当します。このメソッドを使用して、実行時にこのデフォルト値をオーバーライドします。

このメソッドは、会話形式のWebサービス、つまり、@Conversationまたは@Conversationalアノテーションが指定されているWebサービスでのみ使用します。

getMaxIdleTime()

long

クライアントの動作がないためにWebLogic Serverが会話を終了するまでに、会話がアイドル状態を維持できる秒数を返します。

このメソッドは、会話形式のWebサービス、つまり、@Conversationまたは@Conversationalアノテーションが指定されているWebサービスでのみ使用します。

getCurrentIdleTime()

long

最後のクライアント・リクエスト以降の秒数、または、会話の最大アイドル時間のリセット以降の秒数を取得します。

このメソッドは、会話形式のWebサービス、つまり、@Conversationまたは@Conversationalアノテーションが指定されているWebサービスでのみ使用します。

getCallerPrincipal()

java.security.Principal

基本認証が実行されたと想定し、呼び出されたばかりの操作に関連付けられたセキュリティ・プリンシパルを返します。

isCallerInRole(String)

boolean

認証されるプリンシパルが指定されたセキュリティ・ロールに属している場合はtrueを返します。

getService()

weblogic.wsee.jws.ServiceHandle

WebLogic WebサービスAPIのServiceHandleのインスタンスを戻します(このインスタンスに問い合せると、会話ID (Webサービスが会話形式の場合)やWebサービスのURLなど、Webサービスの追加情報を収集できます)。

getLogger(String)

weblogic.wsee.jws.util.Logger

Loggerクラスのインスタンスを取得します(このインスタンスを使用すると、Webサービスからログ・ファイルにメッセージを送信できます)。

getInputHeaders()

org.w3c.dom.Element[]

現在の操作呼出しのSOAPリクエスト・メッセージに関連付けられたSOAPヘッダーの配列を返します。

setUnderstoodInputHeaders(boolean)

void

入力ヘッダーを解釈するかどうかを示します。

getUnderstoodInputHeaders()

boolean

setUnderstoodInputHeaderの呼出しによって設定された最新の値を返します。

setOutputHeaders(Element[])

void

現在の操作を最初に呼び出したクライアント・アプリケーションに返送されるSOAPレスポンス・メッセージに関連付ける、SOAPヘッダーの配列を指定します。

getProtocol()

weblogic.wsee.jws.Protocol

現在の操作を呼び出すのに使用されるプロトコル(HTTP/SやJMSなど)を返します。

Stubインタフェースを使用した実行時情報へのアクセス

javax.xml.rpc.Stubインタフェースを使用すると、Webサービス・クライアント・ファイル内でStubインスタンスを動的に構成できます。詳細は、http://download.oracle.com/javaee/6/api/javax/xml/rpc/Stub.htmlを参照してください。たとえば、次に示すようにport Stubインスタンスに対してターゲット・サービス・エンドポイントを動的に設定できます。

ComplexService service = new ComplexService_Impl (args[0] + "?WSDL" );
ComplexPortType port = service.getComplexServicePort();
((Stub)port)._setProperty(Stub.ENDPOINT_ADDRESS_PROPERTY,
"http://localhost:8010/MyContext/MyService");

Webサービス・クライアントの開発の詳細は、第6章「JAX-RPC Webサービス・クライアントの開発」を参照してください。

次の表に、JWSファイル内でWebサービスの実行時情報にアクセスするために使用できるStubインタフェースのメソッドの説明を示します。

表4-4 Stubインタフェースのメソッド

メソッド

戻り値

説明

_getProperty()

java.lang.Object

特定の構成プロパティの値を取得します。

_getPropertyNames()

java.util.Iterator

Stubインスタンスで構成可能なプロパティの名前のイテレータ・ビューを返します。

_setProperty()

void

Stubインスタンスの構成プロパティの名前および値を設定します。

以下の表では、Stubインスタンスからアクセスできるjavax.xml.rpc.Stubプロパティ値を定義します。

表4-5 Stubインタフェースのプロパティ

プロパティ

型

説明

ENDPOINT_ADDRESS_PROPERTY

java.lang.String

ターゲットのサービス・エンドポイント・アドレス。

PASSWORD_PROPERTY

java.lang.String

認証用パスワード。

SESSION_MAINTAIN_PROPERTY

java.lang.String

サービス・エンドポイントとのセッションに参加するかどうかを示すフラグ。

USERNAME_PROPERTY

java.lang.String

認証用ユーザー名。

ステートレス・セッションEJBを実装すべき場合

jwsc Antタスクでは、JWSファイルを処理するときは常に、Webサービスの基底の実装としてプレーンJavaオブジェクトが選択されます。

しかし、Webサービスの基底の実装をステートレス・セッションEJBにして、EJBが提供するすべての機能(インスタンス・プール、トランザクション、セキュリティ、コンテナ管理による永続性、コンテナ管理による関連、データ・キャッシュなど)を使用することが必要な場合もあります。Webサービスの実装をEJBにする場合は、次の項のプログラミング・ガイドラインに従ってください。

注意:
JAX-RPCはEJB 2.xのみをサポートし、EJB 3.0をサポートしません。

JWSファイルでEJBを実装する場合のプログラミングのガイドライン

一般的なガイドラインは、JWSファイルで常にEJBGenアノテーションを使用して、EJBを実装する場合に必要なEJBリモートおよびホーム・インタフェース・クラスおよびデプロイメント記述子ファイルを、手動で作成するのではなく、自動的に生成することです。EJBGenアノテーションはJWSアノテーションと同じように動作します。JDK 5.0メタデータ構文に従い、プログラミング・タスクを大幅に簡素化します。

EJBGenの詳細は、『Oracle WebLogic Server Enterprise JavaBeansバージョン2.1の開発』のEJBGenリファレンスに関する項を参照してください。

JWSファイルでステートレス・セッションEJBを明示的に実装する場合は、以下のガイドラインに従います。例については「EJBを実装するJWSファイルの例」を参照してください。該当する部分は太字で示されています。

- 標準的なJava Platform, Enterprise Edition (Java EE)バージョン5のEJBクラスをインポートします。

import javax.ejb.SessionBean;
import javax.ejb.SessionContext;

- EJBGenアノテーションをインポートします。EJBGenアノテーションはすべてweblogic.ejbgenパッケージにあります。少なくとも、@Sessionアノテーションをインポートする必要があります。EJBの形式や動作を指定するためにJWSファイルで追加のEJBGenアノテーションを使用する場合は、『Oracle WebLogic Server Enterprise JavaBeansバージョン2.1の開発』のEJBGenリファレンスに関する項を参照し、インポートすべきアノテーションの名前を確認してください。

import weblogic.ejbgen.Session;

- 少なくとも、@Sessionアノテーションをクラス・レベルで使用して、EJBの名前を指定します。

@Session(ejbName="TransactionEJB")

JWSファイルで使用する場合、必須のEJBGenアノテーションは@Sessionのみです。必要な場合は、他のEJBGenアノテーションを使用して、EJBの追加機能を指定します。

- JWSクラスで必ずSessionBeanを実装します。

public class TransactionImpl implements SessionBean {...

- 標準のEJBメソッドejbCreate()、ejbActivate()なども含める必要があります。ただし、通常は、EJBのデフォルトの動作を変更するのでない限り、これらのメソッドにコードを追加する必要はありません。

public void ejbCreate() {}
public void ejbActivate() {}
public void ejbRemove() {}
public void ejbPassivate() {}
public void setSessionContext(SessionContext sc) {}

JWSファイルでこれらのガイドラインにすべて従うと、jwsc AntタスクはWebサービスをEJBにコンパイルして、それをエンタープライズ・アプリケーション内部のEJB JARファイルにパッケージ化します。

EJBを実装するJWSファイルの例

以下の例では、ステートレス・セッションEJBを実装する簡単なJWSファイルを示します。関連するコードは太字で示されています。

package examples.webservices.transactional;
import javax.ejb.SessionBean;
import javax.ejb.SessionContext;
import javax.jws.WebMethod;
import javax.jws.WebService;
import weblogic.jws.WLHttpTransport;
import weblogic.jws.Transactional;
import weblogic.ejbgen.Session;
@Session(ejbName="TransactionEJB")
@WebService(name="TransactionPortType", serviceName="TransactionService",
targetNamespace="http://example.org")
@WLHttpTransport(contextPath="transactions", serviceUri="TransactionService",
portName="TransactionPort")
/**
* This JWS file forms the basis of simple EJB-implemented WebLogic
* Web Service with a single operation: sayHello.  The operation executes
* as part of a transaction.
*
*/
public class TransactionImpl implements SessionBean {
@WebMethod()
@Transactional(value=true)
public String sayHello(String message) {
System.out.println("sayHello:" + message);
return "Here is the message: '" + message + "'";
}
// Standard EJB methods.  Typically there's no need to override the methods.
public void ejbCreate() {}
public void ejbActivate() {}
public void ejbRemove() {}
public void ejbPassivate() {}
public void setSessionContext(SessionContext sc) {}
}

ユーザー定義のJavaデータ型のプログラミング

Webサービス操作として公開されるJWSファイルのメソッドでは、パラメータや戻り値として必ずしも組込みのデータ型(Stringやintegerなど)を使用する必要はなく、独自に作成するJavaデータ型を使用することができます。ユーザー定義のデータ型の例としては、Stringの銘柄記号とintegerの売買株式数という2つのフィールドを持つTradeResultがあります。

JWSファイルで、1つまたは複数のメソッドのパラメータまたは戻り値としてユーザー定義のデータ型を使用する場合は、データ型のJavaコードを独自に作成して、JWSファイルにそのクラスをインポートし、適切に使用する必要があります。jwsc Antタスクは、Javaユーザー定義データ型の対応するXMLスキーマ表現、JAX-RPCの型マッピング・ファイルなど、必要なデータ・バインディング・アーティファクトをすべて作成します。

ユーザー定義のデータ型のJavaコードを記述するときは、以下の基本的な要件に従います。

- デフォルト・コンストラクタを定義します。これは、パラメータを取らないコンストラクタです。

- 公開するメンバー変数ごとにgetXXX()メソッドとsetXXX()メソッドの両方を定義します。

- 公開される各メンバー変数のデータ型は、組込みデータ型のいずれか、または組込みデータ型で構成されるユーザー定義のデータ型にします。

これらの要件はJAX-RPCで指定されています。要件の詳細と完全なリストについては、JAX-RPC仕様(http://java.net/projects/jax-rpc/)を参照してください。

jwsc Antタスクでは、最も一般的なXMLおよびJavaデータ型のデータ・バインディング・アーティファクトを生成できます。サポートされるユーザー定義のデータ型のリストは、「サポートされるユーザー定義のデータ型」を参照してください。サポートされる組込みデータ型の完全なリストは、「サポートされる組込みデータ型」参照してください。

次の例では、BasicStructという簡単なユーザー定義のJavaデータ型を示します。

package examples.webservices.complex;
/**
* Defines a simple JavaBean called BasicStruct that has integer, String,
* and String[] properties
*/
public class BasicStruct {
// Properties
private int intValue;
private String stringValue;
private String[] stringArray;
// Getter and setter methods
public int getIntValue() {
return intValue;
}
public void setIntValue(int intValue) {
this.intValue = intValue;
}
public String getStringValue() {
return stringValue;
}
public void setStringValue(String stringValue) {
this.stringValue = stringValue;
}
public String[] getStringArray() {
return stringArray;
}
public void setStringArray(String[] stringArray) {
this.stringArray = stringArray;
}
}

以下のJWSファイルの抜粋では、BasicStructクラスをインポートして、1つのメソッドのパラメータおよび戻り値として使用する方法を示しています。完全なJWSファイルについては、「サンプルComplexImpl.java JWSファイル」を参照してください。

package examples.webservices.complex;
// Import the standard JWS annotation interfaces
import javax.jws.WebMethod;
import javax.jws.WebParam;
import javax.jws.WebResult;
import javax.jws.WebService;
import javax.jws.soap.SOAPBinding;
// Import the WebLogic-specific JWS annotation interface
import weblogic.jws.WLHttpTransport;
// Import the BasicStruct JavaBean
import examples.webservices.complex.BasicStruct;
@WebService(serviceName="ComplexService", name="ComplexPortType",
targetNamespace="http://example.org")
...
public class ComplexImpl {
@WebMethod(operationName="echoComplexType")
public BasicStruct echoStruct(BasicStruct struct)
{
return struct;
}
}

例外のスロー

JWSファイルのメソッド内にエラー処理のJavaコードを記述する場合は、独自のユーザー定義の例外をスローすることも、javax.xml.rpc.soap.SOAPFaultException例外をスローすることもできます。SOAPFaultExceptionをスローする場合、WebLogic Serverは例外をSOAPエラーにマップして、操作を呼び出すクライアント・アプリケーションに送信します。

JWSファイルがSOAPFaultException以外のJava例外をスローした場合、WebLogic Serverはその例外をできる限りSOAPエラーにマップしようとします。ただし、クライアント・アプリケーションが受け取る例外を制御して、最適な例外情報を送るには、SOAPFaultExceptionまたはSOAPFaultExceptionを拡張した例外を明示的にスローする必要があります。ユーザー定義の例外の作成とスローの詳細は、JAX-RPC仕様(http://java.net/projects/jax-rpc/)を参照してください。

次の抜粋では、SOAPFaultExceptionクラスを記述しています。

public class SOAPFaultException extends java.lang.RuntimeException {
public SOAPFaultException (QName faultcode,
String faultstring,
String faultactor,
javax.xml.soap.Detail detail ) {...}
public Qname getFaultCode() {...}
public String getFaultString() {...}
public String getFaultActor() {...}
public javax.xml.soap.Detail getDetail() {...}
}

SOAP with Attachments API for Java 1.1 (SAAJ)のjavax.xml.soap.SOAPFactory.createDetail()メソッドを使用して、Detailオブジェクトを作成します。このオブジェクトは、エラーに関するアプリケーション固有の詳細情報を提供するDetailEntryオブジェクトのコンテナになります。

SOAPFactoryの独自の実装を使用することも、Oracleの実装を使用することもできます。Oracleの実装には、JWSファイルから静的メソッドweblogic.wsee.util.WLSOAPFactory.createSOAPFactory()を呼び出してアクセスできます。このメソッドはjavax.xml.soap.SOAPFactoryオブジェクトを返します。実行時には、-Djavax.xml.soap.SOAPFactoryフラグを使用して、OracleのSOAPFactory実装を指定します。次に例を示します。

-Djavax.xml.soap.SOAPFactory=weblogic.xml.saaj.SOAPFactoryImpl

次のJWSファイルは、Webサービスの操作を実装するメソッド内からSOAPFaultExceptionを作成してスローする例を示しています。太字の部分は例外コードを表しています。

package examples.webservices.soap_exceptions;
import javax.xml.namespace.QName;
import javax.xml.soap.Detail;
import javax.xml.soap.SOAPException;
import javax.xml.soap.SOAPFactory;
import javax.xml.rpc.soap.SOAPFaultException;
// Import the @WebService annotation
import javax.jws.WebService;
// Import WLHttpTransport
import weblogic.jws.WLHttpTransport;
@WebService(serviceName="SoapExceptionsService",
name="SoapExceptionsPortType",
targetNamespace="http://example.org")
@WLHttpTransport(contextPath="exceptions",
serviceUri="SoapExceptionsService",
portName="SoapExceptionsServicePort")
/**
* This JWS file forms the basis of simple Java-class implemented WebLogic
* Web Service with a single operation: sayHelloWorld
*
*/
public class SoapExceptionsImpl {
public SoapExceptionsImpl() {
}
public void tirarSOAPException() {
Detail detail = null;
try {
SOAPFactory soapFactory = SOAPFactory.newInstance();
detail = soapFactory.createDetail();
} catch (SOAPException e) {
// do something
}
QName faultCode = null;
String faultString = "the fault string";
String faultActor = "the fault actor";
throw new SOAPFaultException(faultCode, faultString, faultActor, detail);
}
}

この例では、SOAPFactoryのデフォルトの実装を使用しています。

注意:
SOAPFaultExceptionを使用せずに独自の例外を作成およびスローする場合に、例外クラスの複数のプロパティのデータ型が同じであるときは、これらのプロパティのセッター・メソッドも作成する必要があります(JAX-RPC仕様で規定されているわけではありません)。これは、WebLogic WebサービスがSOAPメッセージで例外を受け取り、XMLをJava例外クラスに変換するときに、対応するセッター・メソッドがなければ、どのXML要素をどのクラス・プロパティにマップするのかを知る方法がないからです。

JWSファイルからの別のWebサービスの呼出し

JWSファイル内から別のWebサービス(WebLogic ServerにデプロイされているWebサービス、または.NETなどの他のアプリケーション・サーバーにデプロイされているWebサービス)を呼び出すことができます。これを行う手順は、「Java SEクライアントからのWebサービスの呼出し」で説明した手順と似ていますが、clientgen Antタスクを実行してクライアント・スタブを生成するのではなく、呼出し側のWebサービスをビルドするjwsc Antタスクに<clientgen>子要素を含めてクライアント・スタブを生成します。続いて、JWSファイルにある標準JAX-RPC APIを使用します。

詳細な手順については、「別のWebサービスからのWebサービスの呼出し」を参照してください。

JWSアノテーションおよびAPIによるその他の機能のプログラミング

次の各項では、JWSファイル内で特定のJWSアノテーションを指定するか、WebLogic WebサービスAPIを使用してプログラミングできるその他の機能について説明します。

- MTOM/XOPを使用したバイナリ・データの送信

- SOAP添付ファイルのストリーミング

- SOAP 1.2の使用

- トランザクション内で実行する操作の指定

- HttpServletRequest/Responseオブジェクトの取得

MTOM/XOPを使用したバイナリ・データの送信

SOAP Message Transmission Optimization Mechanism/XML-binary Optimized Packaging (MTOM/XOP)では、SOAPメッセージ内のxs:base64Binary型のXMLデータの送信を最適化する方法が説明されています。トランスポート・プロトコルがHTTPの場合、MIME添付ファイルを使用して、送信側と受信側の両方に対して同時にSOAPメッセージ内のXMLデータへの直接アクセスを許可する間にデータを伝達します。このとき、xs:base64BinaryデータのマーシャリングにMIMEアーティファクトが使用されていたことを意識する必要はありません。バイナリ・データの最適化プロセスでは、バイナリ・データのエンコード、SOAPエンベロープからの削除、圧縮およびMIMEパッケージへの添付、SOAPエンベロープでのそのパッケージへのリファレンスの追加を行います。

MTOM仕様では、MTOMが有効化されている場合に、base64binaryデータ送信時にWebサービスのランタイムでXOPバイナリ最適化を使用することは必須ではありません。むしろ、この仕様では、ランタイムがこれを選択して行うようになっています。これは場合によっては、直接SOAPメッセージ内にbase64binaryデータを送信するほうが、より効率的であるとランタイムで判断されることがあるためです。一例としては、トランスポートされるデータ量が少なく、単にデータをそのままインライン処理するよりも多くのリソースが、会話およびトランスポートのオーバーヘッドにより消費されてしまう場合が挙げられます。しかしながら、JAX-RPCサービスのMTOM用WebLogic Webサービスの実装では、MTOMが有効化されている場合には、常にMTOM/XOPが使用されます。

WebLogic JAX-RPC WebサービスでのMTOM/XOPのサポートは、あらかじめパッケージ化されたWS-PolicyファイルMtom.xmlを使用して実装されます。WS-Policyファイルは、http://www.w3.org/TR/ws-policyで説明されているWS-Policy仕様に準拠しています。この仕様では、WEBサービスのポリシー(この場合は、バイナリ・データ送信のためのMTOM/XOPの使用)を記述および通信する汎用モデルおよびXML構文を提供しています。WebサービスWSDLのtypesセクションへの、あらかじめパッケージ化されたMtom.xml WS-Policyファイルのインストールは、次のようになります(参考のためにのみ掲載しています。このファイルは変更できません)。

<wsp:Policy wsu:Id="myService_policy">
<wsp:ExactlyOne>
<wsp:All>
<wsoma:OptimizedMimeSerialization
xmlns:wsoma="http://schemas.xmlsoap.org/ws/2004/09/policy/optimizedmimeserialization" />
</wsp:All>
</wsp:ExactlyOne>
</wsp:Policy>

コンパイルされたJWSファイルをWebLogic Serverにデプロイする際には、MTOM WS-Policyファイルを参照する次のスニペットが動的WSDL内に自動的に含まれます。このスニペットは、WebサービスがMTOM/XOPを使用することを示しています。

<wsdl:binding name="BasicHttpBinding_IMtomTest"
type="i0:IMtomTest">
<wsp:PolicyReference URI="#myService_policy" />
<soap:binding transport="http://schemas.xmlsoap.org/soap/http" />

JWSファイルで@Policyメタデータ・アノテーションを指定することによって、開発時にWebサービスとMtom.xml WS-Policyファイルを関連付けることができます。動的WSDLに、必須であるMtom.xmlファイルへの参照が確実に含まれるよう、必ずattachToWsdl=true属性も指定します。下記の例を参照してください。

デプロイメント時にWebサービスとMtom.xml WS-Policyファイルを関連付けるには、デプロイメント直前にtypesセクションにポリシーを追加し、WSDLを修正します。

また、WebLogic Server管理コンソールを使用して実行時にファイルを追加できます。詳細は、Oracle WebLogic Server管理コンソール・オンライン・ヘルプのWS-PolicyファイルのWebサービスへの追加に関する項を参照してください。この節では、JWSアノテーションの使用方法について説明します。

注意:
このリリースのWebLogic Serverでは、MTOM/XOP使用時にサポートされるJavaデータ型はbyte[]のみです。その他のバイナリ・データ型(imageなど)はサポートされていません。
このリリースのWebLogic Serverでは、非推奨になった9.xセキュリティ・ポリシーのあるMTOMの使用はサポートされていません。

MTOM/XOPを使用してバイナリ・データを送信するには、次の手順に従います。

1. 次の簡単なJWSファイルに示すように、JWSファイル内でWebLogic固有の@weblogic.jws.Policyアノテーションを使用し、あらかじめパッケージ化されたMtom.xmlファイルをWebサービスに適用することを指定します(該当するコードは太字で示してあります)。

package examples.webservices.mtom;
import javax.jws.WebMethod;
import javax.jws.WebService;
import weblogic.jws.WLHttpTransport;
import weblogic.jws.Policy;
@WebService(name="MtomPortType",
serviceName="MtomService",
targetNamespace="http://example.org")
@WLHttpTransport(contextPath="mtom",
serviceUri="MtomService",
portName="MtomServicePort")
@Policy(uri="policy:Mtom.xml", attachToWsdl=true)
public class MtomImpl {
@WebMethod
public String echoBinaryAsString(byte[] bytes) {
return new String(bytes);
}

2. 結果として得られるSOAPメッセージでMTOM/XOPを使用してバイナリ・データの送受信を行う場合は必ず、Webサービス操作でJava byte[]データ型を戻り値または入力パラメータとして使用します。一例としては、上述のechoBinaryAsString操作の実装を参照してください。この操作では、単純にbyteの配列を入力として取り、それをStringとして返しています。

3. WebLogic WebサービスのランタイムにはMTOM/XOPのサポートが組み込まれており、clientgen Antタスクによりクライアント側アーティファクトが生成されるWSDLでMTOM/XOPのサポートが指定されている場合に有効になります。クライアント・アプリケーション自体では、関連データ型としてbyte[]を使用して、通常どおり操作を呼び出します。

MTOM/XOP機能そのものとWebLogic JAX-RPC Webサービスでサポートされる仕様のバージョンの詳細は、SOAP Message Transmission Optimization Mechanism仕様(http://www.w3.org/TR/2005/REC-soap12-mtom-20050125)を参照してください。

SOAP添付ファイルのストリーミング

@weblogic.jws.StreamAttachments JWSアノテーションを使用すると、添付ファイルを含む着信SOAPメッセージを読み取る際に、メッセージ全体をメモリーに読み込むデフォルト動作のかわりに、WebサービスでストリーミングAPIを使用することを指定できます。この機能を使用すると、SOAPメッセージが非常に大きい場合のWebサービスのパフォーマンスを向上させることができます。

添付ファイルをストリーミングすることを指定した例については、『Oracle WebLogic Server Webサービス・リファレンス』のweblogic.jws.StreamAttachmentsに関する項を参照してください。

SOAP 1.2の使用

WebLogic Webサービスでは、Webサービスとそのクライアントの間でデータや呼出しを転送する際に、メッセージ・フォーマットとしてデフォルトでバージョン1.1のSOAP (Simple Object Access Protocol)が使用されます。WebLogic Webサービスでは、SOAP 1.1と新しいSOAP 1.2の両バージョンがサポートされており、どちらのバージョンでも使用できます。

Webサービスでバージョン1.2のSOAPを使用することを指定するには、次の例に示すように、JWSファイルでクラス・レベルの@weblogic.jws.Bindingアノテーションを使用して、その唯一の属性の値をBinding.Type.SOAP12に設定します(該当するコードは太字で示してあります)。

package examples.webservices.soap12;
import javax.jws.WebMethod;
import javax.jws.WebService;
import weblogic.jws.WLHttpTransport;
import weblogic.jws.Binding;
@WebService(name="SOAP12PortType",
serviceName="SOAP12Service",
targetNamespace="http://example.org")
@WLHttpTransport(contextPath="soap12",
serviceUri="SOAP12Service",
portName="SOAP12ServicePort")
@Binding(Binding.Type.SOAP12)
/**
* This JWS file forms the basis of simple Java-class implemented WebLogic
* Web Service with a single operation: sayHello.  The class uses SOAP 1.2
* as its binding.
*
*/
public class SOAP12Impl {
@WebMethod()
public String sayHello(String message) {
System.out.println("sayHello:" + message);
return "Here is the message: '" + message + "'";
}
}

WebサービスでSOAP 1.2を使用する上で、このアノテーションを設定する以外に必要な作業はありません(Webサービスを呼び出すクライアント・アプリケーションの変更も不要です)。WebLogic Webサービス・ランタイムによってすべて自動的に処理されます。

このアノテーションの詳細は、『Oracle WebLogic Server Webサービス・リファレンス』のweblogic.jws.Bindingに関する項を参照してください。

トランザクション内で実行する操作の指定

クライアント・アプリケーションからWebLogic Webサービス操作を呼び出す場合、操作呼出しはデフォルトではトランザクションのコンテキストの外で実行されます。トランザクション内で操作を実行するには、次の例に示すように、JWSファイルで@weblogic.jws.Transactionalアノテーションを指定して、ブール型のvalue属性の値をtrueに設定します(該当するコードは太字で示してあります)。

package examples.webservices.transactional;
import javax.jws.WebMethod;
import javax.jws.WebService;
import weblogic.jws.WLHttpTransport;
import weblogic.jws.Transactional;
@WebService(name="TransactionPojoPortType",
serviceName="TransactionPojoService",
targetNamespace="http://example.org")
@WLHttpTransport(contextPath="transactionsPojo",
serviceUri="TransactionPojoService",
portName="TransactionPojoPort")
/**
* This JWS file forms the basis of simple WebLogic
* Web Service with a single operation: sayHello.  The operation executes
* as part of a transaction.
*
*/
public class TransactionPojoImpl {
@WebMethod()
@Transactional(value=true)
public String sayHello(String message) {
System.out.println("sayHello:" + message);
return "Here is the message: '" + message + "'";
}
}

Webサービスのすべての操作をトランザクション内で実行する場合は、@Transactionalアノテーションをクラス・レベルで指定します。一部の操作のみをトランザクション内で実行する場合は、このアノテーションをメソッド・レベルで指定します。競合が発生した場合は、メソッド・レベルの値でクラス・レベルの値がオーバーライドされます。

追加属性の詳細は、『Oracle WebLogic Server Webサービス・リファレンス』のweblogic.jws.Transactionalに関する項を参照してください。

HttpServletRequest/Responseオブジェクトの取得

トランスポート・プロトコルとしてHTTPを使用する場合は、次の例に示すように、weblogic.wsee.connection.transport.servlet.HttpTransportUtilsを使用して、JAX-RPC ServletEndpointContextオブジェクトからjavax.servlet.http.HttpServletRequestおよびjavax.servlet.http.HttpServletResponseオブジェクトを取得できます(該当するコードを太字で示し、例の後で解説を加えます)。

package examples.webservices.http_transport_utils;
import javax.xml.rpc.server.ServiceLifecycle;
import javax.xml.rpc.server.ServletEndpointContext;
import javax.xml.rpc.ServiceException;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.jws.WebMethod;
import javax.jws.WebService;
import weblogic.jws.WLHttpTransport;
import weblogic.wsee.connection.transport.servlet.HttpTransportUtils;
@WebService(name="HttpTransportUtilsPortType",
serviceName="HttpTransportUtilsService",
targetNamespace="http://example.org")
@WLHttpTransport(contextPath="servlet", serviceUri="HttpTransportUtils",
portName="HttpTransportUtilsPort")
public class HttpTransportUtilsImpl implements ServiceLifecycle {
private ServletEndpointContext wsctx = null;
public void init(Object context) throws ServiceException {
System.out.println("ServletEndpointContext inited...");
wsctx = (ServletEndpointContext)context;
}
public void destroy() {
System.out.println("ServletEndpointContext destroyed...");
wsctx = null;
}
@WebMethod()
public String getServletRequestAndResponse() {
HttpServletRequest request =
HttpTransportUtils.getHttpServletRequest(wsctx.getMessageContext());
HttpServletResponse response =
HttpTransportUtils.getHttpServletResponse(wsctx.getMessageContext());
System.out.println("HttpTransportUtils API used successfully.");
return "HttpTransportUtils API used successfully";
}
}

上の例の中で重要な部分は以下のとおりです。

- 必要なJAX-RPCおよびServletクラスのインポート。

import javax.xml.rpc.server.ServiceLifecycle;
import javax.xml.rpc.server.ServletEndpointContext;
import javax.xml.rpc.ServiceException;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

- WebLogic HttpTransportUtilsクラスのインポート。

import weblogic.wsee.connection.transport.servlet.HttpTransportUtils;

- JAX-RPCメッセージ・コンテキストを問い合せることになるため、JWSファイルではServiceLifecycleを明示的に実装する必要があります。

public class HttpTransportUtilsImpl implements ServiceLifecycle

- データ型ServletEndpointContextの変数の作成。

private ServletEndpointContext wsctx = null;

- JWSファイルでServiceLifecycleを実装するため、initおよびdestroyライフサイクル・メソッドも実装する必要があります。

public void init(Object context) throws ServiceException {
System.out.println("ServletEndpointContext inited...");
wsctx = (ServletEndpointContext)context;
}
public void destroy() {
System.out.println("ServletEndpointContext destroyed...");
wsctx = null;
}

- 最後に、Webサービス操作を実装するメソッドで、ServletEndpointContextオブジェクトを使用してHttpServletRequestおよびHttpServletResponseオブジェクトを取得します。

HttpServletRequest request =
HttpTransportUtils.getHttpServletRequest(wsctx.getMessageContext());
HttpServletResponse response =
HttpTransportUtils.getHttpServletResponse(wsctx.getMessageContext());

JWSプログラミングのベスト・プラクティス

以下のリストでは、JWSファイルをプログラミングする場合のベスト・プラクティスを示します。

- document-literal-bareのWebサービスを作成する場合は、@WebParam JWSアノテーションを使用して、特定のWebサービスのすべての操作のすべての入力パラメータに一意の名前を付けるようにします。document-literal-bareのWebサービスの性質上、@WebParamアノテーションを使用して入力パラメータの名前を明示的に指定しない場合、WebLogic Serverが入力パラメータの名前を作成するため、Webサービス内でパラメータの名前が重複するおそれがあります。

- 一般に、最も相互運用性の高いタイプのWebサービスは、document-literal-wrappedのWebサービスです。

- ハード・コード化された名前returnに常に依存するのではなく、@WebResult JWSアノテーションを使用して、操作の戻り値の名前を明示的に設定します。JWSファイルで@WebResultアノテーションを使用しない場合、returnが戻り値のデフォルト名になります。

- Webサービスの呼出し中にエラーが発生した場合に、クライアント・アプリケーションに戻される例外情報を制御するには、JWSファイルでSOAPFaultExceptionを使用します。

- 必須ではありませんが、JWSファイルでWebLogic固有の@WLHttpTransportアノテーションのportName属性を常に指定することをお薦めします。この属性を指定しない場合、jwsc AntタスクはWSDLファイルの生成時にポート名を生成しますが、この名前はユーザーにとってわかりにくい場合があります。その結果、Webサービスを呼び出すためにクライアント・アプリケーションで使用するgetXXX()メソッドの名前が適切に指定されなくなります。クライアント・アプリケーションがWebサービスを呼び出すときにわかりやすいメソッドを使用できるようにするには、portName属性を使用して、Webサービスの該当するポート名を指定します。

5 データ・バインディングの理解

この章では、Java API for XML-based RPC (JAX-RPC)を使用したWebLogic Webサービスでサポートされるデータ・バインディングおよびデータ型(組込みおよびユーザー定義)について説明します。

この章の内容は次のとおりです。

- データ・バインディングの概要

- サポートされる組込みデータ型

- サポートされるユーザー定義のデータ型

データ・バインディングの概要

様々なシステム間でのデータ交換にはXMLが標準的に使用されているため、Webサービス・アプリケーションには、Javaアプリケーションから直接XML形式のドキュメントへアクセスする手段が必要となります。具体的には、XMLコンテンツをJavaアプリケーションで読み取れる形式に変換する必要があります。データ・バインディングでは、XML表現とJava表現間のデータ変換を記述します。

以前のリリースと同様、WebLogic Webサービスでは、JAX-RPC仕様(http://java.net/projects/jax-rpc/)の規定に従って組込みのXMLスキーマ、Java、およびSOAPのデータ型がサポートされており、追加のプログラミング手順を踏まずに、そうしたデータ型をWebサービスの操作で使用できます。組込みデータ型には、integer、string、timeなどがあります。

また、Webサービスの入力パラメータや戻り値として、様々なユーザー定義のXMLおよびJavaデータ型(org.apache.xmlbeansパッケージのApache XmlBeansを含む)を使用できます。ユーザー定義のデータ型には、XMLスキーマやJavaの構成要素から作成する<xsd:complexType>やJavaBeanなどがあります。jwscやclientgenなどのWebLogic WebサービスAntタスクでは、ユーザー定義のデータ型をXML表現とJava表現の間で変換するのに必要なデータ・バインディング・アーティファクトが自動的に生成されます。XML表現はSOAPリクエストやレスポンス・メッセージで使用し、Java表現はWebサービスを実装するJWSで使用します。

注意:
WebLogic Server 9.1以降では、XMLBeans 1.xデータ型(つまりcom.bea.xml.XmlObjectの拡張)をWebLogic Webサービスのパラメータまたは戻り値の型として使用することは非推奨です。新たに作成するアプリケーションでは、XMLBeans 2.xのデータ型を使用する必要があります。
-noupaオプションを指定してコンパイルしたXMLBeansをWebサービスで使用する場合は、Webサービスが正常にデプロイされるよう、WebLogic Serverの起動スクリプトに-Dweblogic.wsee.bind.setCompileNoUpaRule=trueフラグを設定する必要があります。そうしないと、cos-nonambig: Content model violates the unique particle attribution ruleというエラーが発生してデプロイメントは失敗します。

サポートされる組込みデータ型

次の各項では、WebLogic Webサービスがサポートする組込みデータ型、およびそのXML表現とJava表現の間のマッピングについて説明します。Webサービスを実装するバックエンド・コンポーネントのパラメータと戻り値のデータ型が、組込みデータ型のセットの中にあるかぎり、データはWebLogic Serverによって、XMLとJava間で自動的に変換されます。

一方、ユーザー定義のデータ型を使用する場合は、XML表現とJava表現の間でデータを変換するデータ・バインディング・アーティファクトを作成する必要があります。WebLogic Serverにはjwscおよびwsdlc Antタスクが含まれており、ほとんどのユーザー定義データ型のデータ・バインディング・アーティファクトを自動的に生成できます。サポートされるXMLとJavaのデータ型については、「サポートされるユーザー定義のデータ型」を参照してください。

組込みデータ型のXML-to-Javaマッピング

次の表に、サポートされるXMLスキーマ・データ型(ターゲット・ネームスペースhttp://www.w3.org/2001/XMLSchema)と、それぞれに対応するJavaデータ型をまとめます。

サポートされるユーザー定義のXMLデータ型については、「組込みデータ型のJava-to-XMLマッピング」を参照してください。

表5-1 XMLスキーマの組込みデータ型とJavaデータ型のマッピング

XMLスキーマ・データ型

Javaデータ型(小文字はプリミティブ・データ型を示します)

boolean

boolean

byte

byte

short

short

int

int

long

long

float

float

double

double

integer

java.math.BigInteger

decimal

java.math.BigDecimal

string

java.lang.String

dateTime

java.util.Calendar

base64Binary

byte[]

hexBinary

byte[]

duration

java.lang.String

time

java.util.Calendar

date

java.util.Calendar

gYearMonth

java.util.Calendar

gYear

java.util.Calendar

gMonthDay

java.util.Calendar

gDay

java.util.Calendar

gMonth

java.util.Calendar

anyURI

java.net.URI

NOTATION

java.lang.String

token

java.lang.String

normalizedString

java.lang.String

language

java.lang.String

Name

java.lang.String

NMTOKEN

java.lang.String

NCName

java.lang.String

NMTOKENS

java.lang.String[]

ID

java.lang.String

IDREF

java.lang.String

ENTITY

java.lang.String

IDREFS

java.lang.String[]

ENTITIES

java.lang.String[]

nonPositiveInteger

java.math.BigInteger

nonNegativeInteger

java.math.BigInteger

negativeInteger

java.math.BigInteger

unsignedLong

java.math.BigInteger

positiveInteger

java.math.BigInteger

unsignedInt

long

unsignedShort

int

unsignedByte

short

Qname

javax.xml.namespace.QName

組込みデータ型のJava-to-XMLマッピング

サポートされるユーザー定義のJavaデータ型については、「サポートされるユーザー定義のJavaデータ型」を参照してください。

表5-2 Javaデータ型とXMLスキーマ・データ型のマッピング

Javaデータ型(小文字はプリミティブ・データ型を示します)

同等のXMLスキーマ・データ型

int

int

short

short

long

long

float

float

double

double

byte

byte

boolean

boolean

char

string (with facet of length=1)

java.lang.Integer

int

java.lang.Short

short

java.lang.Long

long

java.lang.Float

float

java.lang.Double

double

java.lang.Byte

byte

java.lang.Boolean

boolean

java.lang.Character

string (with facet of length=1)

java.lang.String

string

java.math.BigInteger

integer

java.math.BigDecimal

decimal

java.util.Calendar

dateTime

java.util.Date

dateTime

byte[]

base64Binary

javax.xml.namespace.QName

Qname

java.net.URI

anyURI

javax.xml.datatype.XMLGregorianCalendar

anySimpleType

javax.xml.datatype.Duration

duration

java.lang.Object

anyType

java.awt.Image

base64Binary

javax.activation.DataHandler

base64Binary

javax.xml.transform.Source

base64Binary

java.util.UUID

string

サポートされるユーザー定義のデータ型

以降の項の表には、jwscおよびwsdlc Antタスクでデータ・バインディング・アーティファクトを自動的に生成できるユーザー定義のXMLデータ型およびJavaデータ型(対応するJava表現またはXML表現、JAX-RPCの型マッピング・ファイルなど)をまとめます。

これらの表にないXMLデータ型またはJavaデータ型で、「サポートされる組込みデータ型」の表に示した組込みデータ型でもない型の場合は、ユーザー定義データ型のアーティファクトを手動で作成する必要があります。

サポートされるユーザー定義のXMLデータ型

次の表に、jwscおよびwsdlc AntタスクでサポートされるXMLスキーマ・データ型と、それぞれに対応するJavaデータ型またはマッピング・メカニズムをまとめます。

データ型の詳細と例については、JAX-RPC仕様(http://java.net/projects/jax-rpc/)を参照してください。

表5-3 サポートされているユーザー定義のXMLスキーマ・データ型

XMLスキーマ・データ型

同等のJavaデータ型またはマッピング・メカニズム

単純型および複合型の両方の要素を持つ<xsd:complexType>

JavaBean

単純なコンテンツを含む<xsd:complexType>

JavaBean

<xsd:complexType>の<xsd:attribute>

JavaBeanのプロパティ。

既存の単純型の制限による新しい単純型の派生

同等の単純型のJavaデータ型。

制限要素で使用されるファセット

シリアライゼーションおよびデシリアライゼーションで強制されないファセット。

<xsd:list>

リスト・データ型の配列。

wsdl:arrayType属性を使用した制限によってsoapenc:Arrayから派生する配列

arrayTypeデータ型と同等のJavaデータ型の配列。

制限によってsoapenc:Arrayから派生する配列

同等のJavaデータ型の配列。

単純型からの複合型の派生

_valueというプロパティのあるJavaBean。_valueの型は、この項の規則に従って単純型からマップされます。

<xsd:anyType>

java.lang.Object

<xsd:any>

javax.xml.soap.SOAPElementまたはorg.apache.xmlbeans.XmlObject

<xsd:any[]>

javax.xml.soap.SOAPElement[]またはorg.apache.xmlbeans.XmlObject[]

<xsd:union>

ユニオン・メンバーの共通の親タイプ。

<xsi:nil>および<xsd:nillable>属性

Javaのnull値。

XMLデータ型が組込みデータ型で通常はJavaプリミティブ・データ型(intやshortなど)にマップされる場合、そのXMLデータ型は実際には同等のオブジェクト・ラッパー型(java.lang.Integerやjava.lang.Shortなど)にマップされます。

複合型の派生

Javaの継承を使用してマップされます。

抽象型

抽象Javaデータ型。

サポートされるユーザー定義のJavaデータ型

次の表は、jwscおよびwsdlc Antタスクでサポートされるユーザー定義のJavaデータ型と、それぞれに対応するXMLスキーマ・データ型の一覧です。

表5-4 サポートされているユーザー定義のJavaデータ型

Javaデータ型

同等のXMLスキーマ・データ型

サポートされている任意のデータ型をプロパティとするJavaBean

JavaBeanプロパティに対応する要素の<xsd:sequence>をコンテンツ・モデルとする<xsd:complexType>。

サポートされるすべてのデータ型の配列および多次元配列(JavaBeanプロパティとして使用する場合)

maxOccurs属性がunboundedに設定されている<xsd:complexType>内の要素。

java.lang.Object

注意: 実行時オブジェクトのデータ型は既知の型である必要があります。

<xsd:anyType>

(org.apache.xmlbeans.XmlObjectからのみ継承されます) Apache XMLBeans

注意: Apache XMLBeansデータ型を戻り値の型またはパラメータとして使用するWebサービスは、document-literal-wrappedまたはdocument-literal-bareとして定義する必要があります。

Apache XMLBeans (http://xmlbeans.apache.org/index.html)を参照してください。

java.util.Collection

リテラル配列。

java.util.List

リテラル配列。

java.util.ArrayList

リテラル配列。

java.util.LinkedList

リテラル配列。

java.util.Vector

リテラル配列。

java.util.Stack

リテラル配列。

java.util.Set

リテラル配列。

java.util.TreeSet

リテラル配列。

java.utils.SortedSet

リテラル配列。

java.utils.HashSet

リテラル配列。

注意:
ユーザー定義のJavaデータ型であるJAX-RPCスタイルの列挙値クラスは、バージョン8.1ではWebLogic Webサービスのパラメータまたは戻り値として使用されていましたが、現在はサポートされていません。
また、パラメータまたは戻り値としてのジェネリックスの使用はサポートされていません。たとえば、以下のJavaメソッドはパブリックな操作として公開できません。

public ArrayList<String> echoGeneric(ArrayList<String> in) {
return in;
}

6 JAX-RPC Webサービス・クライアントの開発

この章では、Java API for XML-based RPC (JAX-RPC)を使用してWebLogic Webサービス・クライアントを開発する方法について説明します。

この章の内容は次のとおりです。

- JAX-RPC Webサービス・クライアントの概要

- Java SEクライアントからのWebサービスの呼出し

- 別のWebサービスからのWebサービスの呼出し

- Webサービス呼出し時のスタンドアロン・クライアントJARファイルの使用

- Webサービス呼出し時のプロキシ・サーバーの使用

- Webサービスを再デプロイする際にクライアント側で考慮すべき事項

- WebLogic Webサービスのスタブ・プロパティ

- レスポンスSOAPメッセージの文字エンコーディングの設定

注意:
次の項では、メッセージ保護されたWebサービスの呼出しについては説明していないため、メッセージ保護されたWebサービスの呼出しについては、『Oracle WebLogic Server WebLogic Webサービスの保護』の「クライアント・アプリケーションの更新によるメッセージ保護されたWebサービスの呼出し」を参照してください。

JAX-RPC Webサービス・クライアントの概要

Webサービスの起動とは、Webサービスを使用するためにクライアント・アプリケーションが実行する操作のことです。Webサービスを呼び出すクライアント・アプリケーションは、Java、Microsoft .NETなどの任意のテクノロジを使用して記述できます。

クライアント・アプリケーションには以下の2種類があります。

- Java SE クライアント - 最も単純な形式では、javaコマンドで呼び出すMainパブリック・クラスがあるJavaプログラムです。

- WebLogic ServerにデプロイされたJava EEコンポーネント - この種のクライアント・アプリケーションでは、EJB、サーブレット、または別のWebサービスなど、WebLogic ServerにデプロイされているJava Platform, Enterprise Edition (Java EE)バージョン5コンポーネント内でWebサービスが実行されます。したがって、WebLogic Serverコンテナの内部で実行されます。

(WebLogic Serverクラスパスへのアクセス権を使用して)WebLogic Serverで実行されているJava SEまたはJava EEアプリケーションからWebサービスを呼び出すことができます。WebLogic Serverのライブラリにアクセスできない環境で実行されているスタンドアロンJavaアプリケーションのサポートの詳細は、「Webサービス呼出し時のスタンドアロン・クライアントJARファイルの使用」を参照してください。

以降の項では、JAX-RPC仕様のOracleの実装を使用してJavaクライアント・アプリケーションからWebサービスを呼び出す方法について説明します。この実装を使用することで、WebLogicおよび非WebLogicにかかわらず任意のアプリケーション・サーバーで実行されているWebサービスを呼び出すことができます。さらに、WebLogic Serverの一部として実行されるクライアントまたはWebLogic Serverライブラリにアクセスできない環境で実行されるスタンドアロン・クライアントも作成できます。

この項で説明したコマンド・ライン・ツールの他に、Oracle JDeveloperなどのIDEもプロキシ生成とテストに使用できます。詳細は、『Oracle WebLogic Server WebLogic Webサービスの理解』のOracle IDEを使用したWebサービスの構築に関する項を参照してください。

注意:
ユーザー定義のデータ型をパラメータまたは戻り値として実装するWebサービス操作を、動的クライアントを使用して呼び出すことはできません。動的クライアントでは、JAX-RPCのCallインタフェースを使用するためです。標準の(静的)クライアントでは、JAX-RPCのServiceインタフェースおよびStubインタフェースを使用するため、ユーザー定義のデータ型を実装するWebサービスを正常に呼び出すことができます。

JAX-RPCを使用したWebサービスの呼出し

Java API for XML based RPC (JAX-RPC)は、Webサービスの呼出しに使用するAPIを定義する仕様です。WebLogic ServerはJAX-RPC仕様を実装しています。

次の表で、JAX-RPCの中心的なインタフェースとクラスを簡単に説明します。

表6-1 JAX-RPCのインタフェースとクラス

javax.xml.rpcのインタフェースまたはクラス

説明

Service

主要なクライアント・インタフェース。

ServiceFactory

Serviceインスタンスの生成に使用するファクトリ・クラス。

Stub

Webサービスの操作を呼び出すためのクライアント・プロキシのベース・クラス。

Call

Webサービスを動的に呼び出すのに使用します。

JAXRPCException

Webサービスの呼出し中にエラーが発生した場合にスローされる例外。

Webサービスを呼び出すクライアントの例

WebLogic ServerのORACLE_HOME\wlserver\samples\server\examples\src\examples\webservicesディレクトリには、必要に応じてWebLogic Webサービスの作成と呼出しのサンプルが含まれます(ORACLE_HOMEは、WebLogic Serverをインストールしたディレクトリです)。サンプルのビルドおよび実行方法の詳細は、ブラウザでWebページORACLE_HOME\wlserver\samples\server\docs\index.htmlを開いて「WebLogic Server Examples」→「Examples」→「API」→「Web Services」ノードを展開してください。詳細は、『Oracle WebLogic Serverの理解』のサンプル・アプリケーションおよびサンプル・コードに関する項を参照してください。

Java SEクライアントからのWebサービスの呼出し

注意:
この項で説明するように、WebLogic Serverで実行されている(WebLogic Serverクラスパスにアクセスする)任意のJava SEまたはJava EEアプリケーションからWebサービスを呼び出すことができます。WebLogic Serverのライブラリにアクセスできない環境で実行されているスタンドアロンJavaアプリケーションのサポートの詳細は、「Webサービス呼出し時のスタンドアロン・クライアントJARファイルの使用」を参照してください。

次の表は、Webサービスを呼び出すJava SEクライアントの作成の主な手順を示しています。

注意:
開発環境でのクライアント・アプリケーションのビルドやJavaファイルのコンパイルなどにAntを使用すること、およびWebサービスのクライアント・タスクで更新する必要のあるbuild.xmlファイルがすでに存在することを想定しています。開発環境でのAntの使用に関する一般情報は、「基本的なAnt build.xmlファイルの作成」を参照してください。この項で使用しているbuild.xmlファイルの完全な例は、「JavaクライアントのサンプルAntビルド・ファイル」を参照してください。

表6-2 Java SEクライアントからWebサービスを呼び出す手順

#

手順

説明

1

環境を設定します。

コマンド・ウィンドウを開いて、ドメイン・ディレクトリのbinサブディレクトリにあるsetDomainEnv.cmd (Windows)またはsetDomainEnv.sh (UNIX)コマンドを実行します。WebLogic Serverドメインのデフォルトの場所はORACLE_HOME/user_projects/domains/domainNameです(ORACLE_HOMEはOracle WebLogic Serverのインストール時にOracleホームとして指定したディレクトリ、domainNameはドメインの名前です)。

2

build.xmlファイルを更新して、Webサービスの呼出しに必要なクライアント側アーティファクトを生成するclientgen Antタスクが実行されるようにします。

「クライアントのアーティファクトを生成するためのclientgen Antタスクの使用」を参照してください。

3

Webサービスに関する情報(その操作のシグネチャ、ポートの名前など)を取得します。

「Webサービスに関する情報の取得」を参照してください。

4

Webサービス操作を呼び出すためのコードを含むクライアント・アプリケーションのJavaコードを記述します。

「Webサービスを呼び出すJavaクライアント・アプリケーション・コードの記述」を参照してください。

5

基本のAntビルド・ファイルbuild.xmlを作成します。

「基本的なAnt build.xmlファイルの作成」を参照してください。

6

Javaクライアント・アプリケーションをコンパイルし、実行します。

「クライアント・アプリケーションのコンパイルと実行」を参照してください。

クライアントのアーティファクトを生成するためのclientgen Antタスクの使用

clientgen WebLogic WebサービスAntタスクは、クライアント・アプリケーションがWebLogic Webサービスと非WebLogic Webサービスの両方の呼出しに使用できるクライアント・アーティファクトを既存のWSDLファイルから生成します。次のようなアーティファクトがあります。

- 呼出しの対象となる特定のWebサービスに対するJAX-RPC StubおよびServiceインタフェース実装のJavaクラス。

- WSDLファイルで指定されたユーザー定義XMLスキーマ・データ型のJavaクラス。

- Javaのユーザー定義のデータ型と、WSDLファイル内で指定されたそのデータ型に対応するXMLスキーマ型の間のマッピングに関する情報を格納するJAX-RPCマッピング・デプロイメント記述子ファイル。

- WSDLファイルのクライアント側のコピー。

clientgen Antタスクの詳細(使用可能なすべての属性など)は、『『Oracle WebLogic Server WebLogic Webサービス・リファレンス』』のAntタスク・リファレンスに関する項を参照してください。

次のサンプルのように、build.xmlファイルを更新してclientgen Antタスクに呼出しを追加します。

<taskdef name="clientgen"
classname="weblogic.wsee.tools.anttasks.ClientGenTask" />
<target name="build-client">
<clientgen
wsdl="http://${wls.hostname}:${wls.port}/complex/ComplexService?WSDL"
destDir="clientclasses"
packageName="examples.webservices.simple_client"
type="JAXRPC"/>
</target>

clientgen WebLogic WebサービスAntタスクを実行するには、その前にこのタスクの完全なJavaクラス名を標準のtaskdef Antタスクを使用して指定する必要があります。

クライアント側アーティファクトの作成に使用するWSDLファイルと、そうしたアーティファクトの生成先ディレクトリを指定するには、clientgen Antタスクのwsdl属性とdestDir属性を含める必要があります。packageName属性は省略できます。省略した場合、clientgenタスクではWSDLのtargetNamespaceに基づくパッケージ名が使用されます。typeも省略可能です。省略した場合のデフォルト値はJAXRPCです。

この例では、パッケージ名はクライアント・アプリケーションと同じパッケージ名examples.webservices.simple_clientに設定されます。パッケージ名をクライアント・アプリケーションとは異なる名前に設定した場合は、適切なクラス・ファイルをインポートする必要があります。たとえば、examples.webservices.complexというパッケージ名にした場合、クライアント・アプリケーションの以下のクラス・ファイルをインポートする必要があります。

import examples.webservices.complex.BasicStruct;
import examples.webservices.complex.ComplexPortType;
import examples.webservices.complex.ComplexService;

注意:
clientgen AntタスクのdestFile属性を使用すると、生成されたJavaファイルを自動的にコンパイルして、すべてのアーティファクトをJARファイルにパッケージ化できます。詳細と例については、『Oracle WebLogic Server WebLogic Webサービス・リファレンス』のclientgenに関する項を参照してください。

WSDLファイルで、Webサービス操作の入力パラメータまたは戻り値としてユーザー定義のデータ型が指定されている場合、clientgenはWSDLに定義されたXMLスキーマ・データ型のJava表現であるJavaBeanクラスを自動的に生成します。JavaBeanクラスは、destDirディレクトリに生成されます。

注意:
ユーザー定義のJavaデータ型のパッケージは、WSDLのデータ型のXMLスキーマに基づくもので、JAX-RPCスタブのパッケージ名とは異なります。

この手順で説明されている追加のターゲット(cleanなど)を含む、完全なサンプルbuild.xmlファイルについては、「JavaクライアントのサンプルAntビルド・ファイル」を参照してください。

clientgen Antタスクを他のサポートAntタスクと一緒に実行するには、コマンド・ラインでbuild-clientターゲットを指定します。

prompt> ant build-client

clientclassesディレクトリで、clientgen Antタスクによって生成されたファイルやアーティファクトを確認します。

Webサービスに関する情報の取得

操作を呼び出すJavaクライアント・アプリケーション・コードの記述に先立って、Webサービスの名前と操作のシグネチャを知る必要があります。この情報を調べるには様々な方法があります。

この情報を得るのに最適なのは、clientgen Antタスクを使用してWebサービス固有のJAX-RPCスタブを生成し、生成された*.javaファイルを調べる方法です。destDir属性で指定したディレクトリ内のpackageName属性の値に対応したサブディレクトリに生成されます。packageName属性が指定されていない場合、WSDLのtargetNamespaceに基づくパッケージに対応したサブディレクトリに生成されます。

- ServiceName.javaソース・ファイルには、Webサービスのポートを取得するためのgetPortName()メソッドが含まれており、ServiceNameはWebサービス名、PortNameはポート名を意味します。WebサービスがJWSファイルで実装されている場合、Webサービス名は@WebService JWSアノテーションのserviceName属性の値となり、ポート名は@WLHttpTransportアノテーションのportName属性の値となります。

- PortType.javaファイルには、Webサービスのパブリック操作に対応するメソッド・シグネチャが含まれており、PortTypeはWebサービスのポートの種類を表します。WebサービスがJWSファイルで実装されている場合、ポートの種類は@WebService JWSアノテーションのname属性の値となります。

Webサービスの実際のWSDLを調べることもできます。デプロイされているWebLogic WebサービスのWSDLの詳細は、「WebサービスのWSDLの参照」を参照してください。Webサービス名は、次のTraderService WSDLの引用に示すように、<service>要素内にあります。

<service name="TraderService">
<port name="TraderServicePort"
binding="tns:TraderServiceSoapBinding">
...
</port>
</service>

このWebサービス用に定義されている操作は、対応する<binding>要素の下に記述されています。たとえば次のWSDLの抜粋は、TraderService Webサービスにbuyとsellの2つの操作があることを示しています(わかりやすくするため、WSDLの関連部分のみを記載しています)。

<binding name="TraderServiceSoapBinding" ...>
...
<operation name="sell">
...
</operation>
<operation name="buy">
</operation>
</binding>

Webサービスを呼び出すJavaクライアント・アプリケーション・コードの記述

次のサンプル・コードでは、JavaアプリケーションがWebサービス操作を呼び出しています。このクライアント・アプリケーションは1つの引数(WebサービスのWSDL)を取ります。アプリケーションは次に標準JAX-RPC APIコードとclientgenによって生成されたServiceインタフェースのWebサービス固有の実装を使用して、Webサービスの操作を呼び出します。

この例では、ユーザー定義のデータ型(examples.webservices.complex.BasicStruct)を入力パラメータおよび戻り値として使用する操作を呼び出す方法も示します。clientgen Antタスクによって、このユーザー定義のデータ型のJavaコードが自動的に生成されます。

package examples.webservices.simple_client;
import java.rmi.RemoteException;
import javax.xml.rpc.ServiceException;
// import the BasicStruct class, used as a param and return value of the
// echoComplexType operation.  The class is generated automatically by
// the clientgen Ant task.
import examples.webservices.complex.BasicStruct;
/**
* This is a simple Java client application that invokes the
* the echoComplexType operation of the ComplexService web service.
*/
public class Main {
public static void main(String[] args)
throws ServiceException, RemoteException {
ComplexService service = new ComplexService_Impl (args[0] + "?WSDL" );
ComplexPortType port = service.getComplexServicePort();
BasicStruct in = new BasicStruct();
in.setIntValue(999);
in.setStringValue("Hello Struct");
BasicStruct result = port.echoComplexType(in);
System.out.println("echoComplexType called. Result: " + result.getIntValue() + ", " + result.getStringValue());
}
}

上記の例で注目すべき点は以下のとおりです。

- 次のコードは、ComplexPortTypeスタブを作成する方法を示します。

ComplexService service = new ComplexService_Impl (args[0] + "?WSDL");
ComplexPortType port = service.getComplexServicePort();

ComplexService_Implスタブ・ファクトリはJAX-RPCのServiceインタフェースを実装します。ComplexService_Implのコンストラクタは、指定されているWSDL URI (args[0] + "?WSDL")に基づいてスタブを作成します。getComplexServicePort()メソッドは、ComplexPortTypeスタブ実装のインスタンスを返すために使用します。

- 次のコードは、ComplexService WebサービスのechoComplexType操作を呼び出す方法を示します。

BasicStruct result = port.echoComplexType(in);

echoComplexType操作は、BasicStructというユーザー定義データ型を返します。

アプリケーションからWebサービス操作を呼び出すメソッドは、生成されたJAX-RPCスタブからスローされるjava.rmi.RemoteExceptionおよびjavax.xml.rpc.ServiceExceptionをスローまたは捕捉する必要があります。

クライアント・アプリケーションのコンパイルと実行

すべてのJavaファイル(クライアント・アプリケーションおよびclientgenによって生成されたファイルの両方)をクラス・ファイルにコンパイルするには、build.xmlファイルのbuild-clientターゲットにjavacタスクを追加します。該当箇所を次のサンプルに太字で示します。

<target name="build-client">
<clientgen
wsdl="http://${wls.hostname}:${wls.port}/complex/ComplexService?WSDL"
destDir="clientclasses"
packageName="examples.webservices.simple_client"
type="JAXRPC"/>
<javac
srcdir="clientclasses"
destdir="clientclasses"
includes="**/*.java"/>
<javac
srcdir="src"
destdir="clientclasses"
includes="examples/webservices/simple_client/*.java"/>
</target>

この例では、1番目のjavacタスクでclientgenによって生成されたclientclassesディレクトリ内のJavaファイルをコンパイルし、2番目のjavacタスクでカレント・ディレクトリのexamples/webservices/simple_clientサブディレクトリ(Javaクライアント・アプリケーションのソースの場所と想定されるディレクトリ)内にあるJavaファイルをコンパイルしています。

この例では、clientgenによって生成されたJavaソース・ファイルとコンパイル後のクラスが同じディレクトリ(clientclasses)に格納されます。プロトタイピングの段階ではこれで十分ですが、多くの場合はソース・コード(生成されたコードも含む)とコンパイルされたクラスを別々のディレクトリに格納するのがベスト・プラクティスです。これを行うには、両方のjavacタスクのdestdirに、srcdirディレクトリとは異なるディレクトリを設定します。また、clientgenによって生成された以下のファイルを、clientgenの出力先ディレクトリからjavacの出力先ディレクトリにコピーする必要もあります。その際、出力先のサブディレクトリの階層構造は同じになるようにします。

packageName/ServiceName_internaldd.xml
packageName/ServiceName_java_wsdl_mapping.xml
packageName/ServiceName_saved_wsdl.wsdl

packageNameは生成されたJAX-RPCスタブのパッケージに対応するサブディレクトリ階層構造、ServiceNameはWebサービスの名前です。

クライアント・アプリケーションを実行するには、javaタスクの呼出しを含むbuild.xmlにrunターゲットを追加します。次に例を示します。

<path id="client.class.path">
<pathelement path="clientclasses"/>
<pathelement path="${java.class.path}"/>
</path>
<target name="run" >
<java
fork="true"
classname="examples.webServices.simple_client.Main"
failonerror="true" >
<classpath refid="client.class.path"/>
<arg line="http://${wls.hostname}:${wls.port}/complex/ComplexService" />
</target>

pathタスクは、CLASSPATHにclientclassesディレクトリを追加します。runターゲットはMainアプリケーションを呼び出し、デプロイされたWebサービスのURLを1つの引数として渡します。

この手順で説明されている追加のターゲット(cleanなど)を含む、完全なサンプルbuild.xmlファイルについては、「JavaクライアントのサンプルAntビルド・ファイル」を参照してください。

アーティファクトを再生成してクラスに再コンパイルするためにbuild-clientターゲットを再実行してから、runターゲットを実行してechoStruct操作を呼び出します。

prompt> ant build-client run

build.xmlファイルのbuild-clientおよびrunターゲットを使用して、開発プロセスの一環としてJavaクライアント・アプリケーションを繰返し更新、再ビルド、および実行できます。

JavaクライアントのサンプルAntビルド・ファイル

次の例では、Javaクライアントを生成およびコンパイルするための完全なbuild.xmlファイルを示します。太字のセクションについては、「クライアントのアーティファクトを生成するためのclientgen Antタスクの使用」および「クライアント・アプリケーションのコンパイルと実行」を参照してください。

<project name="webservices-simple_client" default="all">
<!-- set global properties for this build -->
<property name="wls.hostname" value="localhost" />
<property name="wls.port" value="7001" />
<property name="example-output" value="output" />
<property name="clientclass-dir" value="${example-output}/clientclass" />
<path id="client.class.path">
<pathelement path="${clientclass-dir}"/>
<pathelement path="${java.class.path}"/>
</path>
<taskdef name="clientgen"
classname="weblogic.wsee.tools.anttasks.ClientGenTask" />
<target name="clean" >
<delete dir="${clientclass-dir}"/>
</target>
<target name="all" depends="clean,build-client,run" />
<target name="build-client">
<clientgen
wsdl="http://${wls.hostname}:${wls.port}/complex/ComplexService?WSDL"
destDir="${clientclass-dir}"
packageName="examples.webservices.simple_client"
type="JAXRPC"/>
<javac
srcdir="${clientclass-dir}" destdir="${clientclass-dir}"
includes="**/*.java"/>
<javac
srcdir="src" destdir="${clientclass-dir}"
includes="examples/webservices/simple_client/*.java"/>
</target>
<target name="run" >
<java fork="true"
classname="examples.webservices.simple_client.Main"
failonerror="true" >
<classpath refid="client.class.path"/>
<arg  line="http://${wls.hostname}:${wls.port}/complex/ComplexService"
/>
</java>
</target>
</project>

別のWebサービスからのWebサービスの呼出し

WebLogic Webサービス内からのWebサービスの呼出しは、「Java SEクライアントからのWebサービスの呼出し」で説明している、他のJavaアプリケーションからの呼出しと似ています。ただし、呼び出されるWebサービスのJAX-RPCスタブを生成するclientgen Antタスクを使用するのではなく、呼出し側のWebサービスをコンパイルするjwsc Antタスク内で、<jws>要素の<clientgen>子要素を使用します。一方、他のWebサービスを呼び出すJWSファイルでは、ServiceおよびPortTypeインスタンスの取得に同じ標準JAX-RPC APIを使用して、Webサービス操作を呼び出します。

「Java SEクライアントからのWebサービスの呼出し」をすでに読み、理解していることが前提となります。また、クライアント・アプリケーションのビルドやJavaファイルのコンパイルなどに開発環境でAntを使用していること、そして別のWebサービスを呼び出すために更新したいWebサービスをビルドするbuild.xmlファイルをすでに持っていることも前提となります。

クライアントWebサービスをビルドするbuild.xmlファイルに加える必要のある変更は次のとおりです(このクライアントWebサービスが別のWebサービスを呼び出すことになります)。build.xmlファイルの完全なサンプルについては、「Webサービス・クライアントのサンプルbuild.xmlファイル」を参照してください。

- JWSファイル(別のWebサービスを呼び出すWebサービスを実装しているもの)を指定する<jws>要素に、<clientgen>子要素が追加されます。呼び出されるWebサービスのWSDLに、必要なwsdl属性を設定します。JAX-RPCクライアント・スタブの生成先とするパッケージに、必要なpackageName属性を設定します。

クライアントWebサービスを実装するJWSファイルに加える必要のある変更は次のとおりです。JWSファイルの完全なサンプルについては、「Webサービスを呼び出すサンプルJWSファイル」を参照してください。

- jwsc Antタスクの<clientgen>子要素で生成される一連のファイルがインポートされます。これらには、呼び出されるWebサービスの操作でパラメータまたは戻り値として使用するユーザー定義データ型のJava表現だけでなく、呼び出されるWebサービスのJAX-RPCスタブも含まれます。

注意:
ユーザー定義のデータ型は、clientgenで指定されるパッケージ内ではなく、WSDLのXMLスキーマ・データ型に基づくパッケージ内に生成されます。ただし、JAX-RPCスタブでは<clientgen>要素のpackageName属性で指定されるパッケージ名が使用されます。

- Webサービスの呼出しを含むメソッドを、java.rmi.RemoteExceptionとjavax.xml.rpc.ServiceExceptionの両方をスローまたは捕捉するように更新します。

- JAX-RPCのServiceおよびPortTypeスタブ実装を取得して、通常どおりポート上で操作を呼び出します。詳細は、「Webサービスを呼び出すJavaクライアント・アプリケーション・コードの記述」を参照してください。

Webサービス・クライアントのサンプルbuild.xmlファイル

次のサンプルbuild.xmlファイルでは、別のWebサービスを呼び出すWebサービスを作成する方法を示します。別のWebサービスを呼び出さない単純なWebサービスをビルドするためのbuild.xmlと異なっている部分は、太字で示されています。

この場合のbuild-serviceターゲットは、単純なWebサービスをビルドするターゲットとよく似ています。唯一の違いは、呼び出すWebサービスをビルドするjwsc Antタスクに<jws>要素の<clientgen>子要素も含まれるという点で、これによってjwscでは必要なJAX-RPCクライアント・スタブも生成されるようになります。

<project name="webservices-service_to_service" default="all">
<!-- set global properties for this build -->
<property name="wls.username" value="weblogic" />
<property name="wls.password" value="weblogic" />
<property name="wls.hostname" value="localhost" />
<property name="wls.port" value="7001" />
<property name="wls.server.name" value="myserver" />
<property name="ear.deployed.name" value="ClientServiceEar" />
<property name="example-output" value="output" />
<property name="ear-dir" value="${example-output}/ClientServiceEar" />
<property name="clientclass-dir" value="${example-output}/clientclasses" />
<path id="client.class.path">
<pathelement path="${clientclass-dir}"/>
<pathelement path="${java.class.path}"/>
</path>
<taskdef name="jwsc"
classname="weblogic.wsee.tools.anttasks.JwscTask" />
<taskdef name="clientgen"
classname="weblogic.wsee.tools.anttasks.ClientGenTask" />
<taskdef name="wldeploy"
classname="weblogic.ant.taskdefs.management.WLDeploy"/>
<target name="all" depends="clean,build-service,deploy,client" />
<target name="clean" depends="undeploy">
<delete dir="${example-output}"/>
</target>
<target name="build-service">
<jwsc
srcdir="src"
destdir="${ear-dir}" >
<jws
file="examples/webservices/service_to_service/ClientServiceImpl.java"
type="JAXRPC">
<clientgen
wsdl="http://${wls.hostname}:${wls.port}/complex/ComplexService?WSDL"
packageName="examples.webservices.complex" />
</jws>
</jwsc>
</target>
<target name="deploy">
<wldeploy action="deploy" name="${ear.deployed.name}"
source="${ear-dir}" user="${wls.username}"
password="${wls.password}" verbose="true"
adminurl="t3://${wls.hostname}:${wls.port}"
targets="${wls.server.name}" />
</target>
<target name="undeploy">
<wldeploy action="undeploy" name="${ear.deployed.name}"
failonerror="false"
user="${wls.username}"
password="${wls.password}" verbose="true"
adminurl="t3://${wls.hostname}:${wls.port}"
targets="${wls.server.name}" />
</target>
<target name="client">
<clientgen
wsdl="http://${wls.hostname}:${wls.port}/ClientService/ClientService?WSDL"
destDir="${clientclass-dir}"
packageName="examples.webservices.service_to_service.client"
type="JAXRPC"/>
<javac
srcdir="${clientclass-dir}" destdir="${clientclass-dir}"
includes="**/*.java"/>
<javac
srcdir="src" destdir="${clientclass-dir}"
includes="examples/webservices/service_to_service/client/**/*.java"/>
</target>
<target name="run">
<java classname="examples.webservices.service_to_service.client.Main"
fork="true"
failonerror="true" >
<classpath refid="client.class.path"/>
<arg
line="http://${wls.hostname}:${wls.port}/ClientService/ClientService"/>
</java>
</target>
</project>

Webサービスを呼び出すサンプルJWSファイル

次に示すサンプルJWSファイル(ClientServiceImpl.java)は、ClientServiceというWebサービスを実装しており、このWebサービスに含まれている操作がComplexServiceというWebサービスのechoComplexType操作を呼び出します。この操作では、パラメータとしても戻り値としてもユーザー定義データ型(BasicStruct)を使用します。該当するコードを太字で示し、例の後で説明を加えます。

package examples.webservices.service_to_service;
import java.rmi.RemoteException;
import javax.xml.rpc.ServiceException;
import javax.jws.WebService;
import javax.jws.WebMethod;
import weblogic.jws.WLHttpTransport;
// Import the BasicStruct data type, generated by clientgen and used
// by the ComplexService Web Service
import examples.webservices.complex.BasicStruct;
// Import the JAX-RPC Stubs for invoking the ComplexService Web Service.
// Stubs generated by clientgen
import examples.webservices.service_to_service.ComplexPortType;
import examples.webservices.service_to_service.ComplexService_Impl;
import examples.webservices.service_to_service.ComplexService;
@WebService(name="ClientPortType", serviceName="ClientService",
targetNamespace="http://examples.org")
@WLHttpTransport(contextPath="ClientService", serviceUri="ClientService",
portName="ClientServicePort")
public class ClientServiceImpl {
@WebMethod()
public String callComplexService(BasicStruct input, String serviceUrl)
throws ServiceException, RemoteException
{
// Create service and port stubs to invoke ComplexService
ComplexService service = new ComplexService_Impl(serviceUrl + "?WSDL");
ComplexPortType port = service.getComplexServicePort();
// Create service and port stubs to invoke ComplexService
ComplexService service = new ComplexService_Impl(serviceUrl + "?WSDL");
ComplexPortType port = service.getComplexServicePortTypePort();
// Invoke the echoComplexType operation of ComplexService
BasicStruct result = port.echoComplexType(input);
System.out.println("Invoked ComplexPortType.echoComplexType." );
return "Invoke went okay!  Here's the result: '" + result.getIntValue() + ",  " + result.getStringValue() + "'";
}
}

別のWebサービスを呼び出すJWSファイルをプログラミングする際は、次のガイドラインに従います。ガイドラインのサンプル・コードは、上述のサンプル内では太字で示されています。

- 呼び出されるWebサービスで使用されるユーザー定義データ型をインポートします。このサンプルでは、ComplexServiceでBasicStruct JavaBeanを使用しています。

import examples.webservices.complex.BasicStruct;

- ComplexService WebサービスのJAX-RPCスタブをインポートします。このスタブは、<jws>の<cliengen>子要素によって生成されます。

import examples.webservices.service_to_service.ComplexPortType;
import examples.webservices.service_to_service.ComplexService_Impl;
import examples.webservices.service_to_service.ComplexService;

- クライアントWebサービスがServiceExceptionおよびRemoteExceptionをスローまたは捕捉するようにします。

throws ServiceException, RemoteException

- ComplexServiceのJAX-RPC ServiceおよびPortTypeインスタンスを作成します。

ComplexService service = new
ComplexService_Impl(serviceUrl + "?WSDL");
ComplexPortType port = service.getComplexServicePortTypePort();

- ComplexServiceのechoComplexType操作を、直前にインスタンス化したポートを使用して呼び出します。

BasicStruct result = port.echoComplexType(input);

Webサービス呼出し時のスタンドアロン・クライアントJARファイルの使用

このドキュメントでは、clientgenまたはwsdlc Antタスクによって生成されたクライアント側アーティファクトを使用してWebサービスを呼び出す場合に、WebLogic Serverクラス全体がCLASSPATHに指定されていることを前提としています。ただし、ご使用のコンピュータにWebLogic Serverがインストールされていない場合でも、この項で説明するようにスタンドアロンのWebLogic Webサービス・クライアントJARファイルを使用することで、Webサービスを呼び出すことができます。

スタンドアロン・クライアントJARファイルは、次のような基本的なクライアント側の機能をサポートしています。

- clientgen Antタスクの双方によって作成されるクライアント側アーティファクトでの使用

- SOAPメッセージの処理

- クライアント側のSOAPメッセージ・ハンドラの使用

- MTOMの使用

- JAX-RPC Webサービスの呼出し

- SSLの使用

ただし、スタンドアロン・クライアントJARファイルは、次の高度な機能を使用するWebサービスの呼出しはサポートしていません。

- Webサービスの信頼性のあるSOAPメッセージング

- メッセージ・レベルのセキュリティ(WS-Security)

- 会話

- 非同期の要求/応答

- バッファリング

- JMSトランスポート

スタンドアロンのWebLogic Webサービス・クライアントJARファイルをクライアント・アプリケーションで使用するには、次の手順に従います。

1. ファイルORACLE_HOME/wlserver/modules/clients/com.oracle.webservices.wls.jaxrpc-client.jarを、WebLogic Serverをホストするコンピュータからクライアント・コンピュータにコピーします(ORACLE_HOMEはOracle WebLogic Serverのインストール時にOracleホームとして指定したディレクトリ、domainNameはドメインの名前です)。

2. JARファイルをCLASSPATHに追加します。

注意:
JARファイルでクラスのサブセットが必要になるため、Antクラスを含むJARファイル(ant.jar)が確実にCLASSPATHに格納されるようにしてください。このJARファイルは通常、Antディストリビューションのlibディレクトリ内にあります。

Webサービス呼出し時のプロキシ・サーバーの使用

プロキシ・サーバーを使用すると、クライアント・アプリケーションから、呼び出されるWebサービスをホストするアプリケーション・サーバー(WebLogic、非WebLogicいずれでも)へのリクエストをプロキシできます。通常、プロキシ・サーバーは、アプリケーション・サーバーがファイアウォールの内側にある場合に使用します。クライアント・アプリケーションでプロキシ・サーバーを指定するには、WebLogic HttpTransportInfo APIでプログラム的に行う方法と、システム・プロパティを使用する方法の2つがあります。

HttpTransportInfo APIを使用したプロキシ・サーバーの指定

標準のjava.net.*クラスとWebLogic固有のHttpTransportInfo APIを使用することにより、Webサービスの呼出しをプロキシするプロキシ・サーバーの詳細を、Javaクライアント・アプリケーション自体の中でプログラム的に指定できます。java.netクラスを使用して、プロキシ・サーバーを示すProxyオブジェクトを作成し、次にWebLogic APIとプロパティを使用してJAX-RPCスタブ上でプロキシ・サーバーを設定します(HttpProxySampleService Webサービスのecho操作を呼び出す次のサンプル・クライアントを参照)。太字で示したコードについては、例の後で説明します。

package dev2dev.proxy.client;
import java.net.Proxy;
import java.net.InetSocketAddress;
import weblogic.wsee.connection.transport.http.HttpTransportInfo;
/**
* Sample client to invoke a service through a proxy server via
* programmatic API
*/
public class HttpProxySampleClient {
public static void main(String[] args) throws Throwable{
assert args.length == 5;
String endpoint = args[0];
String proxyHost = args[1];
String proxyPort = args[2];
String user = args[3];
String pass = args[4];
//create service and port
HttpProxySampleService service = new HttpProxySampleService_Impl();
HttpProxySamplePortType port = service.getHttpProxySamplePortTypeSoapPort();
//set endpoint address
((Stub)port)._setProperty(Stub.ENDPOINT_ADDRESS_PROPERTY, endpoint);
//set proxy server info
Proxy p = new Proxy(Proxy.Type.HTTP, new  InetSocketAddress(proxyHost, Integer.parseInt(proxyPort)));
HttpTransportInfo info = new HttpTransportInfo();
info.setProxy(p);
((Stub)port)._setProperty("weblogic.wsee.connection.transportinfo",info);
//set proxy-authentication info
((Stub)port)._setProperty("weblogic.webservice.client.proxyusername",user);
((Stub)port)._setProperty("weblogic.webservice.client.proxypassword",pass);
//invoke
String s = port.echo("Hello World!");
System.out.println("echo: " + s);
}
}

上記の例のうち、留意すべきセクションは、次のとおりです。

- 必要なjava.net.*クラスのインポート。

import java.net.Proxy;
import java.net.InetSocketAddress;

- WebLogic HttpTransportInfo APIのインポート。

import weblogic.wsee.connection.transport.http.HttpTransportInfo;

- プロキシ・サーバーを表すProxyオブジェクトの作成。

Proxy p = new Proxy(Proxy.Type.HTTP, new  InetSocketAddress(proxyHost, Integer.parseInt(proxyPort)));

引数proxyHostおよびproxyPortは、プロキシ・サーバーのホスト・コンピュータおよびポートを表します。

- HttpTransportInfoオブジェクトを作成し、setProxy()メソッドを使用してプロキシ・サーバー情報を設定します。

HttpTransportInfo info = new HttpTransportInfo();
info.setProxy(p);

- weblogic.wsee.connection.transportinfo WebLogicスタブ・プロパティを使用して、JAX-RPCスタブ上でHttpTransportInfoオブジェクトを設定します。

((Stub)port)._setProperty("weblogic.wsee.connection.transportinfo",info);

- WebLogic固有のスタブ・プロパティweblogic.webservice.client.proxyusernameおよびweblogic.webservice.client.proxypasswordを使用して、プロキシ・サーバーへのアクセスが認証されているユーザーのユーザー名とパスワードを指定します。

((Stub)port)._setProperty("weblogic.webservice.client.proxyusername",user);
((Stub)port)._setProperty("weblogic.webservice.client.proxypassword",pass);

別の方法としては、次の例に示すように、HttpTransportInfo APIのsetProxyUsername()およびsetProxyPassword()メソッドを使用してプロキシ・ユーザー名とパスワードを設定することもできます。

info.setProxyUsername("juliet".getBytes());
info.setProxyPassword("secret".getBytes());

システム・プロパティを使用したプロキシ・サーバーの指定

プロキシ・サーバーの指定にシステム・プロパティを使用するには、クライアント・アプリケーションの記述は標準的な方式で行い、クライアント・アプリケーションの実行時にシステム・プロパティを指定します。

Javaの標準的なシステム・プロパティを使用するか、またはWebLogicの履歴プロパティを使用できます。proxySet systemプロパティがfalseに設定される場合(proxySet=false)、プロキシ・プロパティが無視され、プロキシは使用されません。

次の表に、Javaシステム・プロパティをまとめます。その場合は、proxySetのシステム・プロパティを設定することはできません。

表6-3 Javaシステム・プロパティを使用したプロキシ・サーバーの指定

プロパティ

説明

http.proxyHost=proxyHost

または

https.proxyHost=proxyHost

プロキシ・サーバー が動作しているホスト・コンピュータ名。HTTP over SSLに対してhttps.proxyHostを使用します。

http.proxyPort=proxyPort

または

https.proxy.Port=proxyPort

プロキシ・サーバーがリスニングしているポート。HTTP over SSLに対してhttps.proxyPortを使用します。

http.nonProxyHosts=

hostname|hostname|...

プロキシをバイパスし、直接アクセスするホストのリスト。各ホスト名を「|」文字で区切ります。このプロパティはHTTPおよびHTTPSの両方に適用されます。

以下のAntビルド・スクリプトの抜粋では、clients.InvokeMyServiceというクライアント・アプリケーションを呼び出す場合のJavaシステム・プロパティの設定例を示します。

<target name="run-client">
<java fork="true"
classname="clients.InvokeMyService"
failonerror="true">
<classpath refid="client.class.path"/>
<arg line="${http-endpoint}"/>
<jvmarg line=
"-Dhttp.proxyHost=${proxy-host}
-Dhttp.proxyPort=${proxy-port}
-Dhttp.nonProxyHosts=${mydomain}"
/>
</java>
</target>

次の表に、WebLogicシステム・プロパティの概要を示します。この場合、proxySetシステム・プロパティをtrueに設定する必要があります。

表6-4 プロキシ・サーバーの指定に使用するWebLogicシステム・プロパティ

プロパティ

説明

proxySet=true

歴史的なWebLogicプロキシ・プロパティを使用することを指定するフラグ。

proxyHost=proxyHost

プロキシ・サーバー が動作しているホスト・コンピュータ名。

proxyPort=proxyPort

プロキシ・サーバーがリスニングしているポート。

weblogic.webservice.client.proxyusername=username

プロキシ・サーバーにアクセスするために使用するユーザー名。

weblogic.webservice.client.proxypassword=password

プロキシ・サーバーにアクセスするために使用するパスワード。

以下のAntビルド・スクリプトの抜粋では、clients.InvokeMyServiceというクライアント・アプリケーションを呼び出す場合のWebLogicシステム・プロパティの設定例を示します。

<target name="run-client">
<java fork="true"
classname="clients.InvokeMyService"
failonerror="true">
<classpath refid="client.class.path"/>
<arg line="${http-endpoint}"/>
<jvmarg line=
"-DproxySet=true
-DproxyHost=${proxy-host}
-DproxyPort=${proxy-port}
-Dweblogic.webservice.client.proxyusername=${proxy-username}
-Dweblogic.webservice.client.proxypassword=${proxy-passwd}"
/>
</java>
</target>

Webサービスを再デプロイする際にクライアント側で考慮すべき事項

WebLogic Serverでは本番再デプロイメントをサポートしています。つまり、更新後の新しいバージョンのWebLogic Webサービスを同じWebサービスの古いバージョンと並行してデプロイできます。

WebLogic Serverでは、新しいクライアントのリクエストのみが新しいバージョンに転送されるように、クライアント接続が自動的に管理されます。再デプロイメント時にすでにWebサービスに接続していたクライアントは、作業が完了するまで古いバージョンのサービスを使用し続け、それらの作業が完了した時点で、WebLogic Serverが古いWebサービスを自動的にリタイアします。クライアントが会話形式のWebサービスまたは信頼性のあるWebサービスに接続している場合、既存の会話シーケンスまたは信頼性のあるメッセージングのシーケンスがクライアントによって明示的に終了されるか、タイムアウトになったときに、クライアントの作業が完了したとみなされます。

Webサービスの新しいバージョンで次のWebサービス・アーティファクトが変更されていなければ、その新しいバージョンで古いクライアント・アプリケーションを引き続き使用できます。

- Webサービスを記述するWSDL

- Webサービスに添付されたWS-Policyファイル

上記のアーティファクトのいずれかが変更されている場合、clientgen Antタスクを再び実行して、クライアント・アプリケーションで使用されるJAX-RPCスタブを再生成する必要があります。

たとえば、Webサービスの新しいバージョンで操作のシグネチャを変更すると、Webサービスの新しいバージョンを記述するWSDLファイルも変更されます。この場合、JAX-RPCスタブを再生成する必要があります。ただし、単に操作の実装のみを変更し、操作のパブリック・コントラクトは変更しない場合、既存のクライアント・アプリケーションを引続き使用できます。

WebLogic Webサービスのスタブ・プロパティ

WebLogic Serverには、WebLogic Webサービスの呼出しに使用するJAX-RPCスタブに対して設定できる一連のスタブ・プロパティが用意されています。プロパティの設定には、次の例のようにStub._setProperty()メソッドを使用します。

((Stub)port)._setProperty(WLStub.MARSHAL_FORCE_INCLUDE_XSI_TYPE,"true");

ほとんどのスタブ・プロパティはWLStubクラスに定義されています。

WLStubクラスに定義されていない付加的なスタブ・プロパティについては、以下の表で説明します。

表6-5 付加的なスタブ・プロパティ

スタブ・プロパティ

説明

weblogic.wsee.transport.connection.timeout

Webサービスの呼出しを試行しているクライアント・アプリケーションが接続を待機する時間(ミリ秒単位)を指定します。指定した時間が経過しても接続が確立していない場合、その試行はタイムアウトになります。

weblogic.wsee.transport.read.timeout

クライアント・アプリケーションが呼び出しているWebサービスからのレスポンスを待機する時間(ミリ秒単位)を指定します。指定した時間が経過してもレスポンスが到着していない場合、そのクライアントはタイムアウトになります。

weblogic.wsee.security.bst.serverVerifyCert

クライアント・アプリケーションがWebLogic Serverからの署名されたレスポンスの検証に使用する証明書を指定します。デフォルトでは、検証に使用される証明書がSOAPレスポンス・メッセージ自体に格納されます。これが不可能な場合に、このスタブ・プロパティを使用して、別の証明書を指定します。

このスタブ・プロパティは、WebLogic Serverコンテナの内部で実行されるクライアント・アプリケーションのみに適用され、スタンドアロンのクライアント・アプリケーションには適用されません。

このプロパティの値は、java.security.cert.X509Certificateデータ型のオブジェクト。

weblogic.wsee.security.bst.serverEncryptCert

クライアント・アプリケーションが、WebLogic Serverに送信されるSOAPリクエスト・メッセージの暗号化に使用する証明書を指定します。デフォルトでは、クライアント・アプリケーションはWebサービスのWSDLでパブリッシュされているパブリック証明書を使用します。これが不可能な場合に、このスタブ・プロパティを使用して、別の証明書を指定します。

このスタブ・プロパティは、WebLogic Serverコンテナの内部で実行されるクライアント・アプリケーションのみに適用され、スタンドアロンのクライアント・アプリケーションには適用されません。

このプロパティの値は、java.security.cert.X509Certificateデータ型のオブジェクト。

weblogic.wsee.marshal.forceIncludeXsiType

Webサービス操作呼出しのSOAPメッセージに、各パラメータのXMLスキーマ・データ型を含める必要があることを指定します。デフォルトでは、各パラメータのデータ型はSOAPメッセージには含まれません。

次に例を示すように、このプロパティをTrueに設定すると、操作パラメータを記述するSOAPメッセージ内の要素に、パラメータのデータ型を指定するためのxsi:type属性が追加されます。

<soapenv:Envelope>
...
<maxResults xsi:type="xs:int">10</maxResults>
...

デフォルトでは(または、このプロパティをFalseに設定した場合は)、このパラメータ要素は次の例のようになります。

<soapenv:Envelope>
...
<maxResults>10</maxResults>
...

このプロパティの有効な値は、TrueおよびFalseです。デフォルト値はFalseです。

レスポンスSOAPメッセージの文字エンコーディングの設定

レスポンス(発信) SOAPメッセージの文字エンコーディングを設定するには、weblogic.wsee.jaxrpc.WLStub.CHARACTER_SET_ENCODING WLStubプロパティを使用します。設定できる値は次の2つです。

- UTF-8

- UTF-16

クライアント・アプリケーションからの以下の抜粋コードでは、文字エンコーディングをUTF-16に設定する方法を示します。

Simple port = service.getSimpleSoapPort();
((Stub) port)._setProperty(weblogic.wsee.jaxrpc.WLStub.CHARACTER_SET_ENCODING, "UTF-16");
port.invokeMethod();

第III部

JAX-RPC Webサービスの高度な機能の開発

第II部では、Java API for XML-based RPC (JAX-RPC)を使用してWebLogic Webサービスの高度な機能を開発する方法について説明します。

ここで説明するトピックは次のとおりです。

- 第7章「非同期リクエスト-レスポンスを使用したWebサービスの呼出し」

- 第8章「Webサービスの信頼性のあるメッセージングの使用」

- 第9章「会話型Webサービスの作成」

- 第10章「バッファ付きWebサービスの作成」

- 第11章「非同期機能の併用」

- 第12章「コールバックによるクライアントへのイベントの通知」

- 第13章「接続プロトコルとしてのJMSトランスポートの使用」

- 第14章「SOAPメッセージ・ハンドラの作成と使用」

- 第15章「Database Webサービスの使用」

7 非同期リクエスト-レスポンスを使用したWebサービスの呼出し

この章では、非同期リクエスト-レスポンスを使用してWebLogic Java API for XML-based RPC (JAX-RPC) Webサービスを呼び出す方法について説明します。

この章の内容は次のとおりです。

- 非同期リクエスト-レスポンス機能の概要

- 非同期リクエスト-レスポンスの使用: 主な手順

- 非同期WebサービスのホストWebLogic Serverインスタンスの構成

- 非同期のJWSファイルの記述

- 非同期リクエスト-レスポンスを使用する場合のbuild.xmlファイルの更新

- 内部非同期サービスの無効化

- 非同期のリクエスト・レスポンスとプロキシ・サーバーの使用

非同期リクエスト-レスポンス機能の概要

Webサービスを同期的に呼び出す場合、呼出し側のクライアント・アプリケーションは、レスポンスが戻るまで待機してから、処理を続行します。レスポンスが即座に戻る場合であれば、このWebサービス呼出しの方法は適切であると考えられます。しかし、リクエストの処理が遅延する可能性があるため、クライアント・アプリケーションによる処理を続行しレスポンスへの対処は後で行うようにする、すなわち、WebLogic Webサービスにおける非同期リクエスト-レスポンス機能を使用すると便利なことがよくあります。

Webサービスの非同期的な呼出しは、WebLogic Webサービスで実行されているクライアントからのみ行います。スタンドアロンのクライアント・アプリケーションから行うことはありません。呼び出されたWebサービスは、まったく変更されません。したがって、Webサービスをホストするアプリケーション・サーバーがhttp://www.w3.org/Submission/2004/SUBM-ws-addressing-20040810/にあるWS-Addressing仕様をサポートしているかぎり、任意のデプロイ済Webサービス(WebLogicおよび非WebLogicの両方)を非同期的に呼び出せます。

クライアントに非同期リクエスト-レスポンスを実装するには、操作を直接呼び出すのではなく、非同期な種類の同じ操作を呼び出します。(この非同期な種類の操作は、jwsc Antタスクによって自動生成されます。)たとえば、getQuoteという操作を直接呼び出すのではなく、getQuoteAsyncを呼び出します。非同期な種類の操作は、オリジナルの操作が値を戻す場合でも、常にvoidを戻します。そのため、クライアントには、非同期のレスポンスまたは障害が後で戻されたときにそれを処理するメソッドを組み込みます。これらのメソッド内には、Webサービス操作呼出しに対する戻り値、または潜在的な障害を処理するビジネス・ロジックを置きます。これらのメソッドをJWSコンパイラに対して指定するには、ネーミング・ルールとJWSアノテーションの双方を使用します。たとえば、非同期操作がgetQuoteAsyncである場合、これらのメソッドはonGetQuoteAsyncResponseおよびonGetQuoteAsyncFailureになります。

注意:
Webサービスの信頼性のあるメッセージングやバッファリングなどの他の非同期機能とともに非同期リクエスト-レスポンスを使用する場合については、第11章「非同期機能の併用」を参照してください。本項では、非同期リクエスト-レスポンス機能を単独で使用する方法について説明します。
非同期リクエスト-レスポンス機能は、HTTPでのみ動作します。HTTPSまたはJMSトランスポートでは使用できません。

非同期リクエスト-レスポンスの使用: 主な手順

次の手順では、他のWebサービス内に非同期的に操作を呼び出すクライアントWebサービスの作成方法を説明します。この手順では、クライアントWebサービスを実装するJWSファイルをゼロから作成する方法を示しています。既存のJWSファイルを更新する場合は、この手順をガイドとして利用してください。

わかりやすくするために、この手順では以下を想定しています。

- クライアントWebサービスの名前はStockQuoteClientServiceです。

- StockQuoteClientServiceサービスは、WSDLが次のURLにある、デプロイ済みのStockQuoteServiceサービスのgetQuote(String)操作を呼び出します。

http://localhost:7001/async/StockQuote?WSDL

さらに、Antベースの開発環境を設定済であり、かつjwsc Antタスクを実行して生成されたサービスをデプロイするためのターゲットを追加できる、作業用のbuild.xmlファイルがあることが前提となっています。詳細は、次の項を参照してください。

- 「JAX-RPC Webサービス開発者向けサンプル」

- 「JAX-RPC Webサービスの開発」

- JWSファイルのプログラミング

- 「JAX-RPC Webサービス・クライアントの開発」

表7-1 非同期リクエスト-レスポンスを使用する手順

#

手順

説明

1

WebLogic Serverインスタンスを構成します。

「非同期WebサービスのホストWebLogic Serverインスタンスの構成」の説明に従って、非同期のレスポンス・サービスを構成します。

2

StockQuoteClientService Webサービスを実装する、新しいJWSファイルを作成するか、既存のJWSファイルを更新します。

使い慣れたIDEまたはテキスト・エディタを使用します。「非同期のJWSファイルの記述」を参照してください。

3

build.xmlファイルを更新して、StockQuoteClientServiceを実装するJWSファイルがコンパイルされるようにします。

jwsc Antタスクに<clientgen>子要素を追加することによって、呼び出している非同期な種類のWebサービス操作が自動的に生成されます。

「非同期リクエスト-レスポンスを使用する場合のbuild.xmlファイルの更新」を参照してください。

4

Antターゲットを実行して、StockQuoteClientServiceをビルドします。

例:

prompt> ant build-clientService

5

StockQuoteClientService Webサービスを通常どおりデプロイします。

「WebLogic Webサービスのデプロイとアンデプロイ」を参照してください。

StockQuoteClientService Webサービスを呼び出すと、そのWebサービスがStockQuoteService Webサービスを呼び出します。この2回目の呼出しは、同期ではなく非同期のものになります。

非同期WebサービスのホストWebLogic Serverインスタンスの構成

非同期Webサービスのデプロイ先となるWebLogic Serverインスタンスを構成する際には、Webサービスのランタイムで内部的に使用される、JMSサーバーやモジュールなどのJMSリソースを構成します。

これらのリソースは手作業でも構成できますが、構成ウィザードで、Webサービス固有の拡張テンプレートを使用してWebLogic Serverドメインを拡張することもできます。構成ウィザードを使用すると、必要な構成手順を大幅に簡素化できます。詳細は、「Webサービス機能用のドメイン構成」を参照してください。

注意:
または、WLSTを使用してリソースを構成できます。WLSTを使用したドメインの拡張の詳細は、『WebLogic Scripting Toolの理解』の既存ドメインの構成に関する項を参照してください。
Webサービスのリソースを含まないドメインは、Webサービス以外のシナリオおよび非同期のリクエスト/レスポンスが含まれないWebサービス・シナリオにおいて、適切に起動および実行されます。ただし、サーバー・ログに、非同期リソースが構成されていないこと、およびWebサービスの非同期レスポンス・サービスが完全にデプロイされていないことを示すINFOメッセージが表示されます。

リソースを手作業で構成する場合、以下の手順を実行します。

表7-2 非同期WebサービスのホストWebLogic Serverインスタンスを手作業で構成する手順

#

手順

説明

1

ホストWebLogic Serverインスタンスが格納されたドメインのWebLogic Server管理コンソールを起動します。

ブラウザでWebLogic Server管理コンソールを起動するには、次のURLを入力します。

http://host:port/console

各要素の説明は次のとおりです。

- hostは、管理サーバーが動作しているコンピュータを指します。

- portは、管理サーバーが接続リクエストをリスニングしているポート番号を指します。管理サーバーのデフォルトのポート番号は7001です。

『Oracle WebLogic Server WebLogic Webサービスの理解』の管理コンソールの起動に関する項を参照してください。

2

JMSサーバーを作成します。

JMSサーバーを作成します。JMSサーバーがすでに存在する場合は、新しいJMSサーバーを作成せずにそれを使用できます。

Oracle WebLogic Server管理コンソール・オンライン・ヘルプのJMSサーバーの作成に関する項を参照してください。

3

JMSモジュールを作成し、キューを定義します。

JMSモジュールを作成し、その中にJMSキューを定義します。JMSモジュールがすでに存在する場合は、新しいJMSモジュールを作成せずにそれを使用することもできます。JMSキューを、1つ前の手順で作成したJMSサーバーにターゲット指定します。このJMSキューがローカルであることを必ず指定してください(通常は、ローカルJNDI名の設定により指定できます)。Oracle WebLogic Server管理コンソール・オンライン・ヘルプのJMSシステム・モジュールの作成に関する項とシステム・モジュールのキューの作成に関する項を参照してください。

非同期WebサービスでデフォルトWebサービスのキューを使用する場合は、JMSキューのJNDI名をweblogic.wsee.DefaultQueueに設定します。

クラスタ化の考慮事項:

クラスタ内でWebサービスの非同期機能を使用する場合は、次の作業を行う必要があります。

- JMSキューの作成時に、分散キューではなくローカルJMSキューを作成します。

- このJMSキューをクラスタ内の各サーバーに明示的にターゲット指定します。

4

ワーク・マネージャを作成します。

weblogic.wsee.mdb.DispatchPolicyという名前でワーク・マネージャを定義します。これは、デフォルトで非同期リクエスト-レスポンス機能で使用されます。

Oracle WebLogic Server管理コンソール・オンライン・ヘルプのグローバル・ワーク・マネージャの作成に関する項を参照してください。

5

必要に応じて、現在のドメイン環境をチューニングする(オプション)

『Oracle WebLogic Serverのパフォーマンスのチューニング』の負荷が高いシステムのチューニングによるWebサービスのパフォーマンス向上に関する項を参照してください。

非同期のJWSファイルの記述

次の例では、StockQuoteClientというWebサービスを実装する簡単なJWSファイルを示します。このWebサービスには、asyncOperationという単一のメソッドがあり、これが非同期的に、StockQuoteサービスのgetQuoteメソッドを呼び出します。太字で示されたJavaコードについては、「Webサービスの非同期な呼出しのコーディングに関するガイドライン」で説明します。この非同期呼出しが、同じ操作の同期呼出しとどう違うのかについては、「同期呼出しのサンプル」を参照してください。

package examples.webservices.async_req_res;

import weblogic.jws.WLHttpTransport;
import weblogic.jws.ServiceClient;
import weblogic.jws.AsyncResponse;
import weblogic.jws.AsyncFailure;

import weblogic.wsee.async.AsyncPreCallContext;
import weblogic.wsee.async.AsyncCallContextFactory;
import weblogic.wsee.async.AsyncPostCallContext;

import javax.jws.WebService;
import javax.jws.WebMethod;

import examples.webservices.async_req_res.StockQuotePortType;

import java.rmi.RemoteException;

@WebService(name="StockQuoteClientPortType",
serviceName="StockQuoteClientService",
targetNamespace="http://examples.org/")

@WLHttpTransport(contextPath="asyncClient",
serviceUri="StockQuoteClient",
portName="StockQuoteClientServicePort")

/**
*  Client Web Service that invokes the StockQuote Service asynchronously.
*/

public class StockQuoteClientImpl {

@ServiceClient(wsdlLocation="http://localhost:7001/async/StockQuote?WSDL",
serviceName="StockQuoteService", portName="StockQuote")

private StockQuotePortType port;

@WebMethod
public void asyncOperation (String symbol, String userName)
throws RemoteException {

AsyncPreCallContext apc = AsyncCallContextFactory.getAsyncPreCallContext();
apc.setProperty("userName", userName);

try {
port.getQuoteAsync(apc, symbol );
System.out.println("in getQuote method of StockQuoteClient WS");

} catch (RemoteException re) {

System.out.println("RemoteException thrown");
throw new RuntimeException(re);
}

}

@AsyncResponse(target="port", operation="getQuote")
public void onGetQuoteAsyncResponse(AsyncPostCallContext apc, int quote) {
// Get the userName property we set on AsyncPreCallContext
String userName = (String)apc.getProperty("userName");
System.out.println("-------------------");
System.out.println(username + " Got quote " + quote );
System.out.println("-------------------");
}

@AsyncFailure(target="port", operation="getQuote")
public void onGetQuoteAsyncFailure(AsyncPostCallContext apc, Throwable e) {
System.out.println("-------------------");
e.printStackTrace();
System.out.println("-------------------");
}

}

Webサービスの非同期な呼出しのコーディングに関するガイドライン

操作を非同期的に呼び出すための以下のガイドラインは、「非同期のJWSファイルの記述」に記載のサンプルにおいて太字で示したJavaコードに対応しています。これらのガイドラインは、JWSファイル作成のための標準的なガイドラインへの付け加えです。この非同期呼出しが、同じ操作の同期呼出しとどう違うのかについては、「同期呼出しのサンプル」を参照してください。

JWSファイルで操作の非同期呼出しを行う方法は次のとおりです。

- 非同期リクエスト-レスポンス機能に関連する、次のWebLogic固有のJWSアノテーションをインポートします。

import weblogic.jws.ServiceClient;
import weblogic.jws.AsyncResponse;
import weblogic.jws.AsyncFailure;

- 呼び出すWebサービスのポート・タイプのJAX-RPCスタブをインポートします。このスタブは、jwsc Antタスクによって後から作成されます。スタブ・パッケージは、jwscの子要素<clientgen>のpackageName属性によって指定され、スタブの名前は呼び出されたWebサービスのWSDLによって決まります。

import examples.webservices.async_req_res.StockQuotePortType;

- 非同期の呼出し前および呼出し後におけるコンテキストWebLogic APIをインポートします。

import weblogic.wsee.async.AsyncCallContextFactory;
import weblogic.wsee.async.AsyncPreCallContext;
import weblogic.wsee.async.AsyncPostCallContext;

非同期の呼出し前および呼出し後におけるコンテキストの詳細は、「非同期の呼出し前および呼出し後におけるコンテキストの使用」を参照してください。

- JWSファイルの本文で、必要な@ServiceClient JWSアノテーションを使用して、非同期に呼び出すWebサービスのWSDL、名前およびポートを指定します。このアノテーションは、変数のフィールド・レベルで指定します。この変数のデータ型は、呼び出しているWebサービスのJAX-RPCポート・タイプとなります。

@ServiceClient(
wsdlLocation="http://localhost:7001/async/StockQuote?WSDL",
serviceName="StockQuoteService",
portName="StockQuote")

private StockQuotePortType port;

@ServiceClientアノテーションで変数(この場合はport)をアノテーション付きにする場合、Webサービス・ランタイムはその変数を自動的に初期化およびインスタンス化し、別のWebサービスの非同期呼出しに使用できるようにします。

- getQuote操作を非同期に呼び出すJWSファイルのメソッドで、コンテキスト・ファクトリを使用して、呼出し前の非同期コンテキストを取得します。

AsyncPreCallContext apc =
AsyncCallContextFactory.getAsyncPreCallContext();

非同期の呼出し前および呼出し後におけるコンテキストの詳細は、「非同期の呼出し前および呼出し後におけるコンテキストの使用」を参照してください。

- 呼出し前コンテキストのsetPropertyメソッドを使用して、ユーザー名を格納するプロパティを作成します。

apc.setProperty("userName", userName);

- @ServiceClientアノテーションを付けたスタブを使用して、操作(この場合はgetQuote)を呼び出します。ただし、直接呼び出すのではなく、その操作の名前の末尾にAsyncが追加された、非同期のものを呼び出します。非同期の種類の操作は、常にvoidを返します。非同期のコンテキストを最初のパラメータとして渡します。

port.getQuoteAsync(apc, symbol);

- 非同期に呼び出す各操作について、onOperationnameAsyncResponseというメソッドを作成します。Operationnameは操作名で、最初の1文字は常に大文字です。メソッドは、voidを返さなければならず、呼出し後の非同期コンテキストおよび呼び出している操作の戻り値という、2つのパラメータを備えていることが必要です。@AsyncResponse JWSアノテーションでメソッドをアノテーション付きにします。データ型がJAX-RPCスタブである変数を指定するにはtarget属性を使用し、非同期に呼び出している操作の名前を指定するにはoperation属性を使用します。メソッドの本文の中に、操作によって返された値を処理するビジネス・ロジックを入れます。呼出し後コンテキストのgetPropertyメソッドを使用して、非同期メソッドを呼び出す前に呼出し前コンテキストで設定したプロパティを取得します。

@AsyncResponse(target="port", operation="getQuote")
public void onGetQuoteAsyncResponse(AsyncPostCallContext apc,
int quote) {
// Get the userName property we set on AsyncPreCallContext
String userName = (String)apc.getProperty("userName");
System.out.println("-------------------");
System.out.println("Got quote " + quote );
System.out.println("-------------------");
}

非同期の呼出し前および呼出し後におけるコンテキストの詳細は、「非同期の呼出し前および呼出し後におけるコンテキストの使用」を参照してください。

- 非同期に呼び出す各操作について、onOperationnameAsyncFailureというメソッドを作成します。Operationnameは操作名で、最初の1文字は大文字です。メソッドはvoidを返さなければならず、呼出し後の非同期コンテキスト、および呼び出された操作がスローするすべての種類の例外を処理するすべての例外のスーパークラスであるThrowableオブジェクトという、2つのパラメータを備えていることが必要です。@AsyncFailure JWSアノテーションでメソッドをアノテーション付きにします。データ型がJAX-RPCスタブである変数を指定するにはtarget属性を使用し、非同期に呼び出している操作の名前を指定するにはoperation属性を使用します。メソッド内では、例外の性質を正確に判断し、適切なJavaコードを記述することができます。

@AsyncFailure(target="port", operation="getQuote")
public void onGetQuoteAsyncFailure(AsyncPostCallContext apc,
Throwable e) {
System.out.println("-------------------");
e.printStackTrace();
System.out.println("-------------------");
}

注意:
@AsyncResponseアノテーションおよび@AsyncFailureアノテーションの使用は、曖昧な点がすべて明瞭化されJWSファイルが明確かつ理解しやすいものになるため推奨されますが、必須ではありません。ただし、onXXXメソッドの1つで、同じ名前を持つ別々の2つのWebサービスから操作を呼び出している2つ(またはそれ以上)のスタブからの非同期レスポンスまたは障害を処理する場合は、これらのアノテーションの使用を明示的に避ける必要があります。onXXXメソッドの名前は必ず、前述の正しいネーミング・ルールに厳密に準拠するようにしてください。

非同期の呼出し前および呼出し後におけるコンテキストの使用

AsyncPreCallContextおよびAsyncPostCallContextの各APIは、様々な理由によりWebサービスでの使用が可能な非同期のコンテキストを記述します。例:

- 非同期レスポンスを処理するメソッドがそれぞれの非同期呼出しを見分けられるようコンテキストの前にプロパティを設定する

- 操作を呼び出しているユーザーの名前、パスワードなどのコンテキスト変数を取得および設定する

- メソッドを非同期的に呼び出したJAX-RPCスタブの名前を取得する、およびコンテキストのタイムアウト間隔を設定する

非同期の呼出し前および呼出し後におけるコンテキストを使用するには:

1. 非同期の呼出し前および呼出し後におけるコンテキストWebLogic APIをインポートします。

import weblogic.wsee.async.AsyncCallContextFactory;
import weblogic.wsee.async.AsyncPreCallContext;
import weblogic.wsee.async.AsyncPostCallContext;

2. 非同期操作を呼び出すJWSファイルのメソッドで、コンテキスト・ファクトリを使用して呼出し前の非同期コンテキストを取得します。例:

AsyncPreCallContext apc =
AsyncCallContextFactory.getAsyncPreCallContext();

3. 呼出し前コンテキストのメソッドを使用して、非同期メソッドが呼び出される前に非同期コンテキストに対して処理します。次の例は、呼出し前コンテキストのsetPropertyメソッドを使用して、ユーザー名を格納するプロパティを作成します。

apc.setProperty("userName", userName);

4. 呼出し後コンテキストのメソッドを使用して、非同期メソッドが呼び出された後で非同期コンテキストに対して処理します。次の例は、呼出し後コンテキストのgetPropertyメソッドを使用して、非同期メソッドを呼び出す前に呼出し前コンテキストで設定したプロパティを取得します。

String userName = (String)apc.getProperty("userName");

同期呼出しのサンプル

次のサンプルでは、StockQuote WebサービスのgetQuote操作を同期的に呼び出すJWSファイルを示します。このサンプルは、「非同期のJWSファイルの記述」に示した、対応する非同期呼出しとの比較目的でのみ示されています。

package examples.webservices.async_req_res;

import weblogic.jws.WLHttpTransport;
import weblogic.jws.ServiceClient;

import javax.jws.WebService;
import javax.jws.WebMethod;

import java.rmi.RemoteException;

@WebService(name="SyncClientPortType",
serviceName="SyncClientService",
targetNamespace="http://examples.org/")

@WLHttpTransport(contextPath="syncClient",
serviceUri="SyncClient",
portName="SyncClientPort")

/**
*  Normal service-to-service client that invokes StockQuote service
*  synchronously.
*/

public class SyncClientImpl {

@ServiceClient(wsdlLocation="http://localhost:7001/async/StockQuote?WSDL",
serviceName="StockQuoteService", portName="StockQuote")
private StockQuotePortType port;

@WebMethod
public void nonAsyncOperation(String symbol) throws RemoteException {

int quote = port.getQuote(symbol);

System.out.println("-------------------");
System.out.println("Got quote " + quote );
System.out.println("-------------------");

}

}

非同期リクエスト-レスポンスを使用する場合のbuild.xmlファイルの更新

build.xmlファイルを更新して、Webサービス操作を非同期的に呼び出すJWSファイルを生成するには、次のようなtaskdefsおよびbuild-clientServiceターゲットを追加します。詳細は、サンプルの後の説明を参照してください。

<taskdef name="jwsc"
classname="weblogic.wsee.tools.anttasks.JwscTask" />

<target name="build-clientService">

<jwsc
enableAsyncService="true"
srcdir="src"
destdir="${clientService-ear-dir}" >

<jws file="examples/webservices/async_req_res/StockQuoteClientImpl.java" >

<clientgen
wsdl="http://${wls.hostname}:${wls.port}/async/StockQuote?WSDL"
packageName="examples.webservices.async_req_res"/>

</jws>

</jwsc>

</target>

jwsc Antタスクの完全なクラス名を定義するには、taskdef Antタスクを使用します。

クライアントWebサービスをコンパイルするjwsc Antタスクを更新して、<jws>要素の<clientgen>子要素を含めます。これにより、デプロイされたStockQuote WebサービスのJAX-RPCスタブが生成およびコンパイルされるようになります。jwsc Antタスクでは、これらのスタブが生成されたWARファイルに自動的にパッケージ化されるため、即座にクライアントWebサービスからアクセスできるようになります。この場合のデフォルトでは、jwsc AntタスクはJAX-RPCスタブ内にWebサービス操作の同期した種類のものと非同期な種類のものを両方とも生成します。このようにするのは、生成されたクラスの1つをStockQuoteClientImpl JWSファイルでインポートして使用するためです。

内部非同期サービスの無効化

デフォルトでは、すべてのWebLogic Serverインスタンスに、非同期リクエスト-レスポンス機能を処理する内部非同期Webサービスがデプロイされます。この内部サービスがデプロイされないようにするには、-Dweblogic.wsee.skip.async.response=true Javaシステム・プロパティを使用してWebLogic Serverインスタンスを起動します。

非同期サービスを無効にするケースとしては、WebLogic ServerインスタンスをWebLogicクラスタへのWebプロキシとして使用する場合が考えられます。この場合、クラスタ宛に非同期メッセージが送信されても、プロキシ・サーバー上の非同期サービスによって消費されてしまうためクラスタには届きません。このような理由から、プロキシ・サーバー上の非同期サービスは、上記のシステム・プロパティを使用して無効にする必要があります。

Javaシステム・プロパティを指定してWebLogic Serverを構成する方法の詳細は、『Oracle WebLogic Serverサーバーの起動と停止の管理』のWebLogic ServerインスタンスのJavaオプションの指定に関する項を参照してください。

非同期のリクエスト・レスポンスとプロキシ・サーバーの使用

非同期のリクエスト・レスポンス機能を使用するクライアント・アプリケーションでは、操作を直接呼び出さず、プロキシ・サーバーを使用する場合があります。プロキシを使用する理由としては、ファイアウォールの存在や、呼び出されたWebサービスのクラスタへのデプロイメントなどがあります。

この場合、呼び出されたWebサービスをホストするWebLogic Serverインスタンスは、プロキシ・サーバーのアドレスとポートで構成する必要があります。Webサービスがクラスタにデプロイされている場合は、そのクラスタ内のすべてのサーバーを構成することが必要です。

この手順では、ネットワーク接続を管理するための構成可能なWebLogic Serverの主要リソースであるネットワーク・チャネルの作成方法について説明します。ネットワーク・チャネルにより、クラスタのフロントエンド・アドレスにアクセスするための一貫性のある方法を提供できます。ネットワーク・チャネルの詳細は、『Oracle WebLogic Serverサーバー環境の管理』のネットワーク・チャネルの理解に関する項を参照してください。

各サーバー・インスタンスについて、以下の手順を実行します。

1. Webサービスの呼出しに使用するプロトコル用のネットワーク・チャネルを作成します。ネットワーク・チャネルの名前は、weblogic-wsee-proxy-channel-XXXとする必要があります(XXXはプロトコルを表します)。たとえば、HTTPS用のネットワーク・チャネルを作成する場合、weblogic-wsee-proxy-channel-httpsという名前にします。
ネットワーク・チャネルの作成に関する一般情報は、Oracle WebLogic Server管理コンソール・オンライン・ヘルプのカスタム・ネットワーク・チャネルの構成に関する項を参照してください。

2. 「外部リスニング・アドレス」および「外部リスニング・ポート」フィールドを、それぞれプロキシ・サーバーのアドレスおよびポートで更新して、ネットワーク・チャネルを構成します。

8 Webサービスの信頼性のあるメッセージングの使用

この章では、WebLogic Java API for XML-based RPC (JAX-RPC) WebサービスにおけるWebサービスの信頼性のあるメッセージングについて説明します。

この章の内容は次のとおりです。

- Webサービスの信頼性のあるメッセージングの概要

- Webサービスの信頼性のあるメッセージングの使用: 主な手順

- 宛先WebLogic Serverインスタンスの構成

- ソースWebLogic Serverインスタンスの構成

- Webサービスの信頼性のあるメッセージングのWS-Policyファイルの作成

- 信頼性のあるJWSファイルに関するプログラミングのガイドライン

- 信頼性のあるWebサービスの信頼性のあるメッセージングの構成

- 信頼性のあるWebサービスを呼び出すJWSファイルに関するプログラミングのガイドライン

- 信頼性のあるWebサービスのクライアント用build.xmlファイルの更新

- 信頼性のあるメッセージングとMTOMの使用

- 信頼性のあるWebサービスを再デプロイする際にクライアント側で考慮すべき事項

- 信頼性のあるメッセージングとプロキシ・サーバーの使用

注意:
Webサービスの信頼性のあるメッセージングでは、WebLogic Webサービスの非同期リクエスト-レスポンス機能を使用する必要があります。先に進む前に、第7章「非同期リクエスト-レスポンスを使用したWebサービスの呼出し」で説明する概念を理解してください。

Webサービスの信頼性のあるメッセージングの概要

Webサービスの信頼性のあるメッセージングとは、ある1つのアプリケーション・サーバーで実行中のアプリケーションが、別のアプリケーション・サーバーで実行中のWebサービスを確実に呼び出せるフレームワークです。ここでは、双方のサーバーでWS-ReliableMessaging仕様が実装されていることが前提となっています。「信頼性がある」とは、ソフトウェア・コンポーネント、システム、またはネットワークに障害があっても、2つのWebサービス間でメッセージ配信を保証できる状態として定義されます。

注意:
Webサービスの信頼性のあるメッセージングは、WS-ReliableMessaging仕様(http://docs.oasis-open.org/ws-rx/wsrm/200702/wsrm-1.1-spec-os-01.pdf)が実装された任意の2つのアプリケーション・サーバー間で機能します。ただし、このドキュメントでは、この2つのアプリケーション・サーバーがWebLogic Serverインスタンスであると想定しています。
Webサービスの信頼性のあるメッセージングは、JMSトランスポート機能ではサポートされません。

WebLogic Webサービスは、http://docs.oasis-open.org/ws-rx/wsrm/200702/wsrm-1.1-spec-os-01.pdfにあるWS-ReliableMessaging仕様(2007年6月)に準拠しています。この仕様では、別々のアプリケーション・サーバーで実行されている2つのWebサービスが確実に通信できる方法について記述されています。具体的には、この仕様ではソース・エンドポイント(つまりクライアントWebサービス)から宛先エンドポイント(つまり操作を確実に呼び出せるWebサービス)へ送信されるメッセージが、1つ以上の配信保証に基づいて確実に配信されるか、そうでなければ必ずエラーが発生する、相互運用性を備えたプロトコルについて説明されています。

信頼性のあるWebLogic Webサービスには、次の配信保証が備わっています。

表8-1 信頼性のあるメッセージングの配信保証

配信保証

説明

At Most Once

メッセージは最大で1回、重複なしに配信されます。メッセージによっては、一度も配信されない可能性もあります。

At Least Once

すべてのメッセージが、少なくとも1回、配信されます。メッセージによっては、1回よりも多く配信される可能性があります。

Exactly Once

すべてのメッセージが、必ず1回重複なしに配信されます。

In Order

メッセージは、送信された順序で配信されます。この配信保証は、上記の3つの保証と組み合せることも可能です。

注意:
Webサービスの信頼性のあるメッセージングでは、非同期メッセージを使用する必要があります。クライアントが信頼性のあるサービスを同期的に呼び出すことはできません。信頼性のあるスタブ・メソッドを呼び出す際には、xyz()ではなくxyzAsync()のような非同期署名を必ず使用してください。SOAPメッセージを直接作成するクライアントのために、非匿名のReplyToアドレスを使用してリクエスト・メッセージを作成します。
ReplyToを匿名URIに設定することはできません。JAX-RPCベースの信頼性のあるサービス操作を呼び出そうとすると(同期スタブ署名を呼び出すか、匿名のReplyToを使用してリクエストを送信することにより)、実行時例外がスローされます。

ここでは、信頼性のあるクライアントWebサービスを作成し、そのWebサービスがデプロイされる2つのWebLogic Serverインスタンスを構成する方法について説明します。Webサービスの信頼性のあるメッセージングのアーキテクチャの詳細は、WS-ReliableMessaging仕様を参照してください(http://docs.oasis-open.org/ws-rx/wsrm/200702/wsrm-1.1-spec-os-01.pdfを参照)。

WS-Policyを使用した信頼性のあるメッセージング・ポリシーのアサーションの指定

WebLogic Webサービスでは、宛先エンドポイントがWebサービスの信頼性のあるメッセージングの機能と要件を記述および公開できるように、WS-Policyファイルを使用します。WS-Policyファイルは、サポートされているWS-ReliableMessaging仕様のバージョンやサービス品質の要件などが記述されたXMLファイルです。WS-Policy仕様(http://www.w3.org/TR/ws-policy/)では、Webサービスのポリシーを記述して通信するための、汎用的なモデルと構文が提供されています。

WebLogic Serverには、標準的な信頼性のあるメッセージング・アサーションを含むあらかじめパッケージ化されているWS-Policyファイルがあります(付録A「信頼性のあるメッセージング用にパッケージ化されているWS-Policyファイル」を参照)。あらかじめパッケージ化されているWS-Policyファイルがニーズに合わない場合は、独自のWS-Policyファイルを作成する必要があります。詳細は、「Webサービスの信頼性のあるメッセージングのWS-Policyファイルの作成」を参照してください。信頼性のあるメッセージングのポリシー・アサーションに関するリファレンス情報は、『Oracle WebLogic Server WebLogic Webサービス・リファレンス』のWebサービスの信頼性のあるメッセージングのポリシー・アサーションに関するリファレンスの項を参照してください。

信頼性のあるメッセージ・シーケンスのライフサイクルの管理

次の図に、信頼性のあるメッセージの一方向の交換を示します。

図8-1 Webサービスの信頼性のあるメッセージの交換

信頼性のあるメッセージ・シーケンスは、RM送信元とRM宛先の間で確実に交換されるメッセージ・セットの進捗状況を追跡する際に使用されます。シーケンスは、0個以上のメッセージの送信に使用でき、文字列識別子で識別されます。この識別子は、信頼性のあるメッセージングを使用する際に、そのシーケンスを参照するために使用されます。

Webサービス・クライアント・アプリケーションは、RM送信元がRM宛先へ送信する信頼性のある配信のメッセージを送信します。RM宛先は、信頼性のあるメッセージを受信したことを確認応答し、そのメッセージをWebサービス・アプリケーションに配信します。RM送信元は、確認応答を受け取るまでメッセージを再送信できます。

Webサービス・クライアントは、JAX-RPCスタブに対するメソッドの呼出しを行い、ターゲットWebサービスへメッセージを送信します。スタブは、信頼性のあるWebサービスのポート・タイプに関連付けられており、そのWebサービスのプログラム的なインタフェースを表します。WebLogicでは、このスタブ内に、信頼性のあるメッセージ・シーケンスの識別子が格納されます。これによって、信頼性のあるメッセージ・シーケンスが単一のJAX-RPCスタブに接続されます。特定のスタブを使用して送信されるすべてのメッセージは、そのメッセージの数に関係なく、同じ信頼性のあるメッセージ・シーケンスを使用します。JAX-RPCスタブは、jwsc Antタスクの子要素<clientgenによって作成されます。

WebLogic Serverは信頼性のあるシーケンスと関連付けられたリソースを保持するので、適切なタイミングでこれらのリソースを解放することをお薦めします。WebLogic Serverには、Webサービスの信頼性のあるメッセージングで使用できるユーティリティ・クラスweblogic.wsee.reliability.WsrmUtilsがあります。このクラスを使用すると、構成オプションの設定、シーケンスIDの取得、信頼性のあるシーケンスの終了といった一般的なタスクを実行できます。

通常の状況では、すべてのメッセージが送信され、RM宛先によって確認応答されるまで、信頼性のあるシーケンスを保持する必要があります。シーケンスの適切な終了を容易にするため、信頼性のあるメッセージ・シーケンスの最後のメッセージを識別することをお薦めします。これにより、RM宛先へのメッセージの送信が完了したことがわかり、WebLogic Serverは信頼性のあるシーケンスを自動的に終了する前に最後の確認応答の検索を開始できます。最終メッセージは、weblogic.wsee.reliability.WsrmUtils.setFinalMessage()メソッドを使用し、メッセージの送信に使用されているJAX-RPCスタブをRM宛先に渡して示します。

最後のメッセージを識別すると、最後のメッセージまでのすべてのメッセージが確認応答され、信頼性のあるメッセージ・シーケンスが終了し、すべてのリソースが開放されます。そうでない場合、シーケンスは、構成したシーケンスの有効期限に達した後で自動的に終了します。

これは推奨されませんが、terminateSequence()メソッドを使用すると、すべてのメッセージが確認応答されているかどうかに関係なく、信頼性のあるメッセージ・シーケンスを終了できます。このメソッドを発行すると、このスタブ上で信頼性のあるメッセージをそれ以降送信することはできません。

注意:
JAX-RPCスタブは、最初のメソッドが信頼性のあるWebサービスに対して呼び出された直後まで完全に初期化されません。最初のメソッドが呼び出されると、RM送信元はCreateSequenceメッセージをRM宛先へ送信し、信頼性のあるシーケンスを作成および登録するようRM宛先にリクエストします。その後、RM宛先は新たに作成されたシーケンスについて、そのIDで応答します。RM送信元は、このレスポンスIDを受信するまでRM宛先と通信できず、RM宛先のターゲット・サービスを表すJAX-RPCスタブは使用できません。
信頼性のあるメッセージ・シーケンスに対しては、そのシーケンスが完全に初期化されるまで操作を行うことはできません。信頼性のあるメッセージ・シーケンスが初期化されているかどうかをモニターするには、weblogic.wsee.reliability.WsrmUtils.waitForSequenceInitialization()メソッドを使用します。このメソッドは、信頼性のあるシーケンスが初期化されると、そのシーケンスのIDを返します。

Webサービスの信頼性のあるメッセージングの使用: 主な手順

WebLogic Webサービスの信頼性のあるメッセージングを構成するには、JMSサーバーやストア・アンド・フォワード(SAF)・エージェントの作成など標準的なJMSタスクとともに、JWSファイルへのJWSアノテーションの追加などWebサービス固有のタスクを実行する必要があります。また、あらかじめパッケージ化されているファイルを使用しない場合は、必要に応じて、信頼性のあるWebサービスの信頼性のあるメッセージング機能を記述したWS-Policyファイルをユーザー側で作成します。

信頼性のあるWebサービスの呼出しにWebLogicクライアントAPIを使用している場合、クライアント・アプリケーションはWebLogic Server上で実行される必要があります。したがって構成タスクは、信頼性のあるWebサービスを確実に呼び出すクライアント・コードを含むWebサービスがデプロイされたソースWebLogic Serverインスタンスと、信頼性のあるWebサービスそのものがデプロイされた宛先WebLogic Serverインスタンスの双方で実行される必要があります。

次の表では、信頼性のあるWebサービスと、その操作を呼び出すクライアントWebサービスを作成する手順を説明しています。この手順では、2つのWebサービスを実装するJWSファイルをゼロから作成する方法を示しています。既存のJWSファイルを更新する場合は、この手順をガイドとして利用してください。またこの手順では、ソースWebLogic Serverインスタンスと宛先WebLogic Serverインスタンスの構成方法も示しています。

表8-2 信頼性のあるWebサービスの作成および呼出しの手順

#

手順

説明

1

宛先WebLogic ServerインスタンスとソースWebLogic Serverインスタンスを構成します。

信頼性のあるWebサービスを宛先WebLogic Serverインスタンスにデプロイします。宛先WebLogic Serverインスタンスの構成については、「宛先WebLogic Serverインスタンスの構成」を参照してください。

信頼性のあるWebサービスを呼び出すクライアントWebサービスを、ソースWebLogic Serverインスタンスにデプロイします。ソースWebLogic Serverインスタンスの構成については、「ソースWebLogic Serverインスタンスの構成」を参照してください。

2

WS-Policyファイルを作成する(オプション)

任意のXMLまたはプレーン・テキスト・エディタを使用し、必要に応じて宛先WebLogic Server上で実行されているWebサービスの信頼性のあるメッセージング機能が記述されたWS-Policyファイルを作成します。独自のWS-Policyファイルを作成する方法の詳細は、「Webサービスの信頼性のあるメッセージングのWS-Policyファイルの作成」を参照してください。

WebLogic Serverに付属しているいずれかのWS-Policyファイルを使用する場合、この手順は不要です。詳細については、付録A「信頼性のあるメッセージングためのあらかじめパッケージ化されているWS-Policyファイル」を参照してください。

3

信頼性のあるWebサービスを実装するJWSファイルを作成および更新します。

このWebサービスは、宛先WebLogic Serverインスタンスにデプロイされます。「信頼性のあるJWSファイルに関するプログラミングのガイドライン」を参照してください。

4

信頼性のあるWebサービスのコンパイルに使用されるbuild.xmlファイルを更新します。

build.xmlファイルを更新して、信頼性のあるJWSファイルをWebサービスにコンパイルするjwsc Antタスクの呼出しを含めます。

jwscタスクの使用についての一般情報は、「jwsc WebLogic WebサービスAntタスクの実行」を参照してください。

5

信頼性のあるJWSファイルをコンパイルおよびデプロイします。

適切なターゲットを呼び出して信頼性のあるJWSファイルをコンパイルし、宛先WebLogic Serverにデプロイします。例:

prompt> ant build-mainService deploy-mainService

6

信頼性のあるWebサービスを構成します。

WebLogic Server管理コンソールを使用して、信頼性のあるWebサービスの信頼性のあるメッセージング・オプションを構成します。「信頼性のあるWebサービスの信頼性のあるメッセージングの構成」を参照してください。

7

クライアントWebサービスを実装するJWSファイルを作成および更新します。

このサービスは、信頼性のあるWebサービスを呼び出し、ソースWebLogic Serverにデプロイされます。「信頼性のあるWebサービスを呼び出すJWSファイルに関するプログラミングのガイドライン」を参照してください。

8

クライアントWebサービスのコンパイルに使用されるbuild.xmlファイルを更新します。

「信頼性のあるWebサービスのクライアント用build.xmlファイルの更新」を参照してください。

9

クライアントJWSファイルをコンパイルおよびデプロイします。

適切なターゲットを呼び出してクライアントJWSファイルをコンパイルし、ソースWebLogic Serverにデプロイします。例:

prompt> ant build-clientService deploy-clientService

以降の項では、これらの各手順について詳細に説明します。

また、以下の高度なトピックについて説明します。

- 信頼性のあるメッセージングとMTOMの使用 - MTOM/XOPを使用し、SOAPメッセージのxs:base64Binary型のXMLデータの送信を最適化する、信頼性のあるWebサービスを開発します

- 信頼性のあるWebサービスを再デプロイする際にクライアント側で考慮すべき事項 - 信頼性のある更新済WebLogic Webサービスの新しいバージョンを、同じWebサービスの古いバージョンと一緒にデプロイする際に、クライアント側で考慮すべき事項について説明します。

- 信頼性のあるメッセージングとプロキシ・サーバーの使用 - プロキシ・サーバーを使用して信頼性のあるWebサービス操作を呼び出す際の考慮事項について説明します。

前提条件

以下の作業を完了している必要があります。

- 宛先と送信元のWebLogic Serverインスタンスを作成しておきます。

- 各環境でのAntベースの開発環境の設定

- 編集(jwsc Antタスクを実行して信頼性のある生成済Webサービスをデプロイするためのターゲットの追加など)が可能な作業用のbuild.xmlファイルの用意。

詳細は、『JAX-RPC Webサービスの開発』を参照してください。

宛先WebLogic Serverインスタンスの構成

信頼性のあるWebサービスがデプロイされるWebLogic Serverインスタンスを構成するには、JMSおよびストア・アンド・フォワード(SAF)・リソースを構成します。

これらのリソースは手作業でも構成できますが、構成ウィザードで、Webサービス固有の拡張テンプレートを使用してWebLogic Serverドメインを拡張することもできます。構成ウィザードを使用すると、必要な構成手順を大幅に簡素化できます。詳細は、「Webサービス機能用のドメイン構成」を参照してください。

注意:
または、WLSTを使用してリソースを構成できます。WLSTを使用したドメインの拡張の詳細は、『WebLogic Scripting Toolの理解』の既存ドメインの構成に関する項を参照してください。
Webサービスのリソースを含まないドメインは、Webサービス以外のシナリオおよび非同期のリクエスト/レスポンスが含まれないWebサービス・シナリオにおいて、適切に起動および実行されます。ただし、サーバー・ログに、非同期リソースが構成されていないこと、およびWebサービスの非同期レスポンス・サービスが完全にデプロイされていないことを示すINFOメッセージが表示されます。

リソースを手作業で構成する場合、以下の手順を実行します。

表8-3 宛先WebLogic Serverインスタンスを手作業で構成する手順

#

手順

説明

1

宛先WebLogic Serverが格納されたドメインのWebLogic Server管理コンソールを起動します。

ブラウザでWebLogic Server管理コンソールを起動するには、次のURLを入力します。

http://host:port/console

各要素の説明は次のとおりです。

- hostは、管理サーバーが動作しているコンピュータを指します。

- portは、管理サーバーが接続リクエストをリスニングしているポート番号を指します。管理サーバーのデフォルトのポート番号は7001です。

『Oracle WebLogic Server WebLogic Webサービスの理解』の管理コンソールの起動に関する項を参照してください。

2

永続ファイル・ストアを作成する(オプション)

必要に応じて、宛先WebLogic ServerがWebサービスの信頼性のあるメッセージングの内部情報を格納するために使用する永続ストア(ファイルまたはJDBC)を作成します。新規作成しない場合は、既存のものを使用するか、常に存在するデフォルトのストアを使用できます。

Oracle WebLogic Server管理コンソール・オンライン・ヘルプのファイル・ストアの作成に関する項を参照してください。

3

JMSサーバーを作成します。

JMSサーバーを作成します。JMSサーバーがすでに存在する場合は、新しいJMSサーバーを作成せずにそれを使用できます。

Oracle WebLogic Server管理コンソール・オンライン・ヘルプのJMSサーバーの作成に関する項を参照してください。

4

JMSモジュールを作成し、キューを定義します。

JMSモジュールを作成し、その中にJMSキューを定義します。JMSモジュールがすでに存在する場合は、新しいJMSモジュールを作成せずにそれを使用することもできます。JMSキューを、1つ前の手順で作成したJMSサーバーにターゲット指定します。このJMSキューがローカルであることを必ず指定してください(通常は、ローカルJNDI名の設定により指定できます)。

後で信頼性のあるWebサービスを実装するJWSファイルをプログラムする際に使用するため、JMSキュー用に定義したJNDI名は覚えておく必要があります。

Oracle WebLogic Server管理コンソール・オンライン・ヘルプのJMSシステム・モジュールの作成に関する項とシステム・モジュールのキューの作成に関する項を参照してください。

クラスタ化の考慮事項:

クラスタ内でWebサービスの信頼性のあるメッセージング機能を使用する場合は、次の作業を行う必要があります。

- JMSキューの作成時に、分散キューではなくローカルJMSキューを作成します。

- このJMSキューをクラスタ内の各サーバーに明示的にターゲット指定します。

5

ストア・アンド・フォワード(SAF)エージェントを作成します。

新規作成しない場合は、既存のものを使用できます。

SAFエージェントを作成する場合は、次の作業を行います。

- 「エージェントの種類」フィールドを「両方」に設定して、送信エージェントと受信エージェントの双方を有効化します。

- 最初のアシスタント・ページで、「終了」ではなく「次へ」をクリックして「ターゲットの選択」ページを表示し、必ずSAFエージェントをターゲット指定します。

クラスタ化の考慮事項:

- クラスタ内で信頼性のあるメッセージングを使用している場合、SAFエージェントをそのクラスタにターゲット指定する必要があります。

Oracle WebLogic Server管理コンソール・オンライン・ヘルプのストア・アンド・フォワード・エージェントの作成に関する項を参照してください。

6

必要に応じて、現在のドメイン環境をチューニングする(オプション)

『Oracle WebLogic Serverのパフォーマンスのチューニング』の負荷が高いシステムのチューニングによるWebサービスのパフォーマンス向上に関する項を参照してください。

7

サーバーを再起動します。

構成の変更を有効にするには、『Oracle WebLogic Serverサーバーの起動と停止の管理』のサーバーの起動と停止に関する項の説明に従って、サーバーを再起動する必要があります。

ソースWebLogic Serverインスタンスの構成

クライアントWebサービスがデプロイされるWebLogic Serverインスタンスを構成する際には、JMSおよびストア・アンド・フォワード(SAF)・リソースを構成します。

これらのリソースは手作業でも構成できますが、構成ウィザードで、Webサービス固有の拡張テンプレートを使用してWebLogic Serverドメインを拡張することもできます。構成ウィザードを使用すると、必要な構成手順を大幅に簡素化できます。詳細は、「Webサービス機能用のドメイン構成」を参照してください。

注意:
または、WLSTを使用してリソースを構成できます。WLSTを使用したドメインの拡張の詳細は、『WebLogic Scripting Toolの理解』の既存ドメインの構成に関する項を参照してください。
Webサービスのリソースを含まないドメインは、Webサービス以外のシナリオおよび非同期のリクエスト/レスポンスが含まれないWebサービス・シナリオにおいて、適切に起動および実行されます。ただし、サーバー・ログに、非同期リソースが構成されていないこと、およびWebサービスの非同期レスポンス・サービスが完全にデプロイされていないことを示すINFOメッセージが表示されます。

リソースを手作業で構成する場合、以下の手順を実行します。

表8-4 ソースWebLogic Serverインスタンスの構成手順

#

手順

説明

1

ソースWebLogic Serverが格納されたドメインのWebLogic Server管理コンソールを起動します。

ブラウザでWebLogic Server管理コンソールを起動するには、次のURLを入力します。

http://host:port/console

各要素の説明は次のとおりです。

- hostは、管理サーバーが動作しているコンピュータを指します。

- portは、管理サーバーが接続リクエストをリスニングしているポート番号を指します。管理サーバーのデフォルトのポート番号は7001です。

『Oracle WebLogic Server WebLogic Webサービスの理解』の管理コンソールの起動に関する項を参照してください。

2

永続ファイル・ストアを作成する(オプション)

必要に応じて、ソースWebLogic ServerがWebサービスの信頼性のあるメッセージングの内部情報を格納するために使用する永続ストア(ファイルまたはJDBC)を作成します。新規作成しない場合は、既存のものを使用するか、常に存在するデフォルトのストアを使用できます。

Oracle WebLogic Server管理コンソール・オンライン・ヘルプのファイル・ストアの作成に関する項を参照してください。

3

ストア・アンド・フォワード(SAF)エージェントを作成します。

新規作成しない場合は、既存のものを使用できます。

SAFエージェントを作成する場合は、「エージェントの種類」フィールドを「両方」に設定して、送信エージェントと受信エージェントの双方を有効化します。

Oracle WebLogic Server管理コンソール・オンライン・ヘルプのストア・アンド・フォワード・エージェントの作成に関する項を参照してください。

6

必要に応じて、現在のドメイン環境をチューニングする(オプション)

『Oracle WebLogic Serverのパフォーマンスのチューニング』の負荷が高いシステムのチューニングによるWebサービスのパフォーマンス向上に関する項を参照してください。

7

サーバーを再起動します。

構成の変更を有効にするには、『Oracle WebLogic Serverサーバーの起動と停止の管理』のサーバーの起動と停止に関する項の説明に従って、サーバーを再起動する必要があります。

Webサービスの信頼性のあるメッセージングのWS-Policyファイルの作成

WS-Policyファイルは、WS-Policy仕様に準拠するポリシー・アサーションを含むXMLファイルです。この場合、WS-PolicyファイルにはWebサービスの信頼性のあるメッセージングのポリシー・アサーションが含まれています。

WebLogic Serverには、標準的な信頼性のあるメッセージング・アサーションを含むWS-Policyファイルがあらかじめパッケージ化されています。独自のWS-Policyファイルを作成しない場合は、これらのファイルを使用できます。次の表に、あらかじめパッケージ化されているWS-Policyファイルを示します。

注意:
このリリースでは、DefaultReliability.xmlファイルとLongRunningReliability.xmlファイルは非推奨となっています。DefaultReliability1.1.xml、Reliability1.1_SequenceTransportSecurity、またはReliability1.0_1.1.xmlファイルを使用することをお薦めし、http://docs.oasis-open.org/ws-rx/wsrm/200702/wsrm-1.1-spec-os-01.pdfであるWS-ReliableMessaging仕様の1.1バージョンに準拠する必要があります。

表8-5 あらかじめパッケージ化されているWS-Policyファイル

あらかじめパッケージ化されているWS-Policyファイル

説明

DefaultReliability1.1.xml

サービス品質に関するポリシー・アサーションを指定します。Webサービスの信頼性のあるメッセージングのアサーションは、WS Reliable Messaging Policy Assertion 1.1(http://docs.oasis-open.org/ws-rx/wsrmp/200702/wsrmp-1.1-spec-os-01.pdf)に基づいています。「DefaultReliability1.1.xml (WS-Policyファイル)」を参照してください。

Reliability1.1_SequenceTransportSecurity

トランスポート・レベルのセキュリティとサービス品質に関連するポリシー・アサーションを指定します。Webサービスの信頼性のあるメッセージングのアサーションは、WS Reliable Messaging Policy Assertion 1.1(http://docs.oasis-open.org/ws-rx/wsrmp/200702/wsrmp-1.1-spec-os-01.pdf)に基づいています。「Reliability1.1_SequenceTransportSecurity.xml (WS-Policyファイル)」を参照してください。

Reliability1.0_1.1.xml

1.1と1.0のWS Reliable Messagingポリシー・アサーションを結合します。このサンプルは、適切なポリシーの選択に基づいて実行時に適用されるポリシー・アサーションを決定します。「Reliability1.0_1.1.xml (WS-Policy.xmlファイル)」を参照してください

DefaultRelibility.xml

非推奨です。Webサービスの信頼性のあるメッセージングのアサーションは、WS Reliable Messaging Policy Assertion Version 1.0(http://schemas.xmlsoap.org/ws/2005/02/rm/WS-RMPolicy.pdf)に基づいています。このリリースでは、信頼性のあるメッセージングのポリシー・アサーションの多くが、JWSアノテーションまたは構成を通じて管理されます。

信頼性のあるメッセージングのポリシー・アサーションに一般的な値(非アクティブ・タイムアウト10分、確認応答の間隔200ミリ秒、基本的な再送信間隔3秒など)を指定します。「DefaultReliability.xml (WS-Policyファイル) [非推奨]」を参照してください。

LongRunningReliability.xml

非推奨です。長期実行プロセスに関して、Webサービスの信頼性のあるメッセージングのアサーションは、WS Reliable Messaging Policy Assertion Version 1.0に基づいています。このリリースでは、信頼性のあるメッセージングのポリシー・アサーションの多くが、JWSアノテーションまたは構成を通じて管理されます。

1つ前に示した、信頼性のあるメッセージングのデフォルトWS-Policyファイルとほぼ同じですが、アクティビティのタイムアウト間隔に、より大きな値(24時間)を指定する点が異なります。「LongRunningReliability.xml (WS-Policyファイル) [非推奨]」を参照してください。

WebLogic Serverに含まれる、あらかじめパッケージ化されている信頼性のあるメッセージングWS-Policyファイルの1つを使用できます。これらのファイルは、ほとんどの場合に適合しています。あらかじめパッケージ化されているファイルは変更できません。値がニーズを満たさない場合は、カスタムのWS-Policyファイルを作成する必要があります。以下の節で、カスタムWS-Policyファイルの作成方法を説明します。

- WS-ReliableMessagingポリシー・アサーション・バージョン1.1を使用したカスタムWS-Policyファイルの作成

- WS-ReliableMessagingポリシー・アサーション・バージョン1.0を使用したカスタムWS-Policyファイルの作成(非推奨)

- 複数のポリシー選択肢の使用

WS-ReliableMessagingポリシー・アサーション・バージョン1.1を使用したカスタムWS-Policyファイルの作成

この項では、WS Reliable Messaging Policy Assertion Version 1.1(http://docs.oasis-open.org/ws-rx/wsrmp/200702/wsrmp-1.1-spec-os-01.pdf)に基づいたWebサービスの信頼性のあるメッセージングのアサーションを含むカスタムWS-Policyファイルを作成する方法について説明します。現在のリリースでは、信頼性のあるメッセージングのポリシー・アサーションの多くが、JWSアノテーションまたは構成を通じて管理されます。

WS-Policyファイルのルート要素は<Policy>であり、次のネームスペース宣言が含まれている必要があります。

<wsp:Policy
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">

Webサービスの信頼性のあるメッセージングのポリシー・アサーションはすべて、<wsrmp:RMAssertion>要素の内部でラップします。この要素には、Webサービスの信頼性のあるメッセージングのポリシー・アサーションを使用するため、次のネームスペース宣言が含まれている必要があります。

<wsrmp:RMAssertion
xmlns:wsrmp="http://docs.oasis-open.org/ws-rx/wsrmp/200702">

次の表に、WS-Policyファイルで指定可能なWebサービスの信頼性のあるメッセージングのアサーションを示します。アサーションの指定順序は重要です。次のアサーションを指定できますが、WS-Policyファイルでは次の一覧の順序どおりに指定する必要があります。

表8-6 Webサービスの信頼性のあるメッセージング・アサーション(バージョン1.1)

アサーション

説明

<wsrmp:SequenceSTR>

信頼性のあるシーケンスでメッセージを保護するため、ランタイムではCreateSequenceメッセージで参照されるwsse:SecurityTokenReferenceが使用されます。指定できるセキュリティ・アサーションは1つのみとなります。つまり、wsrmp:SequenceSTRまたはwsrmp:SequenceTransportSecurityのいずれか1つは指定できますが、両方は指定できません。

<wsrmp:SequenceTransportSecurity>

信頼性のあるシーケンスでメッセージを保護するため、ランタイムではCreateSequenceメッセージの送信に使用されるSSLトランスポート・セッションが使用されます。このアサーションは、特定のトランスポート・レベル・セキュリティ・メカニズム(sp:HttpsTokenなど)の使用を要求するsp:TransportBindingアサーションとともに使用する必要があります。指定できるセキュリティ・アサーションは1つのみとなります。つまり、wsrmp:SequenceSTRまたはwsrmp:SequenceTransportSecurityのいずれか1つは指定できますが、両方は指定できません。

<wsrm:DeliveryAssurance>

Webサービスの配信保証レベル(配信品質)。有効な値は、AtMostOnce、AtLeastOnce、ExactlyOnceおよびInOrder。次の表に定義されている配信保証のいずれか1つを設定できます。設定しない場合、配信保証にはデフォルトのExactlyOnceが使用されます。

次の例では、簡単なWebサービスの信頼性のあるメッセージングのWS-Policyファイルを示します。

<?xml version="1.0"?>

<wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
<wsrmp:RMAssertion
xmlns:wsrmp="http://docs.oasis-open.org/ws-rx/wsrmp/200702">
<wsrmp:SequenceTransportSecurity/>
<wsrmp:DeliveryAssurance>
<wsp:Policy>
<wsrmp:ExactlyOnce/>
</wsp:Policy>
</wsrmp:DeliveryAssurance>
</wsrmp:RMAssertion>
</wsp:Policy>

WS-Policyファイルにおける信頼性のあるメッセージングのポリシー・アサーションの詳細は、『Oracle WebLogic Server WebLogic Webサービス・リファレンス』のWebサービスの信頼性のあるメッセージングのポリシー・アサーションに関するリファレンスの項を参照してください。

WS-ReliableMessagingポリシー・アサーション・バージョン1.0を使用したカスタムWS-Policyファイルの作成(非推奨)

この項では、WS Reliable Messaging Policy Assertion Version 1.0(http://schemas.xmlsoap.org/ws/2005/02/rm/WS-RMPolicy.pdf)に基づいたWebサービスの信頼性のあるメッセージングのアサーションを含むカスタムWS-Policyファイルを作成する方法について説明します。

注意:
現在のリリースでは、信頼性のあるメッセージングのポリシー・アサーションの多くが、JWSアノテーションまたは構成を通じて管理されます。

WS-Policyファイルのルート要素は<Policy>です。Webサービスの信頼性のあるメッセージングのポリシー・アサーションを使用するには、これに次のネームスペース宣言が含まれていることが必要です。

<wsp:Policy
xmlns:wsrm="http://schemas.xmlsoap.org/ws/2005/02/rm"
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
xmlns:beapolicy="http://www.bea.com/wsrm/policy">

Webサービスの信頼性のあるメッセージングのポリシー・アサーションはすべて、<wsrm:RMAssertion要素の内部でラップします。wsrm:ネームスペースを使用するアサーションは、WS-ReliableMessaging仕様(http://docs.oasis-open.org/ws-rx/wsrm/200702/wsrm-1.1-spec-os-01.pdf)で定義される標準的なアサーションです。beapolicy:ネームスペースを使用するアサーションは、WebLogic固有のものです。詳細は、『Oracle WebLogic Server WebLogic Webサービス・リファレンス』のWebサービスの信頼性のあるメッセージングのポリシー・アサーションに関するリファレンスの項を参照してください。

次の表に、WS-Policyファイルで指定可能なWebサービスの信頼性のあるメッセージングのアサーションを示します。Webサービスの信頼性のあるメッセージングのアサーションは、すべてオプションなので、デフォルト値が不適切なものだけを設定します。アサーションの指定順序は重要です。次のアサーションを指定できますが、WS-Policyファイルでは次の一覧の順序どおりに指定する必要があります。

表8-7 Webサービスの信頼性のあるメッセージング・アサーション(バージョン1.0)

アサーション

説明

<wsrm:InactivityTimeout>

非アクティブ間隔を定義する、Milliseconds属性で指定されるミリ秒数。この時間が経過した時点で、宛先エンドポイントがソース・エンドポイントからのメッセージを受け取っていなければ、宛先エンドポイントは、処理が行われずシーケンスは終了したものと見なす場合があります。これは、ソース・エンドポイントについても同様のことが言えます。デフォルトでは、シーケンスがタイムアウトすることはありません。

<wsrm:BaseRetransmissionInterval>

ソース・エンドポイントがメッセージを送信してから、そのメッセージの確認応答を受け取っていない場合に再送信を行うまでの間隔(ミリ秒単位)。デフォルト値は、ソース・エンドポイントのWebLogic Serverインスタンス上のSAFエージェントによって設定されます。

<wsrm:ExponentialBackoff>

再送信の間隔が、指数関数的なバックオフ・アルゴリズムを使用して調整されることを指定します。この要素には属性はありません。

<wsrm:AcknowledgmentInterval>

宛先エンドポイントがスタンドアロンの確認応答を送信しなければならない最大間隔(ミリ秒単位)。デフォルト値は、宛先エンドポイントのWebLogic Serverインスタンス上のSAFエージェントによって設定されます。

<beapolicy:Expires>

信頼性のあるWebサービスの有効期限が切れ、これ以上の新しいシーケンス・メッセージを受け付けなくなるまでの時間の長さ。デフォルト値では、有効期限が切れることはありません。この要素には、Expiresという1つの属性があります。この属性のデータ型はXMLスキーマ期間型です。(http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/#durationを参照。)たとえば、有効期限までを1日と設定する場合は、<beapolicy:Expires Expires="P1D" />とします。

<beapolicy:QOS>

表8-9で説明されている、配信保証レベル。この要素にはQOSという1つの属性があり、この属性はAtMostOnce、AtLeastOnce、ExactlyOnceの各値のうちの1つに設定します。また、メッセージを順序通りにすることを指定するためにInOrder文字列を含めることもできます。デフォルト値はExactlyOnce InOrderです。この要素は通常、設定されません。

次の例では、簡単なWebサービスの信頼性のあるメッセージングのWS-Policyファイルを示します。

<?xml version="1.0"?>

<wsp:Policy
xmlns:wsrm="http://schemas.xmlsoap.org/ws/2005/02/rm/policy"
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
xmlns:beapolicy="http://www.bea.com/wsrm/policy"
>

<wsrm:RMAssertion>

<wsrm:InactivityTimeout
Milliseconds="600000" />
<wsrm:BaseRetransmissionInterval
Milliseconds="500" />
<wsrm:ExponentialBackoff />
<wsrm:AcknowledgementInterval
Milliseconds="2000" />

</wsrm:RMAssertion>

</wsp:Policy>

WS-Policyファイルにおける信頼性のあるメッセージングのポリシー・アサーションの詳細は、『Oracle WebLogic Server WebLogic Webサービス・リファレンス』のWebサービスの信頼性のあるメッセージングのポリシー・アサーションに関するリファレンスの項を参照してください。

複数のポリシー選択肢の使用

カスタム・ポリシー・ファイルを作成することによって、単一のWebサービスに対して複数のポリシー選択肢(適切なポリシー選択肢)を構成できます。実行時には、適用されるポリシーがそれらの中から自動的に選択されます。その際は、サポートされていないポリシーやアサーションが競合しているポリシーが除外され、構成されているプリファレンスに基づいて、受信メッセージの検証とレスポンス・メッセージの構築に適したポリシーが選択されます。

次の例では、1.1と1.0 WSの信頼性のあるメッセージングの両方をサポートするセキュリティ・ポリシーの例を示します。各ポリシー選択肢は、<wsp:All>要素で囲まれています。

注意:
1.0のWebサービスの信頼性のあるメッセージング・アサーションには、接頭辞としてwsrmp10が付加されます。

<wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
<wsp:ExactlyOne>
<wsp:All>
<wsrmp10:RMAssertion
xmlns:wsrmp10="http://schemas.xmlsoap.org/ws/2005/02/rm/policy">
<wsrmp10:InactivityTimeout Milliseconds="1200000"/>
<wsrmp10:BaseRetransmissionInterval Milliseconds="60000"/>
<wsrmp10:ExponentialBackoff/>
<wsrmp10:AcknowledgementInterval Milliseconds="800"/>
</wsrmp10:RMAssertion>
</wsp:All>
<wsp:All>
<wsrmp:RMAssertion
xmlns:wsrmp="http://docs.oasis-open.org/ws-rx/wsrmp/200702">
<wsrmp:SequenceSTR/>
<wsrmp:DeliveryAssurance>
<wsp:Policy>
<wsrmp:AtMostOnce/>
</wsp:Policy>
</wsrmp:DeliveryAssurance>
</wsrmp:RMAssertion>
</wsp:All>
</wsp:ExactlyOne>
</wsp:Policy>

複数のポリシー選択肢の詳細は、『Oracle WebLogic Server WebLogic Webサービスの保護』の「メッセージ・レベルのセキュリティの構成」、適切なポリシーの選択に関する項を参照してください。

信頼性のあるJWSファイルに関するプログラミングのガイドライン

この項では、信頼性のあるWebサービスを実装するJWSファイルの作成方法を説明します。

信頼性のあるWebサービスを実装するJWSファイルでは、次のJWSアノテーションが使用されます。

表8-8 信頼性のあるメッセージングのJWSアノテーション

アノテーション

説明

@weblogic.jws.Policy

必須項目。信頼性のあるメッセージングのアサーションが含まれるWS-PolicyファイルをWebサービスに追加するよう指定します。「@Policyアノテーションの使用」を参照してください。

@javax.jws.Oneway

信頼性のあるWebサービス操作を同期的に呼び出す(つまり、非同期リクエスト-レスポンスの機能は使用しない)場合にのみ必須です。「@Onewayアノテーションの使用」を参照してください。

@weblogic.jws.BufferQueue

オプション。WebLogic Serverが信頼性のあるメッセージを内部的に格納するために使用するJMSキューのJNDI名を指定します。「@BufferQueueアノテーションの使用」を参照してください。

@weblogic.jws.ReliabilityBuffer

オプション。WebLogic ServerによるJMSキューからWebサービス実装へのメッセージ配信試行回数、およびサーバーが待機すべき再試行間隔を指定します。「@ReliabilityBufferアノテーションの使用」を参照してください。

次のサンプルでは、信頼性のあるWebサービスを実装する簡単なJWSファイルを示します。太字で示されたJavaコードに対応するコーディングのガイドラインについては、サンプルの後の説明を参照してください。

package examples.webservices.reliable;

import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.jws.Oneway;

import weblogic.jws.WLHttpTransport;

import weblogic.jws.ReliabilityBuffer;
import weblogic.jws.BufferQueue;
import weblogic.jws.Policy;

/**
* Simple reliable Web Service.
*/

@WebService(name="ReliableHelloWorldPortType",
serviceName="ReliableHelloWorldService")

@WLHttpTransport(contextPath="ReliableHelloWorld",
serviceUri="ReliableHelloWorld",
portName="ReliableHelloWorldServicePort")

@Policy(uri="ReliableHelloWorldPolicy.xml",
direction=Policy.Direction.both,
attachToWsdl=true)
@BufferQueue(name="webservices.reliable.queue")

public class ReliableHelloWorldImpl {

private static String onewaySavedInput = null;

/**
* A one-way helloWorld method that saves the given string for later
* concatenation to the end of the message passed into helloWorldReturn.
*/
@WebMethod()
@Oneway()
@ReliabilityBuffer(retryCount=10, retryDelay="10 seconds")

public void helloWorld(String input) {
System.out.println(" Hello World " + input);
onewaySavedInput = input;
}

/**
* This echo method concatenates the saved message from helloWorld
* onto the end of the provided message, and returns it.
*/
@WebMethod()
@ReliabilityBuffer(retryCount=10, retryDelay="10 seconds")

public String echo(String input2) {
System.out.println(" Hello World " + input2 + onewaySavedInput);
return input + onewaySavedInput;
}
}

この例では、カスタムReliableHelloWorldPolicy.xmlポリシー・ファイルがクラス・レベルでWebサービスに追加されています。つまり、ポリシー・ファイルはWebサービスのすべてのパブリック操作に適用されます。ポリシー・ファイルは、リクエストWebサービス・メッセージ(信頼性のあるメッセージング機能によって要求される)のみに適用され、WSDLファイルに追加されます。あらかじめパッケージ化されている利用可能なポリシーおよびカスタム・ポリシーの作成の詳細につぃては、「Webサービスの信頼性のあるメッセージングのWS-Policyファイルの作成」を参照してください。

WebLogic Serverが、Webサービスの信頼性のあるメッセージングを有効化するために内部で使用するJMSキューのJNDI名は、@BufferQueueアノテーションで指定されているように、webservices.reliable.queueです。

helloWorld()メソッドは、@WebMethodと@Oneway、どちらのJWSアノテーションでもマークされています。これは、このメソッドがhelloWorldというパブリック操作であるということです。@Policyアノテーションがあるために、操作を確実に呼び出すことができます。@ReliabilityBufferアノテーションに記述されているとおり、Webサービスのランタイムでは、最大で10回、10秒間隔で、信頼性のあるメッセージをサービスに配信しようとします。たとえば、トランザクションがロールバックされる場合や、コミットしない場合などには、メッセージの再配信が必要となることがあります。

echo()メソッドは、@WebMethodとJWSアノテーションでもマークされています。これは、このメソッドがechoというパブリック操作であるということです。@Policyアノテーションがあるために、操作を確実に呼び出すことができます。helloWorld()メソッドと同じような信頼性バッファ構成を使用します。

@Policyアノテーションの使用

信頼性のあるメッセージングのアサーションが含まれるWS-PolicyファイルをWebサービスに追加するよう指定するには、JWSファイルで@Policyアノテーションを使用します。WebLogic Serverでは、あらかじめパッケージ化されているWS-Policyファイルのセットが提供されます。付録A「信頼性のあるメッセージング用にパッケージ化されているWS-Policyファイル」を参照してください。

Webサービスの信頼性のあるメッセージングで@Policyアノテーションを使用する場合は、次のガイドラインに従います。

- uri属性を使用して、ポリシー・ファイルのビルド時の場所を以下のように指定します。

- 独自のWS-Policyファイルを作成した場合は、JWSファイルを基準として相対的に場所を指定します。例:

@Policy(uri="ReliableHelloWorldPolicy.xml",
direction=Policy.Direction.both,
attachToWsdl=true)

この例では、ReliableHelloWorldPolicy.xmlファイルがJWSファイルと同じディレクトリに置かれています。

- あらかじめパッケージ化されているWS-Policyファイルの1つか、共有Java EEライブラリにパッケージ化されているWS-Policyファイルを指定するには、そのポリシー・ファイルの名前とパスとともにpolicy:接頭辞を使用します。この構文ではビルド時のjwsc Antタスクに、ファイル・システムの実際のファイルを探させず、Webサービスが、サービスのデプロイ時にWebLogic ServerからWS-Policyファイルを取得することを通知しています。

注意:
共有Java EEライブラリは、様々なエンタープライズ・アプリケーション内にパッケージ化されている複数のWebサービスとWS-Policyファイルを共有する場合に有用です。WS-Policyファイルが共有Java EEライブラリのMETA-INF/policiesまたはWEB-INF/policiesディレクトリに置かれているかぎり、ポリシー・ファイルはWebサービスの同じアーカイブにパッケージ化されている場合と同様に指定できます。ライブラリの作成、およびWebサービスがポリシー・ファイルを見つけることができるようにするための環境設定については、『Oracle WebLogic Serverアプリケーションの開発』の共有Java EEライブラリおよびオプション・パッケージの作成に関する項を参照してください。

- ポリシー・ファイルをWeb上で公開するよう指定するには、次の例に示すとおり、URLと共にhttp:接頭辞を使用します。

@Policy(uri="http://someSite.com/policies/mypolicy.xml"
direction=Policy.Direction.both,
attachToWsdl=true)

- デフォルトでは、WS-Policyファイルはリクエスト(着信)とレスポンス(発信)の両方のSOAPメッセージに適用されます。このデフォルトの動作は、direction属性をPolicy.Direction.inboundまたはPolicy.Direction.outboundに設定すると変更できます。

- uriで指定されるポリシー・ファイル内でwsp:optional属性を使用し、Webサービスで操作が確実に呼び出され、そのレスポンスが確実に配信されるよう要求するかどうかを指定できます。
任意の操作での発信に対してoptional属性をfalseに設定する場合:

- クライアントは、信頼性のあるレスポンスを送信する時使用できるようにofferシーケンスを提供する必要があります。(http://docs.oasis-open.org/ws-rx/wsrm/200702/wsrm-1.1-spec-os-01.pdfにあるWS-ReliableMessaging仕様で説明されている<wsrm: Offer...>)

- レスポンスが必要なすべての操作に対してレスポンスが確実に送信されます。

すべての操作での発信に対してoptional属性をtrueに設定する場合:

- クライアントはofferシーケンスを提供する必要がありません。

- クライアントがofferシーケンスを提供する場合、レスポンスは確実に送信され、提供しない場合、レスポンスの送信には信頼性がありません。

- @PolicyアノテーションのattachToWsdl属性を設定して、ポリシー・ファイルをWebサービスのパブリック規約が記述されたWSDLファイルに付加するかどうかを指定できます。通常は、クライアント・アプリケーションでWebサービスの信頼性のあるメッセージング機能が認識されるよう、パブリックなものとしてポリシーを公開します。そのため、この属性のデフォルト値はtrueです。

@Policyアノテーションの詳細は、『Oracle WebLogic Server WebLogic Webサービス・リファレンス』のweblogic.jws.Policyに関する項を参照してください。

@Onewayアノテーションの使用

信頼性のあるWebサービス操作を同期的に呼び出す(すなわち、非同期リクエスト-レスポンス機能を使用しない)場合は、実装メソッドに@Onewayアノテーションを付けて、そのメソッドが一方向のものであることを指定する必要があります。つまり、メソッドは値を戻すことができず、明示的にvoidを戻すことになります。

反対に、メソッドに@Onewayアノテーションが付いていなければ、非同期リクエスト-レスポンス機能を使用して呼び出す必要があります。操作の呼出し方法がわからない場合は、同期と非同期の2種類の操作を作成することを検討してください。

第7章「非同期リクエスト-レスポンスを使用したWebサービスの呼出し」と第11章「非同期機能の併用」を参照してください。

@BufferQueueアノテーションの使用

信頼性のあるメッセージを内部に格納するためにWebLogic Serverが使用するJMSキューのJNDI名を指定するには、@BufferQueueアノテーションを使用します。JNDI名は、「宛先WebLogic Serverインスタンスの構成」のステップ4でのJMSキューの作成時に構成したものです。

@BufferQueueアノテーションは、省略可能です。これをJWSファイルで指定しなければ、WebLogic Serverはweblogic.wsee.DefaultQueueのJNDI名を持つキューを使用します。ただし、それでもこのJNDI名を持つJMSキューをWebLogic Server管理コンソールで明示的に作成する必要はあります。

@BufferQueueアノテーションの詳細は、『Oracle WebLogic Server WebLogic Webサービス・リファレンス』のweblogic.jws.BufferQueueに関する項を参照してください。

@ReliabilityBufferアノテーションの使用

@ReliabilityBufferアノテーションは、WebLogic ServerによるJMSキューからWebサービス実装へのメッセージ配信試行回数、およびサーバーが待機すべき再試行間隔の指定に使用します。

再試行回数の指定にはretryCount属性を、待機時間の指定にはretryDelay属性を使用します。retryDelay属性の形式としては、数字の後に以下の文字列のうち1つを続けます。

- seconds

- minutes

- hours

- days

- years

たとえば、再試行回数を20、再試行の遅延を2日と指定するには、次の構文を使用します。

@ReliabilityBuffer(retryCount=20, retryDelay="2 days")

再試行の回数と遅延のデフォルト値はそれぞれ、3と5です。

@ReliabilityBufferアノテーションの詳細は、『Oracle WebLogic Server WebLogic Webサービス・リファレンス』のweblogic.jws.ReliabilityBufferに関する項を参照してください。

信頼性のあるWebサービスの信頼性のあるメッセージングの構成

必要に応じて、アプリケーションのデプロイメント・プランを更新し、weblogic-webservices.xml記述子に格納される、信頼性のあるWebサービスの信頼性のあるメッセージ構成オプションを編集することができます。新しい値は、デプロイメント・プランにより、現在のアプリケーションの記述子における特定の場所に関連付けられます。デプロイメント時に、デプロイメント・プランは変数割当ての値を、その変数のリンク先アプリケーション記述子内の場所に適用することによって、そのアプリケーション内の記述子に結合されます。

次の表では、信頼性のあるWebサービス用に構成できる信頼性のあるメッセージングのオプションを説明しています。

表8-9 信頼性のあるメッセージングの構成オプション

構成オプション

説明

信頼性のあるメッセージ構成のカスタマイズ

Webサービス・エンドポイント・レベルにおけるWebサービス記述子またはデプロイメント・プランで定義された信頼性のあるメッセージ構成をカスタマイズするかどうかを指定するフラグ。このフラグは、Webサービス・エンドポイント・レベルで信頼性のあるメッセージングを構成する場合にのみ使用できます。チェックされない場合、WebLogic Serverに指定された信頼性のあるメッセージ構成が使用されます。

注意:このフラグは、直接WSDLに指定されるWS-RMポリシーなどの他の形式では、信頼性のあるメッセージングの構成を反映しません。

基本の再送信間隔

RM宛先にメッセージの再送信を行うまでの時間間隔。

ソース・エンドポイントが、指定した間隔内で所定のメッセージの確認応答を受信しなかった場合、ソース・エンドポイントはメッセージを再送信します。ソース・エンドポイントは、メッセージのシーケンスの存続期間内の任意の時点で、この再送信間隔を変更することがあります。

この要素を「再送信間隔の指数関数的バックオフ」要素と組み合せて使用すると、再送信間隔を調整するアルゴリズムを指定できます。

指定する値はXMLスキーマの期間を表す字句形式(PnYnMnDTnHnMnS)に従った正の値でなければなりません。ここで、nYは年数、nMは月数、nDは日数を表し、Tは日付/時刻のセパレータ、nHは時間数、nMは分数、nSは秒数を表します。この値のデフォルトはP0DT3S (3秒)です。

再送信間隔の指数関数的バックオフの有効化

メッセージの再送信の間隔を、指数関数的なバックオフ・アルゴリズムを使用して調整するかどうかを示すフラグ。

この要素は「基本の再送信間隔」要素と組み合せて使用します。宛先エンドポイントが、「基本の再送信間隔」で指定した時間内でメッセージのシーケンスを確認応答しなかった場合、メッセージが引続き確認されなければ、連続再送信のタイミングに対して、ソース・エンドポイントは指数関数的なバックオフ・アルゴリズムを使用します。

指数関数的なバックオフ・アルゴリズムは、連続再送信の間隔が、基本の再送信間隔を基に指数的に増えるように指定します。たとえば、基本の再送信間隔が2秒で、指数関数的なバックオフ要素が設定されている場合、連続再送信の間隔は、メッセージが確認されなければ、2、4、8、16、32秒というように増えていきます。

デフォルト値はfalseであり、連続再送信の間隔は指数的に増えず、同じ値が維持されます。

確認応答の間隔

宛先エンドポイントがスタンドアロンの確認応答を送信しなければならない最大間隔。

宛先エンドポイントは、ソース・エンドポイントからメッセージを受信した直後に、返されたメッセージに対する確認応答を送信できます。また、スタンドアロンの確認応答として個別に確認応答を送信することもできます。返されたメッセージに対して確認応答を送信できない場合、宛先エンドポイントは、スタンドアロンの確認応答を送信するまで、確認応答の間隔に設定した時間範囲内で待機することがあります。未確認メッセージがない場合、宛先エンドポイントは確認応答を送信しない可能性があります。

指定する値はXMLスキーマの期間を表す字句形式(PnYnMnDTnHnMnS)に従った正の値でなければなりません。ここで、nYは年数、nMは月数、nDは日数を表し、Tは日付/時刻のセパレータ、nHは時間数、nMは分数、nSは秒数を表します。この値のデフォルトはP0DT0.2S (200ミリ秒)。

非アクティブ・タイムアウト

非アクティブの間隔。非アクティブ・タイムアウト間隔で、エンドポイント(RM送信元とRM宛先)がアプリケーションのメッセージまたは制御メッセージを受け取らなければ、エンドポイントはRMシーケンスが非アクティブなため終了したものと見なす場合があります。

指定する値はXMLスキーマの期間を表す字句形式(PnYnMnDTnHnMnS)に従った正の値でなければなりません。ここで、nYは年数、nMは月数、nDは日数を表し、Tは日付/時刻のセパレータ、nHは時間数、nMは分数、nSは秒数を表します。この値のデフォルトはP0DT600S(600秒)です。

順序の有効期限

アクティビティにかかわらず、シーケンスが期限切れになるまでの時間。

指定する値はXMLスキーマの期間を表す字句形式(PnYnMnDTnHnMnS)に従った正の値でなければなりません。ここで、nYは年数、nMは月数、nDは日数を表し、Tは日付/時刻のセパレータ、nHは時間数、nMは分数、nSは秒数を表します。この値のデフォルトはP1D(1日)です。

バッファの再試行回数

信頼性のあるリクエストを再試行する回数。この値のデフォルトは3。

バッファの再試行遅延

信頼性のあるリクエストを再試行するまでの待機時間。

再試行間隔は、JMSキューにあるクライアントのリクエスト・メッセージとWebサービスの実装へのメッセージ配信までの間隔。

指定する値はXMLスキーマの期間を表す字句形式(PnYnMnDTnHnMnS)に従った正の値でなければなりません。ここで、nYは年数、nMは月数、nDは日数を表し、Tは日付/時刻のセパレータ、nHは時間数、nMは分数、nSは秒数を表します。この値のデフォルトはP0DT5S(5秒)です。

信頼性のあるメッセージング構成オプションは、WebLogic Server管理コンソールやWLSTを使用して設定できます。以降の項を参照してください。

- 管理コンソールの使用

- WLSTの使用

管理コンソールの使用

WebLogic Server管理コンソールを使用してWebサービス・エンドポイント用の信頼性のあるメッセージングを構成するには:

1. 『Oracle WebLogic Server WebLogic Webサービスの理解』の管理コンソールの起動に関する項の説明に従って、WebLogic Server管理コンソールを起動します。

2. 左側のナビゲーション・ペインで、「デプロイメント」を選択します。

3. 「デプロイメント」表でWebサービスの名前をクリックします。

4. 「構成」タブ、「ポート」タブの順に選択します。

5. 「ポート」表でWebサービスのエンドポイントの名前をクリックします。

6. 「信頼できるメッセージ」タブを選択します。

7. 「信頼性のあるメッセージ構成のカスタマイズ」をクリックし、必要に応じて、指示に従ってデプロイメント・プランを保存します。

8. 必要に応じて、信頼性のあるメッセージングのプロパティを設定します。

9. 「保存」をクリックします。

WLSTの使用

WLSTを使用して、信頼性のあるメッセージングを構成するためにアプリケーションのデプロイメント・プランを更新する方法の説明と例は、『WebLogic Scripting Toolの理解』のデプロイメント・プランの更新に関する項を参照してください。

以下の表に、WS-RM構成オプションのXPath値を参考としてまとめます。

表8-10 WS_RM構成変数名とXPath値

構成オプション

変数名の例

XPath値

非アクティブ・タイムアウト

ReliabilityConfig_
InactivityTimeout

/weblogic-webservices/webservice-description/
[webservice-description-name="
service_name"]/port-component/
[port-component-name="port_name"]
/reliability-config/inactivity-timeout

基本の再送信間隔

ReliabilityConfig_
BaseRetransmission
Interval

/weblogic-webservices/webservice-description/
[webservice-description-name=
"service_name"]/port-component/
[port-component-name="port-name"]
/reliability-config/base-retransmission-interval

再送信間隔の指数関数的バックオフ

ReliabilityConfig_
Retransmission
ExponentialBackoff

/weblogic-webservices/webservice-description/
[webservice-description-name=
"service_name"]/port-component/
[port-component-name="port-name"]/reliability-
config/retransmission-exponential-backoff

確認応答の間隔

ReliabilityConfig_
AcknowledgementInterval

/weblogic-webservices/webservice-description/
[webservice-description-name=
"service_name"]/port-component/
[port-component-name="port-name"]
/reliability-config/acknowledgement-interval

順序の有効期限

ReliabilityConfig_
SequenceExpiration

/weblogic-webservices/webservice-description/
[webservice-description-name=
"service_name"]/port-component/
[port-component-name="port-name"]
/reliability-config/sequence-expiration

バッファの再試行回数

ReliabilityConfig_
BufferRetryCount

/weblogic-webservices/webservice-description/
[webservice-description-name=
"service_name"]/port-component/
[port-component-name="port-name"]
/reliability-config/buffer-retry-count

バッファの再試行遅延

ReliabilityConfig_
BufferRetryDelay

/weblogic-webservices/webservice-description/
[webservice-description-name=
"service_name"]/port-component/
[port-component-name="port-name"]
/reliability-config/buffer-retry-delay

信頼性のあるWebサービスを呼び出すJWSファイルに関するプログラミングのガイドライン

WebLogicクライアントAPIを使用している場合は、信頼性のあるWebサービスをWebサービス内から呼び出す必要があります。スタンドアロンのクライアント・アプリケーションからは呼び出せません。

次の例では、「信頼性のあるJWSファイルに関するプログラミングのガイドライン」で説明した、サービスから信頼性のある操作を呼び出すWebサービス用の簡単なJWSファイルを示します。

package examples.webservices.reliable;

import java.rmi.RemoteException;

import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.xml.rpc.Stub;
import weblogic.jws.WLHttpTransport;
import weblogic.jws.ServiceClient;
import weblogic.jws.ReliabilityErrorHandler;

import weblogic.jws.AsyncFailure;
import weblogic.jws.AsyncResponse;

import examples.webservices.reliable.ReliableHelloWorldPortType;

import weblogic.wsee.reliability.ReliabilityErrorContext;
import weblogic.wsee.reliability.ReliableDeliveryException;
import weblogic.wsee.reliability.WsrmUtils;

@WebService(name="ReliableClientPortType",
serviceName="ReliableClientService")

@WLHttpTransport(contextPath="ReliableClient",
serviceUri="ReliableClient",
portName="ReliableClientServicePort")

public class ReliableClientImpl
{
private static String responseMessage = null;

@ServiceClient(
serviceName="ReliableHelloWorldService",
portName="ReliableHelloWorldServicePort")

private ReliableHelloWorldPortType port;

@WebMethod
public void callHelloWorld(String input, String input2, String serviceUrl)
throws RemoteException {

((Stub)port)._setProperty(Stub.ENDPOINT_ADDRESS_PROPERTY, serviceUrl);

port.helloWorld(input);

System.out.println(" Invoked the ReliableHelloWorld.helloWorld operation reliably." );
WsrmUtils.setFinalMessage((Stub)port);
port.echo(input2);
System.out.println(" Invoked the ReliableHelloWorld.echo operation reliably." );
}

@AsyncResponse(target = "port", operation = "echo")
public void onEchoAsyncResponse(String msg) {

System.out.println("ClientService: Got async response for request : " + msg);
responseMessage = msg;
}

@AsyncFailure(target = "port", operation = "echo")
public void onEchoAsyncFailure(Throwable t) {
System.out.println("ClientService: Got async FAILURE for request : " + t);
t.printStackTrace();
}

@ReliabilityErrorHandler(target="port")
public void onReliableMessageDeliveryError(ReliabilityErrorContext ctx) {

ReliableDeliveryException fault = ctx.getFault();
String message = null;
if (fault != null) {
message = ctx.getFault().getMessage();
}
String operation = ctx.getOperationName();
System.out.println("Reliable operation " + operation + " may have not invoked. The error message is " + message);
}

}

信頼性のあるWebサービスを呼び出すJWSファイルをプログラミングする際は、次のガイドラインに従います。ガイドラインのサンプル・コードは、前述のサンプル内では太字で示されています。

- @ServiceClientおよび@ReliabilityErrorHandler JWSアノテーションをインポートします。

import weblogic.jws.ServiceClient;
import weblogic.jws.ReliabilityErrorHandler;

- エラー(信頼性のあるWebサービスから受信したメッセージの確認応答をクライアントWebサービスで受信していない場合に発生するエラー)を処理するメソッド内で使用するWebLogic APIをインポートします。

import weblogic.wsee.reliability.ReliabilityErrorContext;
import weblogic.wsee.reliability.ReliableDeliveryException;

- 非同期のレスポンスおよび障害のために使用するAPIをインポートします。

import weblogic.jws.AsyncFailure;
import weblogic.jws.AsyncResponse;

- 呼び出す信頼性のあるWebサービスのポート・タイプのJAX-RPCスタブをインポートします。このスタブは、jwsc Antタスクの<clientgen>子要素によって後から作成されます。スタブ・パッケージは、<clientgen>のpackageName属性によって指定され、スタブの名前は呼び出されたWebサービスのWSDLによって決まります。

import examples.webservices.reliable.ReliableHelloWorldPortType;

- ライフサイクル管理に使用されるAPIをインポートします(あとでプロパティを設定し、最終メッセージを指定するため)。

import javax.xml.rpc.Stub;
import weblogic.wsee.reliability.WsrmUtils;

- JWSファイルの本文で、@ServiceClient JWSアノテーションを使用して、呼び出す信頼性のあるWebサービスの名前とポートを指定します。このアノテーションは、プライベート変数のフィールド・レベルで指定します。この変数のデータ型は、呼び出しているWebサービスのJAX-RPCポート・タイプとなります。

@ServiceClient(
serviceName="ReliableHelloWorldService",
portName="ReliableHelloWorldServicePort")

private ReliableHelloWorldPortType port;

- port._setPropertyメソッドを使用して、ターゲットとなるサービス・エンドポイント・アドレスをWebサービス・クライアント内で動的に指定します。

((Stub)port)._setProperty(Stub.ENDPOINT_ADDRESS_PROPERTY, serviceUrl);

- @ServiceClientアノテーションを付けたスタブを使用して、信頼性のある操作helloWorldを呼び出します。

port.helloWorld(input);

操作は一方向のものとしてマークされているので、値は返しません。

- エラー(信頼性のあるWebサービスが受信したメッセージの確認応答をクライアントWebサービスで受信していない場合に発生するエラー)を処理するメソッドを作成し、@weblogic.jws.ReliabilityErrorHandlerアノテーションを付けます。

@ReliabilityErrorHandler(target="port")
public void onReliableMessageDeliveryError(ReliabilityErrorContext ctx) {
ReliableDeliveryException fault = ctx.getFault();
String message = null;
if (fault != null) {
message = ctx.getFault().getMessage();
}
String operation = ctx.getOperationName();
System.out.println("Reliable operation " + operation + " may have not invoked. The error message is " + message);
}

このメソッドは、唯一のパラメータとしてReliabilityErrorContextを取り、voidを返します。

このエラー処理メソッドのプログラミングの詳細は、『Oracle WebLogic Server WebLogic Webサービス・リファレンス』のweblogic.jws.ReliabilityErrorHandlerに関する項を参照してください。

- サービスは会話型ではないため、ポート・フィールドに保持されている状態は、このメソッドが戻されると失われます。信頼性のあるメッセージングの場合、この状態には、メッセージの送信に使用されている信頼性のあるシーケンスのIDが含まれます。setFinalMessageメソッドは、このメッセージがこのシーケンスで送信される最終メッセージであることを指定します。これにより、信頼性のあるメッセージング・サブシステムは、信頼性のあるシーケンスをタイムアウトさせる前にクリーンアップすることができます。

WsrmUtils.setFinalMessage((Stub)port);

- @ServiceClientアノテーションを付けたスタブを使用して、信頼性のある操作echoを呼び出します。

port.echo(input2);

- 非同期レスポンスまたは障害を処理するメソッドを作成します。@weblogic.jws.AsyncResponseと@weblogic.jws.AsyncFailureアノテーションを使用します。

@AsyncResponse(target = "port", operation = "echo")
public void onEchoAsyncResponse(String msg) {
System.out.println("ClientService: Got async response for request : " + msg);
responseMessage = msg;
}

@AsyncFailure(target = "port", operation = "echo")
public void onEchoAsyncFailure(Throwable t) {
System.out.println("ClientService: Got async FAILURE for request : " + t);
t.printStackTrace();
}

非同期のレスポンスおよび障害のメソッドの生成方法については、「非同期のJWSファイルの記述」を参照してください。

クライアントWebサービスをプログラミングする際、次のガイドラインに従います。

- 関連付けられたWS-Policyファイル内で、信頼性のあるメッセージング・アノテーション(ただし@ReliabilityErrorHandlerを除く)を指定したり、信頼性のあるメッセージング・アサーションを使用しません。

- @ServiceClientアノテーションのwsdlLocation属性を指定しません。これは、指定したWSDLの実行時の取得に失敗する可能性があり、ローカルのWSDLファイルが使用されるようにしておいたほうがよいためです。

信頼性のあるWebサービスのクライアント用build.xmlファイルの更新

build.xmlファイルを更新し、信頼性のあるWebサービス操作を呼び出すJWSファイルを生成するには、次のようなtaskdefおよびbuild-reliable-clientターゲットを追加します。

<taskdef name="jwsc"
classname="weblogic.wsee.tools.anttasks.JwscTask" />

<target name="build-reliable-client">

<jwsc
enableAsyncService="true"
srcdir="src"
destdir="${client-ear-dir}" >

<jws file="examples/webservices/reliable/ReliableClientImpl.java">

<clientgen
wsdl="http://${wls.destination.host}:${wls.destination.port}/ReliableHelloWorld/ReliableHelloWorld?WSDL"
packageName="examples.webservices.reliable"/>

</jws>

</jwsc>

</target>

jwsc Antタスクの完全なクラス名を定義するには、taskdef Antタスクを使用します。

クライアントWebサービスをコンパイルするjwsc Antタスクを更新して、<jws>要素の<clientgen>子要素を含めます。これにより、デプロイされたReliableHelloWorld WebサービスのJAX-RPCスタブが生成およびコンパイルされるようになります。jwsc Antタスクでは、これらのスタブが生成されたWARファイルに自動的にパッケージ化されるため、即座にクライアントWebサービスからアクセスできるようになります。このようにするのは、生成されたクラスの1つをReliableClientImpl JWSファイルでインポートして使用するためです。

信頼性のあるメッセージングとMTOMの使用

次に、信頼性のあるWebサービスを実装し、MTOM/XOPを使用してSOAPメッセージ内のxs:base64Binary型のXMLデータの転送を最適化する簡単なJWSファイルの例を示します。コーディング・ガイドラインとして、サンプル・コードの後の説明を参照してください。このガイドラインはJavaコード内の太字部分に対応しています。このサンプルは、「信頼性のあるWebサービスを呼び出すJWSファイルに関するプログラミングのガイドライン」のサンプルを元に作成しています。

package examples.webservices.reliable;

import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.jws.Oneway;
import weblogic.jws.WLHttpTransport;

import weblogic.jws.ReliabilityBuffer;
import weblogic.jws.BufferQueue;
import weblogic.jws.Policy;
import weblogic.jws.Policies;

/**
* Simple reliable Web Service.
*/

@WebService(name="ReliableHelloWorldPortType",
serviceName="ReliableHelloWorldService")

@WLHttpTransport(contextPath="ReliableHelloWorld",
serviceUri="ReliableHelloWorld",
portName="ReliableHelloWorldServicePort")

@Policies({@Policy(uri="ReliableHelloWorldPolicy.xml",
direction=Policy.Direction.both,
attachToWsdl=true),
@Policy(uri = "policy:Mtom.xml")})

@BufferQueue(name="webservices.reliable.queue")

public class ReliableHelloWorldImpl {

@WebMethod()
@Oneway()
@ReliabilityBuffer(retryCount=10, retryDelay="10 seconds")

public void helloWorld(String input) {
System.out.println(" Hello World " + input);

}

@WebMethod

public byte[] echoBinary(byte[] bytes) {
return bytes;
}
}

MTOMを使用して信頼性のあるWebサービスを呼び出すJWSファイルをプログラミングする際は、次のガイドラインに従います。ガイドラインのサンプル・コードは、前述のサンプル内では太字で示されています。

- あらかじめパッケージ化されているMtom.xmlファイルを現在のWebサービスに適用するには、@weblogic.jws.Policyアノテーションを使用します。複数のWS-Policyファイル(信頼性のあるメッセージング・ポリシー・ファイルやMTOMポリシー・ファイルを含む)をグループ化するには、@weblogic.jws.Policiesアノテーションを使用します。

@Policies({@Policy(uri="ReliableHelloWorldPolicy.xml",
direction=Policy.Direction.both,
attachToWsdl=true),
@Policy(uri = "policy:Mtom.xml")})

- 結果として得られるSOAPメッセージでMTOM/XOPを使用してバイナリ・データの送受信を行う場合は必ず、Webサービス操作でJava byte[]データ型を戻り値または入力パラメータとして使用します。

public byte[] echoBinary(byte[] bytes) {
return bytes;
}

注意:
このリリースのWebLogic Serverでは、MTOM/XOP使用時にサポートされるJavaデータ型はbyte[]のみです。その他のバイナリ・データ型(imageなど)はサポートされていません。

信頼性のあるWebサービスを再デプロイする際にクライアント側で考慮すべき事項

WebLogic Serverでは、本番用の再デプロイメントがサポートされています。つまり、信頼性のあるWebLogic Webサービスの更新後の新しいバージョンを、同じWebサービスの古いバージョンと並行してデプロイできます。

WebLogic Serverでは、新しいクライアントのリクエストのみが新しいバージョンに転送されるように、クライアント接続が自動的に管理されます。再デプロイメント時にすでにWebサービスに接続していたクライアントは、作業が完了するまで古いバージョンのサービスを使用し続け、それらの作業が完了した時点で、WebLogic Serverが古いWebサービスを自動的にリタイアします。クライアントが信頼性のあるWebサービスに接続されている場合は、既存の信頼性のあるメッセージ・シーケンスがクライアントによって明示的に終了されるか、またはタイムアウトになったときに、そのクライアントの作業が完了したとみなされます。

本番用の再デプロイメントおよびWebサービス・クライアントに関する追加情報は、Webサービスを再デプロイする際にクライアント側で考慮すべき事項に関する項を参照してください。

信頼性のあるメッセージングとプロキシ・サーバーの使用

信頼性のあるWebサービスを呼び出すクライアント・アプリケーションでは、直接操作を呼び出すのではなく、プロキシ・サーバーを使用することがあります。プロキシを使用する理由としては、ファイアウォールの存在や、呼び出されたWebサービスのクラスタへのデプロイメントなどがあります。

この場合、呼び出されたWebサービスをホストするWebLogic Serverインスタンスは、プロキシ・サーバーのアドレスとポートで構成する必要があります。Webサービスがクラスタにデプロイされている場合は、そのクラスタ内のすべてのサーバーを構成することが必要です。

この手順では、ネットワーク接続を管理するための構成可能なWebLogic Serverの主要リソースであるネットワーク・チャネルの作成方法について説明します。ネットワーク・チャネルにより、クラスタのフロントエンド・アドレスにアクセスするための一貫性のある方法を提供できます。ネットワーク・チャネルの詳細は、『Oracle WebLogic Serverサーバー環境の管理』のネットワーク・チャネルの理解に関する項を参照してください。

各サーバー・インスタンスについて、以下の手順を実行します。

1. Webサービスの呼出しに使用するプロトコル用のネットワーク・チャネルを作成します。ネットワーク・チャネルの名前は、weblogic-wsee-proxy-channel-XXXとする必要があります(XXXはプロトコルを表します)。たとえば、HTTPS用のネットワーク・チャネルを作成する場合、weblogic-wsee-proxy-channel-httpsという名前にします。
ネットワーク・チャネルの作成に関する一般情報は、Oracle WebLogic Server管理コンソール・オンライン・ヘルプのカスタム・ネットワーク・チャネルの構成に関する項を参照してください。

2. 「外部リスニング・アドレス」および「外部リスニング・ポート」フィールドを、それぞれプロキシ・サーバーのアドレスおよびポートで更新して、ネットワーク・チャネルを構成します。

3. -Dweblogic.wsee.skip.async.response=true Javaシステム・プロパティを使用してWebLogic Serverインスタンスを起動することによって、WebLogic Serverプロキシ・サーバー上の非同期レスポンス・サービスを無効にします。
デフォルトでは、すべてのWebLogic Serverインスタンスに、非同期リクエスト-レスポンス機能を処理する内部非同期Webサービスがデプロイされます。このシステム・プロパティを指定しない場合、プロキシ・サーバー上の非同期サービスが非同期メッセージを消費するため、非同期メッセージは要求したとおりにクラスタに到着しません。

9 会話型Webサービスの作成

この章では、会話型のWebLogic Java API for XML-based RPC (JAX-RPC) Webサービスの作成方法について説明します。

この章の内容は次のとおりです。

- 会話型Webサービスの概要

- 会話型Webサービスの作成: 主な手順

- 会話型JWSファイルに関するプログラミングのガイドライン

- 会話型Webサービスを呼び出すJWSファイルに関するプログラミングのガイドライン

- ConversationUtilsユーティリティ・クラス

- 会話型Webサービスのクライアント用build.xmlファイルの更新

- 会話型Webサービスを呼び出すためのスタンドアロンJavaクライアントの更新

- 会話型Webサービスの.NETクライアントの例

- 会話型Webサービスを再デプロイする際にクライアント側で考慮すべき事項

会話型Webサービスの概要

Webサービスと、そのWebサービスを呼び出すクライアント・アプリケーションは、1つのタスクを完了するために複数回通信する場合があります。また、複数のクライアント・アプリケーションが同時に同じWebサービスと通信する場合もあります。会話を使用すると、直接的な方法で、呼出し間のデータを追跡して、Webサービスが常に正しいクライアントに応答するようにできます。

会話を使用すると、複数の通信にわたってデータを維持することに伴う以下の2つの問題が解決されます。

- 会話では、1つのクライアント・アプリケーションと1つのWebサービスの間の双方向通信が一意に識別されるので、メッセージが常に正しいクライアントに戻されます。たとえば、ショッピング・カート・アプリケーションでは、どのショッピング・カートがどの顧客に属するかを会話型Webサービスが追跡します。会話型Webサービスでは、クライアント・アプリケーションとの間で新しい会話が始まるたびに、一意の会話IDを作成することによって、これを実現しています。

- 会話によってWebサービスへの呼出し間の状態を保持します。つまり、サービスに対する呼出し間の特定のクライアント・アプリケーションに関連付けられているデータを追跡します。会話を使用すると、特定のクライアントに関連付けられているデータは、必要がなくなるまで、または処理が完了するまで、確実に保存されます。たとえば、ショッピング・カート・アプリケーションでは、顧客がショッピングを続けている間、ショッピング・カートに入っている品物を会話型Webサービスが記憶します。状態の保持はまた、会話中にWebサービスをホストするコンピュータで発生した障害に対処するためにも必要です。すべての状態関連データがディスクに永続化されるので、コンピュータが再起動すれば、クライアント・アプリケーションとの会話を続行できます。

WebLogic Serverはこの一意のIDと状態を、クライアント・アプリケーションが新しく会話を開始するたびに会話コンテキストを作成することによって管理します。Webサービスがその後、このコンテキストを使用して、サービスとの間の呼出しを相関させ、状態関連データを永続化します。

クライアント・アプリケーションとWebサービスの間の会話には、3つの異なるフェーズがあります。

- 開始: クライアント・アプリケーションが、会話型Webサービスの開始操作を呼び出すことによって、会話を開始します。次にそのWebサービスが、新しい会話コンテキストおよびそれに伴う一意のIDを作成し、アイドル時間と会話の存続期間を計測する内部タイマーを起動します。

- 続行: クライアント・アプリケーションは会話を開始した後、1つ以上の続行操作を呼び出して会話を続行します。会話型Webサービスでは、呼出しに関連付けられたIDを使用して、会話しているクライアント・アプリケーション、永続化する状態、およびリセットするアイドル・タイマーを判断します。通常の続行操作は、クライアント・アプリケーションからさらに情報をリクエストするものや、ステータスをリクエストするものなどです。

- 終了: クライアント・アプリケーションは、会話が終了すると明示的に終了操作を呼び出します。Webサービスがその後、その会話と関連付けられたすべてのデータまたはリソースを、削除済としてマークします。

会話は通常、2つのWebLogic Webサービス間で発生します。そのうち1つは会話型としてマークされ、開始、続行、および終了の操作を定義し、もう1つのWebサービスは@ServiceClientアノテーションを使用して、それが会話型Webサービスのクライアントであることを指定します。また、制限事項はありますが、会話型WebサービスはスタンドアロンJavaクライアントからも呼び出せます。

他のWebLogic Webサービスの機能と同様に、Webサービスを会話型のものとして指定するには、JWSアノテーションを使用します。

注意:
会話型Webサービスを呼び出すクライアントWebサービスは、必ずしも会話型にする必要はありません。ただし、クライアントが会話型でない場合は、このクライアントの複数のインスタンスが同じ会話型Webサービス・スタブにアクセスする危険性があり、保存されている会話状態が破損するおそれがあります。この危険性があると判断した場合は、クライアントWebサービスも会話型になるように指定してください。その場合は、スタンドアロンのJavaクライアントは使用できません。これは、WebLogic APIを使用して会話型であることを指定する方法がないためです。
会話型Webサービス自体は、必ず1回、メッセージの配信が行われることや、メッセージが順序どおりに配信されることを保証するものではありません。そのようなメッセージ配信保証が必要であれば、Webサービスに信頼性があることも指定する必要があります。「Webサービスの信頼性のあるメッセージングの使用:主な手順」および第11章「非同期機能の併用」を参照してください。

会話型Webサービスの作成: 主な手順

次の手順では、会話型Webサービス、ならびにクライアントWebサービスおよびスタンドアロンJavaクライアント・アプリケーション(いずれも会話を開始および実施するもの)を作成する方法について説明します。この手順では、2つのWebサービスを実装するJWSファイルをゼロから作成する方法を示しています。既存のJWSファイルを更新する場合は、この手順をガイドとして利用することもできます。

Antベースの開発環境を設定済であり、かつjwsc Antタスクを実行して生成された会話型Webサービスをデプロイするためのターゲットを追加できる、作業用のbuild.xmlファイルがあることが前提となっています。さらに、会話を開始するクライアントWebサービスをホストする、WebLogic Serverインスタンスを同様に設定してあることも前提となっています。詳細は、次の項を参照してください。

- 「JAX-RPC Webサービス開発者向けサンプル」

- 「JAX-RPC Webサービスの開発」

- JWSファイルのプログラミング

- 「JAX-RPC Webサービス・クライアントの開発」

表9-1 会話型Webサービスの作成手順

#

手順

説明

1

会話型Webサービスを実装する、新しいJWSファイルを作成するか、既存のJWSファイルを更新します。

使い慣れたIDEまたはテキスト・エディタを使用します。「会話型JWSファイルに関するプログラミングのガイドライン」を参照してください。

2

build.xmlファイルを更新して、会話型JWSファイルをWebサービスにコンパイルするjwsc Antタスクの呼出しを含めます。

「jwsc WebLogic WebサービスAntタスクの実行」を参照してください。

3

Antターゲットを実行して、会話型Webサービスをビルドします。

例:

prompt> ant build-mainService

4

ターゲットWebサービスを通常どおりデプロイします。

「WebLogic Webサービスのデプロイとアンデプロイ」を参照してください。

5

クライアントWebサービスを実装する、新しいJWSファイルを作成するか、既存のJWSファイルを更新します。

クライアント・アプリケーションがスタンドアロンJavaクライアントである場合は、「会話型Webサービスを呼び出すためのスタンドアロンJavaクライアントの更新」を参照してください。手順6 - 9をスキップします。

クライアント・アプリケーション自体がWebサービスである場合は、ステップ6 - 9に従います。

6

会話型Webサービスで会話を開始および実施する新しいJWSファイルを作成するか、既存のJWSファイルを更新します。

使い慣れたIDEまたはテキスト・エディタを使用します。クライアントWebサービスが、会話型Webサービスをホストするものとは別のWebLogic Serverインスタンスにデプロイされていることが前提となります。「会話型Webサービスを呼び出すJWSファイルに関するプログラミングのガイドライン」を参照してください。

7

クライアントWebサービスをビルドするbuild.xmlファイルを更新します。

「会話型Webサービスのクライアント用build.xmlファイルの更新」を参照してください。

8

Antターゲットを実行して、クライアントWebサービスをビルドします。

例:

prompt> ant build-clientService

9

クライアントWebサービスを通常どおりデプロイします。

「WebLogic Webサービスのデプロイとアンデプロイ」を参照してください。

会話型JWSファイルに関するプログラミングのガイドライン

次のサンプルでは、会話型Webサービスを実装する簡単なJWSファイルを示します。太字で示されたJavaコードに対応するコーディングのガイドラインについては、サンプルの後の説明を参照してください。

package examples.webservices.conversation;

import java.io.Serializable;

import weblogic.jws.WLHttpTransport;
import weblogic.jws.Conversation;
import weblogic.jws.Conversational;
import weblogic.jws.Context;
import weblogic.wsee.jws.JwsContext;
import weblogic.wsee.jws.ServiceHandle;

import javax.jws.WebService;
import javax.jws.WebMethod;
@Conversational(maxIdleTime="10 minutes",
maxAge="1 day",
runAsStartUser=false,
singlePrincipal=false )
@WebService(name="ConversationalPortType",
serviceName="ConversationalService",
targetNamespace="http://examples.org/")

@WLHttpTransport(contextPath="conv",
serviceUri="ConversationalService",
portName="ConversationalServicePort")

/**
* Conversational web service.
*/

public class ConversationalServiceImpl implements Serializable {

@Context
private JwsContext ctx;
public String status = "undefined";

@WebMethod
@Conversation (Conversation.Phase.START)
public String start() {

ServiceHandle handle = ctx.getService();
String convID = handle.getConversationID();

status = "start";
return "Starting conversation, with ID " + convID + " and status equal to " + status;

}

@WebMethod
@Conversation (Conversation.Phase.CONTINUE)
public String middle(String message) {

status = "middle";
return "Middle of conversation; the message is: " + message + " and status is " + status;

}

@WebMethod
@Conversation (Conversation.Phase.FINISH)
public String finish(String message ) {

status = "finish";
return "End of conversation; the message is: " + message + " and status is " + status;

}

}

会話型Webサービスを実装するJWSファイルをプログラミングする際には、次のガイドラインに従います。ガイドラインのコード・スニペットは、前述のサンプルでは太字で示されています。

- 会話型Webサービスは、java.io.Serializableを実装している必要があるので、まずJWSファイルにクラスをインポートします。

import java.io.Serializable;

- 会話型JWSアノテーションをインポートします。

import weblogic.jws.Conversation;
import weblogic.jws.Conversational;

- 会話型Webサービスの実行時情報にアクセスする場合は、@ContextアノテーションおよびコンテキストAPIをインポートします。

import weblogic.jws.Context;

import weblogic.wsee.jws.JwsContext;
import weblogic.wsee.jws.ServiceHandle;

- クラス・レベルの@Conversationalアノテーションを使用して、Webサービスが会話型であると指定します。このアノテーションはオプションですが(メソッド・レベルの@Conversationアノテーションを指定していると仮定した場合)、常にこれをJWSファイル内で使用して、Webサービスが会話型であると明確に指定することをお薦めします。
指定するオプション属性は、WebLogic Serverが会話を終了するまでの、Webサービスがアイドル状態でいられる最大時間maxIdleTime、会話の最大存続期間maxAge、既存の会話の続行フェーズと終了フェーズを、会話を開始したユーザーとして実行するかどうかを示すrunAsStartUser、会話を開始したユーザー以外のユーザーが、会話の続行フェーズと終了フェーズの実行を許可されるかどうかを示すsinglePrincipalのうちのいずれかです。

@Conversational(maxIdleTime="10 minutes",
maxAge="1 day",
runAsStartUser=false,
singlePrincipal=false )

JWSファイルに@Conversationalアノテーションが含まれている場合、Webサービスのすべての操作が会話型です。操作のデフォルトのフェーズは、明示的に@Conversationアノテーションが指定されていなければ、続行フェーズです。ただし、会話型Webサービスには、1つ以上の開始操作と、1つの終了操作が含まれていることが必要なので、メソッド・レベルの@Conversationアノテーションを使用して、これらの操作をどのメソッドで実装するかを指定する必要があります。

属性のデフォルト値の詳細は、『Oracle WebLogic Server WebLogic Webサービス・リファレンス』のweblogic.jws.Conversationalに関する項を参照してください。

- JWSファイルには、java.io.Serializableが実装されている必要があります。

public class ConversationalServiceImpl implements Serializable {

- Webサービスの実行時情報にアクセスするには、データ型weblogic.wsee.jws.JwsContextのプライベート・クラス変数に、フィールド・レベルの@Context JWSアノテーションを付けます。

@Context
private JwsContext ctx;

- @Conversationアノテーションを使用して、会話の開始、続行、および終了フェーズを実装するメソッドを指定します。会話には、1つ以上の開始操作と、1つの終了操作が必要です。続行操作は任意指定です。フェーズを指定するアノテーションには、Conversation.Phase.START、Conversation.Phase.CONTINUE、またはConversation.Phase.FINISHの各パラメータを使用します。次の例では、開始操作を指定しています。

@WebMethod
@Conversation (Conversation.Phase.START)
public String start() {...

@ConversationアノテーションでマークするJWSファイルのメソッドが1つのみの場合、Webサービス全体が会話型となり、各操作は、会話の一部とみなされます。これは、JWSファイルで任意指定のクラス・レベル@Conversationalアノテーションを使用していなかった場合でも当てはまります。@Conversationで明示的にアノテーション付きにされていないメソッドはすべて、デフォルトで続行操作となります。つまり、たとえばクライアント・アプリケーションが、それ以前に開始操作を呼び出していない状態でこれらの続行メソッドの1つを呼び出すと、Webサービスが実行時エラーを返すということです。

なお、スタンドアロンJavaクライアントから会話型Webサービスを呼び出す場合、開始操作はリクエスト-レスポンスであることが必要です。つまり、この操作に、@Oneway JWSアノテーションを付けることはできません。操作は、voidを返すことがあります。Webサービスを、WebLogic Serverで実行されているクライアント・アプリケーションからのみ呼び出す場合、この要件は適用されません。

詳細は、『Oracle WebLogic Server WebLogic Webサービス・リファレンス』のweblogic.jws.Conversationに関する項を参照してください。

- Webサービスの実行時情報を取得するには、JwsContextインスタンスを使用します。
たとえば、開始操作の次のコードでは、WebLogic Serverが新しい会話に割り当てるIDを取得します。

ServiceHandle handle = ctx.getService();
String convID = handle.getConversationID();

会話型Webサービスを呼び出すJWSファイルに関するプログラミングのガイドライン

次の例では、「会話型JWSファイルに関するプログラミングのガイドライン」で説明した会話型Webサービスを呼び出すWebサービス用の簡単なJWSファイルを示します。太字で示されたJavaコードに対応するコーディングのガイドラインについては、サンプルの後の説明を参照してください。

package examples.webservices.conversation;

import weblogic.jws.WLHttpTransport;
import weblogic.jws.ServiceClient;

import weblogic.wsee.conversation.ConversationUtils;

import javax.jws.WebService;
import javax.jws.WebMethod;

import javax.xml.rpc.Stub;

import examples.webservices.conversation.ConversationalPortType;

import java.rmi.RemoteException;

@WebService(name="ConversationalClientPortType",
serviceName="ConversationalClientService",
targetNamespace="http://examples.org/")

@WLHttpTransport(contextPath="convClient",
serviceUri="ConversationalClient",
portName="ConversationalClientPort")

/**
*  client that has a conversation with the ConversationalService.
*/

public class ConversationalClientImpl {

@ServiceClient(
wsdlLocation="http://localhost:7001/conv/ConversationalService?WSDL",
serviceName="ConversationalService",
portName="ConversationalServicePort")

private ConversationalPortType port;

@WebMethod
public void runConversation(String message) {

try {

// Invoke start operation
String result = port.start();
System.out.println("start method executed.");
System.out.println("The message is: " + result);

// Invoke continue operation
result = port.middle(message );
System.out.println("middle method executed.");
System.out.println("The message is: " + result);

// Invoke finish operation
result = port.finish(message );
System.out.println("finish method executed.");
System.out.println("The message is: " + result);
ConversationUtils.renewStub((Stub)port);

}
catch (RemoteException e) {
e.printStackTrace();
}

}

}

会話型Webサービスを呼び出すJWSファイルをプログラミングする際には、次のガイドラインに従います。ガイドラインのコード・スニペットは、前述のサンプルでは太字で示されています。

- @ServiceClient JWSアノテーションをインポートします。

import weblogic.jws.ServiceClient;

- 必要に応じて、会話をさらに構成するためのWebLogicユーティリティ・クラスをインポートします。

import weblogic.wsee.conversation.ConversationUtils;

- 呼び出す会話型Webサービスのポート・タイプのJAX-RPCスタブをインポートします。実際のスタブそのものは、後でjwsc Antタスクによって作成されます。スタブ・パッケージは、<jws>の子要素<clientgen>のpackageName属性によって指定され、スタブの名前は呼び出されたWebサービスのWSDLによって決まります。

import examples.webservices.conversation.ConversationalPortType;

- JWSファイルの本文で、@ServiceClient JWSアノテーションを使用して、呼び出す会話型WebサービスのWSDL、名前、およびポートを指定します。このアノテーションは、プライベート変数のフィールド・レベルで指定します。この変数のデータ型は、呼び出しているWebサービスのJAX-RPCポート・タイプとなります。

@ServiceClient(
wsdlLocation="http://localhost:7001/conv/ConversationalService?WSDL",
serviceName="ConversationalService",
portName="ConversationalServicePort")

private ConversationalPortType port;

- @ServiceClientアノテーションを付けたスタブを使用して、会話型Webサービスの開始操作を呼び出し、会話を開始します。開始メソッドは、JWSファイルの任意の場所(コンストラクタ、メソッドなど)から呼び出せます。

String result = port.start();

- 必要に応じて続行メソッドを呼び出し、会話を続行します。開始したものと同じ会話が続行されるよう、必ず同じスタブ・インスタンスを使用します。

result = port.middle(message );

- 会話が完了したら、会話型Webサービスが現在の会話に使用していたリソースを解放できるよう、終了操作を呼び出します。

result = port.finish(message );

- Webサービスの会話スタブを再利用して新しい会話を開始するには、weblogic.wsee.conversation.ConversationUtilsユーティリティ・クラスのrenewStub()メソッドを使用して、そのスタブを明示的に更新する必要があります。

ConversationUtils.renewStub((Stub)port);

注意:
会話型Webサービスを呼び出すクライアントWebサービスは、必ずしも会話型にする必要はありません。ただし、クライアントが会話型でない場合は、このクライアントの複数のインスタンスが同じ会話型Webサービス・スタブにアクセスする危険性があり、保存されている会話状態が破損するおそれがあります。この危険性があると判断した場合は、クライアントWebサービスも会話型になるように指定してください。

ConversationUtilsユーティリティ・クラス

WebLogic Serverには、会話機能で使用するユーティリティ・クラスが用意されています。このクラスを使用すると、会話IDの取得や設定、構成オプションの設定といった一般的なタスクを実行できます。これらのタスクには、会話型Webサービス内で実行するものと、会話型Webサービスを呼び出すクライアント内で実行するものがあります。このクラスの使用例については、「会話型Webサービスを呼び出すJWSファイルに関するプログラミングのガイドライン」を参照してください。

会話型Webサービスのクライアント用build.xmlファイルの更新

build.xmlファイルを更新して、会話型Webサービスを呼び出すJWSファイルを生成するには、次のサンプルのようなtaskdefsおよびbuild-clientServiceターゲットを追加します。詳細は、サンプルの後の説明を参照してください。

<taskdef name="jwsc"
classname="weblogic.wsee.tools.anttasks.JwscTask" />

<target name="build-clientService">

<jwsc
enableAsyncService="true"
srcdir="src"
destdir="${clientService-ear-dir}" >

<jws file="examples/webservices/conversation/ConversationalClientImpl.java" >
<clientgen
wsdl="http://${wls.hostname}:${wls.port}/conv/ConversationalService?WSDL"
packageName="examples.webservices.conversation"/>

</jws>

</jwsc>

</target>

jwsc Antタスクの完全なクラス名を定義するには、taskdef Antタスクを使用します。

クライアントWebサービスをコンパイルするjwsc Antタスクを更新して、<jws>要素の<clientgen>子要素を含めます。これにより、デプロイされたConversationalService WebサービスのJAX-RPCスタブが生成およびコンパイルされるようになります。jwsc Antタスクでは、これらのスタブが生成されたWARファイルに自動的にパッケージ化されるため、即座にクライアントWebサービスからアクセスできるようになります。このようにするのは、生成されたクラスの1つをConversationalClientImpl JWSファイルでインポートして使用するためです。

会話型Webサービスを呼び出すためのスタンドアロンJavaクライアントの更新

次の例では、「会話型JWSファイルに関するプログラミングのガイドライン」で説明した会話型Webサービスを呼び出す、簡単なスタンドアロンのJavaクライアントを示します。太字で示されたJavaコードに対応するコーディングのガイドラインについては、サンプルの後の説明を参照してください。

package examples.webservices.conv_standalone.client;

import java.rmi.RemoteException;

import javax.xml.rpc.ServiceException;
import javax.xml.rpc.Stub;
import weblogic.wsee.jaxrpc.WLStub;

/**
* stand-alone client that invokes and converses with ConversationlService.
*/

public class Main {

public static void main(String[] args)
throws ServiceException, RemoteException{

ConversationalService service = new ConversationalService_Impl(args[0] + "?WSDL");
ConversationalPortType port = service.getConversationalServicePort();

// Set property on stub to specify that client is invoking a web service
// that uses advanced features; this property is automatically set if
// the client runs in a WebLogic Server instance.

Stub stub = (Stub)port;
stub._setProperty(WLStub.COMPLEX,  "true");

// Invoke start operation to begin the conversation
String result = port.start();
System.out.println("start method executed.");
System.out.println("The message is: " + result);

// Invoke continue operation
result = port.middle("middle" );
System.out.println("middle method executed.");
System.out.println("The message is: " + result);

// Invoke finish operation
result = port.finish("finish" );
System.out.println("finish method executed.");
System.out.println("The message is: " + result);

}

}

会話型Webサービスを呼び出すスタンドアロンJavaクライアントをプログラミングする際には、次のガイドラインに従います。ガイドラインのコード・スニペットは、前述のサンプルでは太字で示されています。

- weblogic.wsee.jaxrpc.WLStubクラスをインポートします。

import weblogic.wsee.jaxrpc.WLStub;

- _setPropertyメソッドを使用して、WLStub.ComplexプロパティをConversationalServiceのJAX-RPCスタブに対して設定します。

Stub stub = (Stub)port;
stub._setProperty(WLStub.COMPLEX,  "true");

このプロパティは、クライアントが高度なWebサービス(この場合は会話型Webサービス)を呼び出すことをWebサービスのランタイムに対して指定します。このプロパティは、別のWebLogic Webサービスから会話型Webサービスを呼び出している場合には、自動的に設定されます。

- 会話型Webサービスの開始操作を呼び出して、会話を開始します。

String result = port.start();

- 必要に応じて続行メソッドを呼び出し、会話を続行します。

result = port.middle(message );

- 会話が完了したら、会話型Webサービスが現在の会話に使用していたリソースを解放できるよう、終了操作を呼び出します。

result = port.finish(message );

会話型Webサービスの.NETクライアントの例

この項では、会話型WebLogic Webサービスの.NET WSE3.0クライアントを作成する方法について説明します。この例には次のファイルが含まれています。

- ConversationService.java -- @Conversationおよび@Callbackアノテーションを使用して会話型Webサービスを実装するJWSファイル。ConversationService.javaは、コールバックを介してクライアントに結果を通知することもできます(オプション)。

- Service.cs -- ConversationService Webサービスのクライアントとして機能するConversationClient .NET WebサービスのC#ソース・ファイル。
このサンプル.NETクライアントは、ConversationServiceとの会話に参加できます。また、コールバックを介して結果を受け取ることも可能です。

- build.xml -- 会話型Webサービスをビルドおよびデプロイするためのターゲットを含むAntビルド・ファイル。

これらのファイルについては、以降の項で詳しく説明します。

ConversationService.javaファイル

サンプルのConversationService.javaファイルを例9-1に示します。このサンプルには、機能を説明するコメントが大量に含まれています。

例9-1 ConversationService.javaファイル

package conv;

import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.jws.Oneway;

import weblogic.jws.Conversation;
import weblogic.jws.Callback;
import weblogic.jws.CallbackService;

import java.io.Serializable;

/**
* Demonstrates use of the @Conversation annotation to manage the lifetime of the service
* and provide data persistence and message correlation.
*
* Remember that multiple clients might invoke a web service simultaneously.  When the
* web service stores data relevant to the client or calls additional services
* in order to process a client's request, the service must be able to process returned
* data from the external services in the context of the specific client it relates
* to.  This is all automatic when conversations are used.
*
* Remember that not all clients are capable of accepting callbacks.  Specifically,
* clients operating from behind firewalls may not be able to receive asynchronous
* callbacks.  You may wish to provide a synchronous interface, like this one,
* for such clients.  If a client can accept callbacks, it must send a callback endpoint refrence
* as part of any "start conversation" method invocation.
*
* To see the behavior in the Test View, invoke startRequest and then getRequestStatus
* several times quickly.
*/
@WebService(serviceName = "ConversationService", portName = "conversation", targetNamespace = "http://www.openuri.org/")
public class ConversationService implements Serializable {

@Callback
public CallbackInterface callback;
private boolean useCallbacks;
private int num;

/**
* Starts the conversation
*/
@Conversation(Conversation.Phase.START)
@WebMethod
public void startRequest(boolean useCallbacks) {
this.useCallbacks = useCallbacks;
}

@WebMethod
@Conversation(Conversation.Phase.CONTINUE)
public String getRequestStatus() {

num++;
if (num == 1)
return "This is the first time you call getRequestStatus method.";
if (num == 2 && useCallbacks) {
callback.onResultReady("finished");
return "This is the second time you call  getRequestStatus method, the conversation has been terminated automtically when the onResultReady callback method is invoked.";
} else
return "You have called getRequestStatus method " + num + " times";

}

/**
* Used to tell Conversation.jws that the current conversation is
* no longer needed.
*/
@WebMethod
@Conversation(Conversation.Phase.FINISH)
public void terminateRequest() {

}

@CallbackService(serviceName = "ConversationCallbackService")
public interface CallbackInterface {

/**
* Callback to invoke on the client when the external service
* returns its result. Will only be called it the client can
* accept callbacks and told us where to send them.
* <p/>
* If this callback is used, it implicitly terminates the
* conversation with no action required on the part of the
* client.
*/
@WebMethod
@Oneway
@Conversation(Conversation.Phase.FINISH)
public void onResultReady(String result);
}

}

Service.csファイル

サンプルのService.csファイルを例9-2に示します。

この会話プロキシ・ファイルは、Microsoft WSDL to Proxy ClassツールWseWsdl3.exe(http://msdn.microsoft.com/en-us/library/aa529578.aspxを参照)とConversationService WebサービスのWSDLファイルを使用して作成したものです。

このサンプルには、機能を説明するコメントが大量に含まれています。

例9-2 Service.csファイル

using System;
using System.Web;
using System.Web.Services;
using System.Web.Services.Protocols;
using System.Diagnostics;
using System.IO;
using System.Xml;
using Microsoft.Web.Services3.Addressing;
using Microsoft.Web.Services3;
using System.Collections.Generic;
using Microsoft.Web.Services3.Design;

[WebService(Namespace = "http://tempuri.org/")]
[WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1)]
public class Service : System.Web.Services.WebService
{

public Service () {

//Uncomment the following line if using designed components
//InitializeComponent();
}

/*
* start invokes the Conversation web service's startRequest
* operation.
*
* Since the Conversation web service is conversational,
* we must also persist the ReplyTo endpoint reference SOAP header
* for subsequent calls.
*
* Since the Conversation web service can optionally communicate
* the result of it's work via a callback, we must prepare a
* second SOAP header CallbackTo SOAP header, which is the endpoint reference
* of the recipient to which callbacks should be sent.
*/
[WebMethod(EnableSession = true)]
public void start(Boolean useCallbacks, Boolean useIPAddress)
{
/*
* The Conversation proxy was created using .NET WSE3.0's WseWsdl3.exe
* application and the Conversation.jws's WSDL file.  The WSDL
* file for any WLS web service may be obtained
* by hitting the web service's URL with "?WSDL" appended to
* the end.  For example:
*
* http://somehost:7001/samples/async/Conversation.jws?WSDL
*
* WseWsdl3.exe produces a C# proxy class.  Place the resulting
* ConversationService.cs file in your .NET project, then use Visual
* Studio's Project->Add Existing Item menu action to "import"
* the class into the project.
*/
ConversationServiceSoapBinding conv;
String callbackLocation;
int asmxIndex;

/*
* Construct the callback URL from various pieces of
* server and HttpRequest info.
*/
Uri requestUrl = Context.Request.Url;

if (useIPAddress)
{
/*
* if useIPAddress is true, construct the callback address
* with the IP address of this host.
*/
callbackLocation = requestUrl.Scheme + "://" + System.Net.Dns.GetHostByName(requestUrl.Host).AddressList[0] +
":" + requestUrl.Port + requestUrl.AbsolutePath;
}
else
{
/*
* if useIPAddress is false, construct the callback address
* with the hostname of this host.
*/
callbackLocation = requestUrl.Scheme + "://" + requestUrl.Host +
":" + requestUrl.Port + requestUrl.AbsolutePath;
}

// Remove everything after ".asmx"
asmxIndex = callbackLocation.IndexOf(".asmx") + 5;
callbackLocation = callbackLocation.Remove(asmxIndex,
callbackLocation.Length - asmxIndex);

/*
* Create an instance of the proxy for the Conversation
* web service.
*
*/
conv = new ConversationServiceSoapBinding();

/*
* When callback is enabled, a custom callback header should be added into
* the outbound soap message.
*
*/
if (useCallbacks)
enableSoapFilterToAddCallbackHeader(conv, callbackLocation);

/*
* Invoke the startRequest method of the web service. The
* single boolean parameter determines whether the Conversation
* web service will use callbacks to communicate the result
* back to this client.
*
* If the argument is true, an onResultReady callback will
* be sent when the result is ready.  This client must implement
* a method with that name that expects the message shape defined
* by the target web service (returns void and accepts a single
* string argument).  See the onResultReady method below.
*
* If the argument to startRequest is false, callbacks will not
* be used and this client must use the getRequestStatus method
* to poll the Conversation web service for the result.
*/
conv.startRequest(useCallbacks);
/*
* Persist the ReplyTo header  in session state so that it can
* be used in other methods that take part in the conversation.
*
* This is not safe since one session could start multiple
* conversations, but there is no other apparent way to persist
* this information.  Member variables of WebService classes
* are not persisted across method invocations.
*/
Session["ConversationReplyTo"] = conv.ResponseSoapContext.Addressing.ReplyTo;

}

/* the CallbackTo header defintion isn't exposed by WLS9x/WLS10x callback service.
* So we need to use SOAPFilter to add the CallbackTo header.
*
*/
private static void enableSoapFilterToAddCallbackHeader(ConversationServiceSoapBinding conv, String callbackLocation)
{
//Create a custom policy.
Policy myPolicy = new Policy();
// Create a new policy assertion
MyPolicyAssertion myAssertion = new MyPolicyAssertion(callbackLocation);
// Add the assertion to the policy
myPolicy.Assertions.Add(myAssertion);
//Set the custom policy you have created on the client proxy
conv.SetPolicy(myPolicy);
}

/*
* getStatus invokes Conversation's getRequestStatus method.
* getRequestStatus is a polling method that is an alternative
* for web services that cannot recieve callbacks.
*
* Note that a conversation must be started with startRequest before
* this method may be invoked.  If not, or if this method is invoked
* outside of a conversation for any reason, it will get back a SOAP
* fault indicating that the conversation does not exist.
*/
[WebMethod(EnableSession = true)]
public String getStatus()
{
String result;

/*
* Create an instance of the proxy for the Conversation
* web service.  We could probably persist the proxy instance
* in session state, but chose not to.
*/
ConversationServiceSoapBinding conv = new ConversationServiceSoapBinding();

/*
* change the destination to the ReplyTo endpoint reference we cached on session state in
* the start method.
*/
conv.RequestSoapContext.Addressing.Destination = (EndpointReference)Session["ConversationReplyTo"];
/*
* Invoke the getRequestStatus method of the web service.
*/
result = conv.getRequestStatus();
return result;
}

/*
* finish invokes Conversation's terminateRequest method, which
* terminates the current conversation.
*
* Note that a conversation must be started with startRequest before
* this method may be invoked.  If not, or if this method is invoked
* outside of a conversation for any reason, it will get back a SOAP
* fault indicating that the conversation does not exist.
*/
[WebMethod(EnableSession = true)]
public void finish()
{
/*
* Create an instance of the proxy for the Conversation
* web service.  We could probably persist the proxy instance
* in session state, but chose not to.
*/
ConversationServiceSoapBinding conv = new ConversationServiceSoapBinding();

/*
* change the destination to the ReplyTo endpoint reference we cached on session state in
* the start method. Both "continue" and "finish" methods use the same destination.
*/
conv.RequestSoapContext.Addressing.Destination = (EndpointReference)Session["ConversationReplyTo"];
/*
* Invoke the terminateRequest method of the web service.
*/
conv.terminateRequest();
}

/*
* onResultReady is a callback handler for the onResultReady
* callback that Conversation.jws can optionally use to return
* its results.
*
* .NET WSE3.0 does not support callbacks directly, but a callback is just
* a method invocation message.  So if you construct a WebMethod with
* the same signature as the callback and set the XML namespace
* properly, it serves as a callback handler.
*
*/
[WebMethod]
[SoapDocumentMethod(OneWay = true,
Action = "http://www.openuri.org/ConversationService_CallbackInterface/onResultReady",
RequestElementName = "http://www.openuri.org/",
ResponseNamespace = "http://www.openuri.org/"
)]
public void onResultReady(String result)
{
/*
* When the callback is invoked, log a message to the
* hardcoded file c:\temp\ConversationClient.log.
*
* Note: if c:\temp does not exist on this server, an
* Exception will be raised.  Since it is not handled here,
* it will be returned as a SOAP fault to the Conversation
* web service.
*/
TextWriter output;
output = File.AppendText("c:\\temp\\ConversationClient.log");
String msg = "[" + DateTime.Now.ToString() + "] callback received";
output.WriteLine(msg);
output.Flush();
output.Close();
}

}

public class MyFilter : Microsoft.Web.Services3.SoapFilter
{
private String callbackLocation;

public MyFilter(String callbackLocation)
{
this.callbackLocation = callbackLocation;
}

public override SoapFilterResult ProcessMessage(SoapEnvelope envelope)
{

//create the CallbackTo soap element.
XmlDocument xmldoc = new XmlDocument();
XmlElement xmlEle = xmldoc.CreateElement("callback", "CallbackTo", "http://www.openuri.org/2006/03/callback");

//create the CallbackTo endpoint reference.
Address callbacto = new Address(new Uri(callbackLocation));
XmlElement xmlEle2 =new EndpointReference(callbacto).GetXml(xmldoc);
//add the CallbackTo endpoint reference into CallbackTo SOAP element.
xmlEle.AppendChild(xmlEle2.FirstChild);
//add the whole CallbackTo SOAP element into SOAP header.
XmlNode callbackheader = envelope.ImportNode(xmlEle, true);
envelope.DocumentElement.FirstChild.AppendChild(callbackheader);
return SoapFilterResult.Continue;

}
}

public class MyPolicyAssertion : Microsoft.Web.Services3.Design.PolicyAssertion
{
private String callbackLocation;

public MyPolicyAssertion(String callbackLocation)
{
this.callbackLocation = callbackLocation;
}

public override  SoapFilter CreateClientInputFilter(FilterCreationContext context)
{
return null;
}

public override  SoapFilter CreateClientOutputFilter(FilterCreationContext context)
{
//use MyFilter to add the CallbackTo header in the outbound soap message.
return new MyFilter(callbackLocation);
}

public override  SoapFilter CreateServiceInputFilter(FilterCreationContext context)
{
return null;
}

public override  SoapFilter CreateServiceOutputFilter(FilterCreationContext context)
{
return null;
}

}

build.xmlファイル

サンプルのbuild.xmlファイルを例9-3に示します。

build.xmlは、サンプル・ソース・ファイルを新しいORACLE_HOME\wlserver\samples\server\examples\src\examples\webservices\convディレクトリにコピーすることを前提としています。ORACLE_HOMEは、WebLogic Serverがインストールされているディレクトリです。WebLogic Serverのサンプル・コードの詳細は、『Oracle WebLogic Serverの理解』のサンプル・アプリケーションとサンプル・コードに関する項を参照してください。

build.xmlを使用するには、まずORACLE_HOME\user_projects\domains\wl_server>setExamplesEnv.cmd(shを実行してサンプルの環境を正しく設定し、サンプルのサーバーを開始しておくことも必要です。

このサンプルには、ビルド・ファイルの機能を説明するコメントとターゲットが含まれています。

例9-3 build.xmlファイル

<?xml version="1.0" encoding="ISO-8859-1"?>
<project name="webservices.conversation" default="all" basedir=".">

<!-- set global properties for this build -->
<property file="../../../examples.properties"/>

<property name="client.dir" value="${client.classes.dir}/webservices_conversation" />
<property name="package.dir" value="examples/webservices/conv"/>
<property name="package" value="examples.webservices.conv"/>
<property name="ear.dir" value="${examples.build.dir}/webservicesConversationEar" />

<path id="client.class.path">
<pathelement path="${java.class.path}"/>
</path>

<!-- Web service WLS Ant task definitions -->
<taskdef name="jwsc"
classname="weblogic.wsee.tools.anttasks.JwscTask" />
<taskdef name="clientgen"
classname="weblogic.wsee.tools.anttasks.ClientGenTask" />

<target name="all" depends="build, deploy"/>

<target name="clean">
<delete dir="${ear.dir}"/>
</target>

<!-- Target that builds the conversational  web service -->
<target name="build" description="Target that builds the MTOM web service">
<jwsc
srcdir="${examples.src.dir}/${package.dir}"
sourcepath="${examples.src.dir}"
destdir="${ear.dir}"
classpath="${java.class.path}"
keepGenerated="true"
deprecation="${deprecation}"
debug="${debug}">
<jws file="ConversationService.java">
<WLHttpTransport contextPath="/samples/async" serviceURI="conversation.jws"/>
</jws>
</jwsc>
</target>

<!-- Target that deploys the conversational web service -->
<target name="deploy" description="Target that deploys the conversational web service">
<wldeploy
action="deploy"
source="${ear.dir}"
user="${wls.username}"
password="${wls.password}"
verbose="true"
adminurl="t3://${wls.hostname}:${wls.port}"
targets="${wls.server.name}"
failonerror="${failondeploy}"/>
</target>

<!-- Target that undeploys the conversational web service -->
<target name="undeploy" description="Target that deploys the conversational web service">
<wldeploy
action="undeploy"
name="webservicesConversationEar"
user="${wls.username}"
password="${wls.password}"
verbose="true"
adminurl="t3://${wls.hostname}:${wls.port}"
targets="${wls.server.name}"
failonerror="${failondeploy}"/>
</target>

</project>

会話型Webサービスを再デプロイする際にクライアント側で考慮すべき事項

WebLogic Serverでは、本番再デプロイメントがサポートされています。つまり、会話型WebLogic Webサービスの更新後の新しいバージョンを、同じWebサービスの古いバージョンと並行してデプロイできます。

WebLogic Serverでは、新しいクライアントのリクエストのみが新しいバージョンに転送されるように、クライアント接続が自動的に管理されます。再デプロイメント時にすでにWebサービスに接続していたクライアントは、作業が完了するまで古いバージョンのサービスを使用し続け、それらの作業が完了した時点で、WebLogic Serverが古いWebサービスを自動的にリタイアします。クライアントが会話型Webサービスに接続されている場合は、既存の会話がクライアントによって明示的に終了されるか、またはタイムアウトになったときに、そのクライアントの作業が完了したとみなされます。

本番再デプロイメントおよびWebサービス・クライアントに関する追加情報は、Webサービスを再デプロイする際にクライアント側で考慮すべき事項に関する項を参照してください。

10 バッファ付きWebサービスの作成

この章では、バッファ付きのWebLogic Java API for XML-based RPC (JAX-RPC) Webサービスの作成方法について説明します。

この章の内容は次のとおりです。

- バッファ付きWebサービスの概要

- バッファ付きWebサービスの作成: 主な手順

- バッファ付きWebサービスのホストWebLogic Serverインスタンスの構成

- バッファ付きJWSファイルに関するプログラミングのガイドライン

- バッファ付きWebサービスを呼び出すJWSファイルのプログラミング

- バッファ付きWebサービスのクライアント用build.xmlファイルの更新

バッファ付きWebサービスの概要

バッファ付き操作がクライアントによって呼び出されると、メソッド操作はJMSキューに渡され、WebLogic Serverは非同期にそれを処理します。Webサービスの信頼性のあるメッセージングの場合と同様に、メソッド呼出しがまだキューに入っているときにWebLogic Serverが停止しても、再起動すればすぐに処理が行われます。バッファ付きWebサービスを呼び出す際に、クライアントが呼出しからのレスポンスを待機しないので、クライアントの実行は続行可能です。

バッファ付きWebサービスの作成: 主な手順

次の手順では、バッファ付きWebサービスと、そのバッファ付きWebサービス操作を呼び出すクライアントWebサービスを作成する方法を説明しています。この手順では、2つのWebサービスを実装するJWSファイルをゼロから作成する方法を示しています。既存のJWSファイルを更新する場合は、この手順をガイドとして利用してください。この手順ではまた、バッファ付きWebサービスをホストするWebLogic Serverインスタンスを構成する方法も示しています。

注意:
非同期リクエスト-レスポンス機能を一緒に使用しているのでなければ、別のWebサービスからバッファ付きWebサービスを呼び出す必要はありません。これは、スタンドアロンJavaアプリケーションからも呼び出すことができます。

Antベースの開発環境を設定済であり、かつjwsc Antタスクを実行して生成されたバッファ付きWebサービスをデプロイするためのターゲットを追加できる、作業用のbuild.xmlファイルがあることが前提となっています。さらに、バッファ付きWebサービスを呼び出すクライアントWebサービスをホストする、WebLogic Serverインスタンスを同様に設定してあることも前提となっています。詳細は、次の項を参照してください。

- 「JAX-RPC Webサービス開発者向けサンプル」

- 「JAX-RPC Webサービスの開発」

- JWSファイルのプログラミング

- 「JAX-RPC Webサービス・クライアントの開発」

表10-1 バッファ付きWebサービスの作成手順

#

手順

説明

1

バッファ付きWebサービスをホストするWebLogic Serverインスタンスを構成します。

「バッファ付きWebサービスのホストWebLogic Serverインスタンスの構成」を参照してください。

2

バッファ付きWebサービスを実装する、新しいJWSファイルを作成するか、既存のJWSファイルを更新します。

使い慣れたIDEまたはテキスト・エディタを使用します。「バッファ付きJWSファイルに関するプログラミングのガイドライン」を参照してください。

3

build.xmlファイルを更新して、JWSファイルをバッファ付きWebサービスにコンパイルするjwsc Antタスクの呼出しを含めます。

例:

<jwsc
srcdir="src"
destdir="${service-ear-dir}" >
<jws
file="examples/webservices/async_buffered/AsyncBufferedImpl.java"
/>
</jwsc>

jwsc Antタスクの使用についての一般情報は、「jwsc WebLogic WebサービスAntタスクの実行」を参照してください。

4

適切なターゲットを呼び出してJWSファイルを再コンパイルしてから、WebLogic ServerにWebサービスを再デプロイします。

例:

prompt> ant build-clientService deploy-clientService

デプロイの詳細は、「WebLogic Webサービスのデプロイとアンデプロイ」を参照してください。

5

バッファ付きWebサービスを呼び出すクライアントWebサービスを実装する、新しいJWSファイルを作成するか、既存のJWSファイルを更新します。

「バッファ付きWebサービスを呼び出すJWSファイルのプログラミング」を参照してください。

6

クライアントWebサービスをビルドするbuild.xmlファイルを更新します。

「バッファ付きWebサービスのクライアント用build.xmlファイルの更新」を参照してください。

7

適切なターゲットを呼び出してクライアントJWSファイルを再コンパイルしてから、クライアントWebLogic ServerにWebサービスを再デプロイします。

例:

prompt> ant build-clientService deploy-clientService

デプロイの詳細は、「WebLogic Webサービスのデプロイとアンデプロイ」を参照してください。

バッファ付きWebサービスのホストWebLogic Serverインスタンスの構成

バッファ付きWebサービスのデプロイ先となるWebLogic Serverインスタンスを構成する際には、Webサービスのランタイムで内部的に使用される、JMSサーバーやモジュールなどのJMSリソースを構成します。

これらのリソースは手作業でも構成できますが、構成ウィザードで、Webサービス固有の拡張テンプレートを使用してWebLogic Serverドメインを拡張することもできます。構成ウィザードを使用すると、必要な構成手順を大幅に簡素化できます。詳細は、「Webサービス機能用のドメイン構成」を参照してください。

注意:
または、WLSTを使用してリソースを構成できます。WLSTを使用したドメインの拡張の詳細は、『WebLogic Scripting Toolの理解』の既存ドメインの構成に関する項を参照してください。
Webサービスのリソースを含まないドメインは、Webサービス以外のシナリオおよび非同期のリクエスト/レスポンスが含まれないWebサービス・シナリオにおいて、適切に起動および実行されます。ただし、サーバー・ログに、非同期リソースが構成されていないこと、およびWebサービスの非同期レスポンス・サービスが完全にデプロイされていないことを示すINFOメッセージが表示されます。

リソースを手作業で構成する場合、以下の手順を実行します。

表10-2 バッファ付きWebサービスのホストWebLogic Serverインスタンスを手作業で構成する手順

#

手順

説明

1

ホストWebLogic Serverインスタンスが格納されたドメインのWebLogic Server管理コンソールを起動します。

ブラウザでWebLogic Server管理コンソールを起動するには、次のURLを入力します。

http://host:port/console

各要素の説明は次のとおりです。

- hostは、管理サーバーが動作しているコンピュータを指します。

- portは、管理サーバーが接続リクエストをリスニングしているポート番号を指します。管理サーバーのデフォルトのポート番号は7001です。

『Oracle WebLogic Server WebLogic Webサービスの理解』の管理コンソールの起動に関する項を参照してください。

3

JMSサーバーを作成します。

JMSサーバーを作成します。JMSサーバーがすでに存在する場合は、新しいJMSサーバーを作成せずにそれを使用できます。

Oracle WebLogic Server管理コンソール・オンライン・ヘルプのJMSサーバーの作成に関する項を参照してください。

4

JMSモジュールを作成し、キューを定義します。

JMSモジュールを作成し、その中にJMSキューを定義します。JMSモジュールがすでに存在する場合は、新しいJMSモジュールを作成せずにそれを使用することもできます。JMSキューを、1つ前の手順で作成したJMSサーバーにターゲット指定します。このJMSキューがローカルであることを必ず指定してください(通常は、ローカルJNDI名の設定により指定できます)。Oracle WebLogic Server管理コンソール・オンライン・ヘルプのJMSシステム・モジュールの作成に関する項とシステム・モジュールのキューの作成に関する項を参照してください。

バッファ付きWebサービスで、デフォルトWebサービスのキューを使用する場合は、JMSキューのJNDI名をweblogic.wsee.DefaultCallbackQueueに設定します。そうせずに、別のJNDI名を使用する場合は、JWSファイル内で@BufferQueueアノテーションを使用して、このJNDI名を信頼性のあるWebサービスに対して指定する必要があります。「バッファ付きJWSファイルに関するプログラミングのガイドライン」を参照してください。

クラスタ化の考慮事項:

クラスタ内でWebサービスのバッファ機能を使用する場合は、次の作業を行う必要があります。

- JMSキューの作成時に、分散キューではなくローカルJMSキューを作成します。

- このJMSキューをクラスタ内の各サーバーに明示的にターゲット指定します。

4

必要に応じて、現在のドメイン環境をチューニングする(オプション)

『WebLogic Serverパフォーマンスおよびチューニング』の「Webサービスのパフォーマンスを向上させるために負荷が高いシステムのチューニング」を参照してください。

バッファ付きJWSファイルに関するプログラミングのガイドライン

次のサンプルでは、バッファ付きWebサービスを実装する簡単なJWSファイルを示します。太字で示されたJavaコードに対応するコーディングのガイドラインについては、サンプルの後の説明を参照してください。

package examples.webservices.buffered;

import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.jws.Oneway;

import weblogic.jws.WLHttpTransport;
import weblogic.jws.MessageBuffer;
import weblogic.jws.BufferQueue;

@WebService(name="BufferedPortType",
serviceName="BufferedService",
targetNamespace="http://example.org")

@WLHttpTransport(contextPath="buffered",
serviceUri="BufferedService",
portName="BufferedPort")

// Annotation to specify a specific JMS queue rather than the default
@BufferQueue(name="my.jms.queue")

/**
* Simple buffered Web Service.
*/

public class BufferedImpl {

@WebMethod()
@MessageBuffer(retryCount=10, retryDelay="10 seconds")
@Oneway()
public void sayHelloNoReturn(String message) {
System.out.println("sayHelloNoReturn: " + message);

}
}

バッファ付きWebサービスを実装するJWSファイルをプログラミングする際には、次のガイドラインに従います。ガイドラインのコード・スニペットは、前述のサンプルでは太字で示されています。

- バッファ付きWebサービスに使用されるJWSアノテーションをインポートします。

import javax.jws.Oneway;
import weblogic.jws.MessageBuffer;
import weblogic.jws.BufferQueue;

どのJWSアノテーションが必要かについては、以下の箇条書きを参照してください。

- 必要に応じて、クラス・レベルの@BufferQueue JWSアノテーションを使用し、バッファ付きの呼出しを処理する際にWebLogic Serverによって内部使用されるJMSキューのJNDI名を指定します。例:

@BufferQueue(name="my.jms.queue")

このJWSアノテーションを指定しなかった場合、WebLogic Serverは、デフォルトWebサービスJMSキュー(weblogic.wsee.DefaultQueue)を使用します。

デフォルトのJMSキューと、このアノテーションで指定されたキューの双方を作成してからでなければ、バッファ付きの操作を正常に呼び出すことはできません。詳細については、「バッファ付きWebサービスのホストWebLogic Serverインスタンスの構成」を参照してください。

- @MessageBuffer JWSアノテーションを使用し、バッファ付きWebサービス操作を指定します。アノテーションには、次の2つのオプション属性があります。

- retryCount: WebLogic ServerによるJMSキューからWebサービス実装へのメッセージ配信試行回数(デフォルトでは3)。

- retryDelay: サーバーが待機すべき再試行間隔(デフォルトでは5分)。

例:

@MessageBuffer(retryCount=10, retryDelay="10 seconds")

このアノテーションをクラス・レベルで使用すると、すべての操作をバッファ付きにすることを指定でき、メソッド・レベルで指定すると、どの操作をバッファ付きにするかを選択できます。

- バッファ付きWebサービス操作を同期的に呼び出す(すなわち、非同期リクエスト-レスポンス機能を使用しない)場合は、実装メソッドに@Onewayアノテーションを付けて、そのメソッドが一方向のものであることを指定する必要があります。つまり、メソッドは値を戻すことができず、明示的にvoidを戻すことになります。例:

@Oneway()
public void sayHelloNoReturn(String message) {

反対に、メソッドに@Onewayアノテーションが付いていなければ、非同期リクエスト-レスポンス機能を使用して呼び出す必要があります。操作の呼出し方法がわからない場合は、同期と非同期の2種類の操作を作成することを検討してください。

第7章「非同期リクエスト-レスポンスを使用したWebサービスの呼出し」と第11章「非同期機能の併用」を参照してください。

バッファ付きWebサービスを呼び出すJWSファイルのプログラミング

バッファ付きWebサービスは、スタンドアロンJavaアプリケーション(非同期リクエスト-レスポンスを使用していない場合)と別のWebサービスの双方から呼び出せます。ただし、他のWebLogic Webサービスの非同期機能とは異なり、クライアントWebサービスにおいて@ServiceClient JWSアノテーションは使用せず、その他のサービスと同じように呼び出します。詳細は、「別のWebサービスからのWebサービスの呼出し」を参照してください。

次のサンプルJWSファイルでは、BufferedService WebサービスのsayHelloNoReturn操作を呼び出す方法を示します。

package examples.webservices.buffered;

import java.rmi.RemoteException;
import javax.xml.rpc.ServiceException;

import javax.jws.WebService;
import javax.jws.WebMethod;

import weblogic.jws.WLHttpTransport;

import examples.webservices.buffered.BufferedPortType;
import examples.webservices.buffered.BufferedService_Impl;
import examples.webservices.buffered.BufferedService;

@WebService(name="BufferedClientPortType",
serviceName="BufferedClientService",
targetNamespace="http://examples.org")

@WLHttpTransport(contextPath="bufferedClient",
serviceUri="BufferedClientService",
portName="BufferedClientPort")

public class BufferedClientImpl {

@WebMethod()
public String callBufferedService(String input, String serviceUrl)
throws RemoteException {

try {

BufferedService service = new BufferedService_Impl(serviceUrl + "?WSDL");
BufferedPortType port = service.getBufferedPort();

// Invoke the sayHelloNoReturn() operation of BufferedService

port.sayHelloNoReturn(input);

return "Invoke went okay!";

} catch (ServiceException se) {

System.out.println("ServiceExcpetion thrown");
throw new RuntimeException(se);

}
}
}

バッファ付きWebサービスのクライアント用build.xmlファイルの更新

build.xmlファイルを更新して、バッファ付きWebサービス操作を呼び出すJWSファイルを生成するには、次のサンプルのようなtaskdefsおよびbuild-clientServiceターゲットを追加します。詳細は、サンプルの後の説明を参照してください。

<taskdef name="jwsc"
classname="weblogic.wsee.tools.anttasks.JwscTask" />

<target name="build-clientService">

<jwsc
enableAsyncService="true"
srcdir="src"
destdir="${clientService-ear-dir}" >

<jws file="examples/webservices/buffered/BufferedClientImpl.java">
<clientgen
wsdl="http://${wls.hostname}:${wls.port}/buffered/BufferedService?WSDL"
packageName="examples.webservices.buffered"/>

</jws>

</jwsc>

</target>

jwsc Antタスクの完全なクラス名を定義するには、taskdef Antタスクを使用します。

クライアントWebサービスをコンパイルするjwsc Antタスクを更新して、<jws>要素の<clientgen>子要素を含めます。これにより、デプロイされたBufferedService WebサービスのJAX-RPCスタブが生成およびコンパイルされるようになります。jwsc Antタスクでは、これらのスタブが生成されたWARファイルに自動的にパッケージ化されるため、即座にクライアントWebサービスからアクセスできるようになります。このようにするのは、生成されたクラスの1つをBufferedClientImpl JWSファイルでインポートして使用するためです。

11 非同期機能の併用

この章では、WebLogic Java API for XML-based RPC (JAX-RPC) Webサービスと非同期機能を併用する方法について説明します。

この章の内容は次のとおりです。

- 非同期機能の併用

- 信頼性のある会話型Webサービスを実装するJWSファイルの例

- 信頼性のある会話型Webサービスを非同期で呼び出すクライアントWebサービスの例

非同期機能の併用

ここまでの各項では、WebLogic Webサービスの非同期機能(Webサービスの信頼性のあるメッセージング、会話、非同期リクエスト-レスポンス、およびバッファリング)を単独で使用する方法を説明します。ただし、通常、Webサービスではこれらの機能を併用しています。例については、「信頼性のある会話型Webサービスを実装するJWSファイルの例」および「信頼性のある会話型Webサービスを非同期で呼び出すクライアントWebサービスの例」を参照してください。

併用すると、個々の機能についての節で説明した制限事項の一部が適用されなくなったり、場合によっては追加の制限事項が適用されたりします。次の表に、様々な機能を組み合せる場合の考慮事項をまとめます。

表11-1 非同期機能を一緒に使用する場合の考慮事項

機能の組合せ

考慮事項

非同期リクエスト-レスポンス機能とWebサービスの信頼性のあるメッセージング/バッファ機能

- 信頼性のあるWebサービスからの非同期レスポンスも信頼性があります。つまり、レスポンスを処理するためには、宛先WebLogic Serverインスタンスを構成するのと同じように、ソースWebLogic Serverインスタンス上でもJMSサーバー、モジュールおよびキューを構成する必要があります。
ソースWebLogic Serverインスタンス上でJMSキューを作成する際には、weblogic.wsee.DefaultQueueのJNDI名を指定することが要求されます。キューの名前は任意に付けることができます。また、このJMSキューがローカルであることも(通常は、ローカルJNDI名の設定により)指定する必要があります。

- 信頼性のある操作またはバッファ付きの操作を一方向にすることはできません。つまり、実装メソッドに@Onewayアノテーションを付加することはできません。

非同期リクエスト-レスポンス機能とWebサービスの信頼性のあるメッセージング機能

非同期コンテキストのいずれか1つ(AsyncPreCallContextまたはAsyncPostCallContext)でプロパティを設定する場合、そのプロパティはjava.io.Serializableを実装する必要があります。

非同期リクエスト-レスポンス機能とバッファ機能

バッファ付きWebサービス操作を呼び出すクライアントWebサービスで@ServiceClient JWSアノテーションを使用する必要があります。

会話機能とWebサービスの信頼性のあるメッセージング機能

- JWSの会話は、信頼性のあるシーケンスとは異なり、いかなる方法によってもリンクされません。信頼性のあるシーケンスの管理は、会話のライフサイクルとは別に検討する必要があります。たとえば、信頼性のあるメッセージングを使用して、クライアント・サービスと信頼性のある会話型サービスとの間でメッセージを送信する場合、会話を終了しても信頼性のあるシーケンスは終了されません。信頼性のあるシーケンスは(WsrmUtils.setFinalMessage()などの許容可能なメソッドを使用して)明示的に終了させる必要があります。または、シーケンスの存続期間が経過して期限切れになるまでアクティブにしておくことができます。信頼性のあるメッセージ・シーケンスのライフサイクルの詳細については、「信頼性のあるメッセージ・シーケンスのライフサイクルの管理」を参照。

- プロパティWLStub.CONVERSATIONAL_METHOD_BLOCK_TIMEOUTは、クライアントWebサービスのスタブに対して設定された場合、クライアントがブロックしないため無視されます。

- 信頼性のある会話型Webサービスの少なくとも1つのメソッドは、@Onewayアノテーションでマークしないでください。

会話機能と非同期リクエスト-レスポンス機能

クライアントの会話型Webサービスとその他のWebサービスとの間における非同期のレスポンスもまた、会話に参加します。たとえば、WebServiceAが会話型で、非同期リクエスト-レスポンスを使用してWebServiceBを呼び出すとします。WebServiceAは会話型であるため、WebServiceBからの非同期レスポンスも同じ会話に参加します。

信頼性のある会話型Webサービスを実装するJWSファイルの例

次のサンプルのJWSファイルでは、信頼性があり、かつ会話型でもあるWebサービスを実装しています。

package examples.webservices.async_mega;

import java.io.Serializable;

import weblogic.jws.WLHttpTransport;
import weblogic.jws.Conversation;
import weblogic.jws.Policy;

import javax.jws.WebService;
import javax.jws.WebMethod;

@WebService(name="AsyncMegaPortType",
serviceName="AsyncMegaService",
targetNamespace="http://examples.org/")

@Policy(uri="AsyncReliableConversationPolicy.xml",
attachToWsdl=true)

@WLHttpTransport(contextPath="asyncMega",
serviceUri="AsyncMegaService",
portName="AsyncMegaServicePort")

/**
* Web Service that is both reliable and conversational.
*/

public class AsyncMegaServiceImpl implements Serializable {

@WebMethod
@Conversation (Conversation.Phase.START)
public String start() {
return "Starting conversation";
}

@WebMethod
@Conversation (Conversation.Phase.CONTINUE)
public String middle(String message) {
return "Middle of conversation; the message is: " + message;
}

@WebMethod
@Conversation (Conversation.Phase.FINISH)
public String finish(String message ) {
return "End of conversation; the message is: " + message;
}

}

信頼性のある会話型Webサービスを非同期で呼び出すクライアントWebサービスの例

次のJWSファイルでは、「信頼性のある会話型Webサービスを実装するJWSファイルの例」に記載のWebサービスにおける様々な会話型のメソッドを確実に呼び出すクライアントWebサービスの実装方法を示します。クライアントJWSファイルでは、非同期リクエスト-レスポンス機能も使用しています。

package examples.webservices.async_mega;

import weblogic.jws.WLHttpTransport;
import weblogic.jws.ServiceClient;
import weblogic.jws.AsyncResponse;
import weblogic.jws.AsyncFailure;

import javax.jws.WebService;
import javax.jws.WebMethod;
import javax.xml.rpc.Stub;

import weblogic.wsee.async.AsyncPreCallContext;
import weblogic.wsee.async.AsyncCallContextFactory;
import weblogic.wsee.async.AsyncPostCallContext;
import weblogic.wsee.reliability.WsrmUtils;

import examples.webservices.async_mega.AsyncMegaPortType;
import examples.webservices.async_mega.AsyncMegaService;
import examples.webservices.async_mega.AsyncMegaService_Impl;

import java.rmi.RemoteException;

@WebService(name="AsyncMegaClientPortType",
serviceName="AsyncMegaClientService",
targetNamespace="http://examples.org/")

@WLHttpTransport(contextPath="asyncMegaClient",
serviceUri="AsyncMegaClient",
portName="AsyncMegaClientServicePort")

/**
* Client Web Service that has a conversation with the AsyncMegaService
* reliably and asynchronously.
*/

public class AsyncMegaClientImpl {

@ServiceClient(
wsdlLocation="http://localhost:7001/asyncMega/AsyncMegaService?WSDL",
serviceName="AsyncMegaService",
portName="AsyncMegaServicePort")

private AsyncMegaPortType port;

@WebMethod
public void runAsyncReliableConversation(String message) {

AsyncPreCallContext apc = AsyncCallContextFactory.getAsyncPreCallContext();
apc.setProperty("message", message);

try {
port.startAsync(apc);
System.out.println("start method executed.");

port.middleAsync(apc, message );
System.out.println("middle method executed.");

// Since this service is not conversational, any state kept in the port
// field will be lost when this method returns. In the case of reliable
// messaging, this state includes the ID of the reliable sequence being
// used to send messages. The setFinalMessage method specifies
// that this is the final message to be sent on this sequence. This
// will allow the reliable messaging subsystem to proactively clean up
// the reliable sequence instead of timing out.
WsrmUtils.setFinalMessage((Stub)port);
port.finishAsync(apc, message );
System.out.println("finish method executed.");

}
catch (RemoteException e) {
e.printStackTrace();
}

}

@AsyncResponse(target="port", operation="start")
public void onStartAsyncResponse(AsyncPostCallContext apc, String message) {
System.out.println("-------------------");
System.out.println("Got message " + message );
System.out.println("-------------------");
}

@AsyncResponse(target="port", operation="middle")
public void onMiddleAsyncResponse(AsyncPostCallContext apc, String message) {
System.out.println("-------------------");
System.out.println("Got message " + message );
System.out.println("-------------------");
}

@AsyncResponse(target="port", operation="finish")
public void onFinishAsyncResponse(AsyncPostCallContext apc, String message) {
System.out.println("-------------------");
System.out.println("Got message " + message );
System.out.println("-------------------");
}

@AsyncFailure(target="port", operation="start")
public void onStartAsyncFailure(AsyncPostCallContext apc, Throwable e) {
System.out.println("-------------------");
e.printStackTrace();
System.out.println("-------------------");
}

@AsyncFailure(target="port", operation="middle")
public void onMiddleAsyncFailure(AsyncPostCallContext apc, Throwable e) {
System.out.println("-------------------");
e.printStackTrace();
System.out.println("-------------------");
}

@AsyncFailure(target="port", operation="finish")
public void onFinishAsyncFailure(AsyncPostCallContext apc, Throwable e) {
System.out.println("-------------------");
e.printStackTrace();
System.out.println("-------------------");
}
}

12 コールバックによるクライアントへのイベントの通知

この章では、WebLogic Java API for XML-based RPC (JAX-RPC) Webサービスでコールバックを使用してクライアントにイベントを通知する方法について説明します。

この章の内容は次のとおりです。

- コールバックの概要

- コールバックの実装の概要と用語

- コールバックのプログラミング: 主な手順

- ターゲットWebサービスのプログラミングのガイドライン

- コールバック・クライアントWebサービスのプログラミングのガイドライン

- コールバック・インタフェースのプログラミングのガイドライン

- クライアントWebサービスのbuild.xmlファイルの更新

コールバックの概要

コールバックは、なんらかのイベントが発生したことをWebサービスのクライアントに通知するものです。たとえば、クライアントのリクエストの結果が用意されたとき、または、クライアントのリクエストが実行できない場合に、クライアントに通知できます。

メソッドをJWSファイル内で(@WebMethodアノテーションを使用して)標準のパブリック操作として公開した場合は、クライアントがWebサービスにSOAPメッセージを送信して操作を呼び出します。一方、Webサービスにコールバックを追加する場合は、WebサービスからクライアントWebサービスに返送するメッセージを定義して、イベントが発生したことをそのメッセージでクライアントに通知します。つまり、メソッドをパブリック操作として公開することとコールバックを定義することは、送受信の方向が逆になった対照的なプロセスです。

WebLogic Serverでは、呼出し側のクライアントからのSOAPメッセージは、ターゲットWebサービスに自動的にルーティングされます。一方、クライアントがコールバックを受信するためには、クライアントが同じサービスを提供する環境で動作している必要があります。これは一般的に、クライアントがWebサーバー上で動作するWebサービスであることを意味します。クライアントがこれらの要件を満たしていない場合、通常はWebサービスからのコールバックを受信できません。

コールバックに使用されるプロトコルおよびメッセージ形式は、現在の会話を開始したメソッドで使用されているプロトコルおよびメッセージ形式と必ず同じになります。コールバックのプロトコルやメッセージ形式をオーバーライドしようとするとエラーがスローされます。

コールバックの実装の概要と用語

コールバックを実装するには、以下の3つのJavaファイルを作成または更新する必要があります。

- コールバック・インタフェース: コールバック・メソッドを定義するJavaインタフェース・ファイル。このファイルは、明示的に実装するのではなく、jwsc Antタスクによってこのインタフェースの実装が自動的に生成されます。この実装によって、ターゲットWebサービスからクライアントWebサービスにメッセージが返送されます。生成されたWebサービスは、クライアントWebサービスをホストする同じWebLogic Serverにデプロイされます。
この節で示す例では、コールバック・インタフェースの名前をCallbackInterfaceとしています。このインタフェースには、単一のコールバック・メソッド、callbackOperation()が定義されています。

- ターゲットWebサービスを実装するJWSファイル: ターゲットWebサービスには、コールバック・インタフェースで定義されたメソッドを呼び出す1つ以上の標準操作が含まれます。このメソッドによって、ターゲットWebサービス操作の呼出し元のクライアントWebサービスにメッセージが返送されます。
例では、このWebサービスの名前がTargetServiceになっており、単一の標準メソッドtargetOperation()が定義されています。

- クライアントWebサービスを実装するJWSファイル: クライアントWebサービスは、ターゲットWebサービスの操作を呼び出します。このWebサービスには、コールバック・メソッドを介してターゲットWebサービスからコールバック・メッセージを受け取ったときに、クライアントが実行すべき動作を指定する1つ以上のメソッドが含まれます。
例では、このWebサービスの名前がCallbackClientになっています。このWebサービスは、コールバックを受信すると、callbackHandler()というメソッドを自動的に呼び出します。clientOperation()は、TargetServiceを標準の方法で呼び出すメソッドです。

次の図に、メッセージの流れを示します。

1. あるWebLogic Serverインスタンスで動作するCallbackClient WebサービスのclientOperation()メソッドが、TargetServiceのtargetOperation()操作を明示的に呼び出します。TargetServiceサービスは、別のWebLogic Serverインスタンスで動作していてもかまいません。

2. TargetService.targetOperation()メソッドの実装が、コールバック・サービスを実装するCallbackInterfaceのcallbackOperation()操作を明示的に呼び出します。コールバック・サービスは、クライアントWebサービスをホストするWebLogic Serverにデプロイされています。

3. jwscによって生成されたCallbackInterface.callbackOperation()メソッドの実装は、単純にメッセージをCallbackClient Webサービスに返送します。クライアントWebサービスには、このメッセージを処理するcallbackHandler()メソッドが含まれています。

コールバックのプログラミング: 主な手順

この項の手順では、コールバックを実装するために必要な3つのJWSファイル(ターゲットWebサービス、クライアントWebサービス、コールバック・インタフェース)をプログラミングおよびコンパイルする方法について説明します。この手順では、これらのJWSファイルをゼロから作成する方法を示しています。既存のJWSファイルを更新する場合は、この手順をガイドとして利用してください。

Antベースの開発環境を設定済であり、かつjwsc Antタスクを実行してWebサービスをデプロイするためのターゲットを追加できる、作業用のbuild.xmlファイルがあることが前提となっています。

表12-1 コールバックのプログラミング手順

#

手順

説明

1

ターゲットWebサービスを実装する、新しいJWSファイルを作成するか、既存のJWSファイルを更新します。

使い慣れたIDEまたはテキスト・エディタを使用します。「ターゲットWebサービスのプログラミングのガイドライン」を参照してください。

注意: ターゲットWebサービスを実装するJWSファイルは、コールバック・インタフェースの1つ以上のコールバック・メソッドを呼び出します。(コールバック・インタフェースのプログラミング手順については後述の説明を参照してください。)したがって、これらの3つのJWSファイルは、この手順に従って順番にプログラミングするのではなく、すべてを同時にプログラミングすることをお薦めします。手順をこの順番に説明しているのは、あくまで各手順を理解しやすくするためです。

2

build.xmlファイルを更新して、ターゲットJWSファイルをWebサービスにコンパイルするjwsc Antタスクの呼出しを含めます。

「jwsc WebLogic WebサービスAntタスクの実行」を参照してください。

3

Antターゲットを実行して、ターゲットWebサービスをビルドします。

例:

prompt> ant build-mainService

4

ターゲットWebサービスを通常どおりデプロイします。

「WebLogic Webサービスのデプロイとアンデプロイ」を参照してください。

5

クライアントWebサービスを実装する、新しいJWSファイルを作成するか、既存のJWSファイルを更新します。

クライアントWebサービスは、ターゲットWebサービスをホストするものとは別のWebLogic Serverインスタンスにデプロイされていることが前提となっています。「コールバック・クライアントWebサービスのプログラミングのガイドライン」を参照してください。

6

コールバックWebサービスを実装するコールバックJWSインタフェースを作成します。

「コールバック・インタフェースのプログラミングのガイドライン」を参照してください。

7

クライアントWebサービスをビルドするbuild.xmlファイルを更新します。

クライアントWebサービスをビルドするjwsc Antタスクでは、コールバックWebサービスもコールバック・インタフェース・ファイルから暗黙的に生成されます。「クライアントWebサービスのbuild.xmlファイルの更新」を参照してください。

8

Antターゲットを実行して、クライアントおよびコールバックWebサービスをビルドします。

例:

prompt> ant build-clientService

9

クライアントWebサービスを通常どおりデプロイします。

「WebLogic Webサービスのデプロイとアンデプロイ」を参照してください。

ターゲットWebサービスのプログラミングのガイドライン

次のサンプルでは、ターゲットWebサービスを実装する簡単なJWSファイルを示します。太字で示されたJavaコードに対応するコーディングのガイドラインについては、サンプルの後の説明を参照してください。

package examples.webservices.callback;

import weblogic.jws.WLHttpTransport;
import weblogic.jws.Callback;

import javax.jws.WebService;
import javax.jws.WebMethod;

@WebService(name="CallbackPortType",
serviceName="TargetService",
targetNamespace="http://examples.org/")

@WLHttpTransport(contextPath="callback",
serviceUri="TargetService",
portName="TargetServicePort")

/**
* callback service
*/

public class TargetServiceImpl {

@Callback
CallbackInterface callback;

@WebMethod
public void targetOperation (String message) {

callback.callbackOperation (message);
}

}

ターゲットWebサービスを実装するJWSファイルをプログラミングする際には、次のガイドラインに従います。ガイドラインのコード・スニペットは、前述のサンプルでは太字で示されています。

- 必要なJWSアノテーションをインポートします。

import weblogic.jws.Callback;

- @weblogic.jws.Callback JWSアノテーションを使用して、変数がコールバックであることを指定します。つまり、アノテーション付き変数を使用して、TargetService Webサービス操作を呼び出したクライアントWebサービスにコールバック・イベントを返送できます。この変数のデータ型はコールバック・インタフェース(この場合はCallbackInterface)です。

@Callback
CallbackInterface callback;

- TargetService操作を実装するメソッドでは、アノテーション付き変数を使用してコールバック・インタフェースのコールバック・メソッドの1つ(この場合はcallbackOperation())を呼び出します。

callback.callbackOperation (message);

この項で説明したWebLogic固有のJWSアノテーションの詳細は、『Oracle WebLogic Server WebLogic Webサービス・リファレンス』のJWSアノテーション・リファレンスの項を参照してください。

コールバック・クライアントWebサービスのプログラミングのガイドライン

次のサンプルでは、「ターゲットWebサービスのプログラミングのガイドライン」で説明したターゲットWebサービスを呼び出すクライアントWebサービス用の簡単なJWSファイルを示します。太字で示されたJavaコードに対応するコーディングのガイドラインについては、サンプルの後の説明を参照してください。

package examples.webservices.callback;

import weblogic.jws.WLHttpTransport;
import weblogic.jws.ServiceClient;
import weblogic.jws.CallbackMethod;
import weblogic.jws.security.CallbackRolesAllowed;
import weblogic.jws.security.SecurityRole;

import javax.jws.WebService;
import javax.jws.WebMethod;

import examples.webservices.callback.CallbackPortType;

import java.rmi.RemoteException;

@WebService(name="CallbackClientPortType",
serviceName="CallbackClientService",
targetNamespace="http://examples.org/")

@WLHttpTransport(contextPath="callbackClient",
serviceUri="CallbackClient",
portName="CallbackClientPort")

public class CallbackClientImpl {

@ServiceClient(
wsdlLocation="http://localhost:7001/callback/TargetService?WSDL",
serviceName="TargetService",
portName="TargetServicePort")
@CallbackRolesAllowed(@SecurityRole(role="mgr", mapToPrincipals="joe"))
private CallbackPortType port;

@WebMethod
public void clientOperation (String message) {

try {

port.targetOperation(message);
}
catch (RemoteException e) {
e.printStackTrace();
}

}
@CallbackMethod(target="port", operation="callbackOperation")
@CallbackRolesAllowed(@SecurityRole(role="engineer",  mapToPrincipals="shackell"))
public void callbackHandler(String msg) {

System.out.println (msg);
}

}

ターゲットWebサービスを呼び出すJWSファイルをプログラミングする際には、次のガイドラインに従います。ガイドラインのコード・スニペットは、前述のサンプルでは太字で示されています。

- 必要なJWSアノテーションをインポートします。

import weblogic.jws.ServiceClient;
import weblogic.jws.CallbackMethod;

- コールバック・メソッドの呼出しを許可するロールを指定したい場合は、必要に応じてセキュリティ関連のアノテーションをインポートします。

import weblogic.jws.security.CallbackRolesAllowed;
import weblogic.jws.security.SecurityRole;

- 呼び出すターゲットWebサービスのポート・タイプのJAX-RPCスタブをインポートします。実際のスタブそのものは、後でjwsc Antタスクによって作成されます。スタブ・パッケージは、<jws>の子要素<clientgen>のpackageName属性によって指定され、スタブの名前は呼び出されたWebサービスのWSDLによって決まります。

import examples.webservices.callback.CallbackPortType;

- JWSファイルの本文で、@ServiceClient JWSアノテーションを使用して、呼び出すターゲットWebサービスのWSDL、名前、およびポートを指定します。このアノテーションは、プライベート変数のフィールド・レベルで指定します。この変数のデータ型は、呼び出しているWebサービスのJAX-RPCポート・タイプとなります。

@ServiceClient(
wsdlLocation="http://localhost:7001/callback/TargetService?WSDL",
serviceName="TargetService",
portName="TargetServicePort")
@CallbackRolesAllowed(@SecurityRole(role="mgr", mapToPrincipals="joe"))
private CallbackPortType port;

このコードでは、省略可能な@CallbackRolesAllowedアノテーションを使用して、コールバック・メソッドの呼出しを許可する@SecurityRolesのリストを指定する方法も示されています。

- @ServiceClientアノテーションを付けた変数を使用して、ターゲットWebサービス操作を呼び出します。この操作によって、コールバック・インタフェースのコールバック・メソッドが呼び出されます。

port.targetOperation(message);

- コールバック・サービスから受信したコールバック・メッセージを処理するメソッドを作成します。このメソッドには自由に名前を付けることができます。ただし、そのシグネチャは、コールバック・インタフェース内の対応するメソッドのシグネチャと完全に一致させる必要があります。
メソッドに@CallbackMethodアノテーションを付けて、このメソッドでコールバック・メッセージを処理することを指定します。target属性を使用すると、コールバックを受信するJAX-RPCポートの名前(つまり、前の手順で@ServiceClientアノテーションを付けた変数)を指定できます。operation属性を使用すると、このメソッドで処理するコールバック・メッセージを送信するコールバック・インタフェース内のコールバック・メソッドの名前を指定できます。

@CallbackMethod(target="port", operation="callbackOperation")
@CallbackRolesAllowed(@SecurityRole(role="engineer",  mapToPrincipals="shackell"))
public void callbackHandler(String msg) {
System.out.println (msg);
}

このコードでは、省略可能な@CallbackRolesAllowedアノテーションを使用して、この特定のコールバック・メソッドの呼出しを許可するセキュリティ・ロールをさらに制限する方法も示されています。

この項で説明したWebLogic固有のJWSアノテーションの詳細は、『Oracle WebLogic Server WebLogic Webサービス・リファレンス』のJWSアノテーション・リファレンスの項を参照してください。

コールバック・インタフェースのプログラミングのガイドライン

コールバック・インタフェースも、Webサービスを実装したJWSファイルです。ただし、大きな違いが1つあります。コールバック・インタフェースでは、標準の@javax.jws.WebServiceアノテーションを使用して標準のWebサービスであることを指定するかわりに、WebLogic固有の@weblogic.jws.CallbackServiceを使用してコールバック・サービスであることを指定します。@CallbackServiceの属性は、@WebServiceの属性の限定的なサブセットです。

コールバック・サービスを実装するJWSファイルをプログラミングする場合は、使用できるデータ型およびJWSアノテーションについて以下の制約があります。

- @weblogic.jws.CallbackService以外のWebLogic固有のJWSアノテーションを使用することはできません。

- 以下を除くすべての標準JWSアノテーションを使用できます。

- javax.jws.HandlerChain

- javax.jws.soap.SOAPMessageHandler

- javax.jws.soap.SOAPMessageHandlers

- Holderクラス(javax.xml.rpc.holders.Holderインタフェースを実装するユーザー定義のデータ型)を除き、サポートされているすべてのデータ型をパラメータまたは戻り値として使用できます。

次の例では、コールバックWebサービスを実装する簡単なコールバック・インタフェース・ファイルを示します。まず、「ターゲットWebサービスのプログラミングのガイドライン」で説明したターゲットWebサービスが、このインタフェースのメソッドを明示的に呼び出します。次に、jwscによって生成されたコールバック・インタフェースの実装が、ターゲットWebサービスの呼出し元のクライアントWebサービスにメッセージを自動的に返送します。クライアントWebサービスについては「コールバック・クライアントWebサービスのプログラミングのガイドライン」を参照してください。太字で示されたJavaコードに対応するコーディングのガイドラインについては、サンプルの後の説明を参照してください。

package examples.webservices.callback;

import weblogic.jws.CallbackService;

import javax.jws.Oneway;
import javax.jws.WebMethod;

@CallbackService
public interface CallbackInterface {

@WebMethod
@Oneway
public void callbackOperation (String msg);

}

コールバックWebサービスを実装するJWSファイルをプログラミングする際には、次のガイドラインに従います。ガイドラインのコード・スニペットは、前述のサンプルでは太字で示されています。

- 必要なJWSアノテーションをインポートします。

import weblogic.jws.CallbackService;

- インタフェース宣言に@CallbackServiceアノテーションを付けて、JWSファイルがコールバック・サービスを実装することを指定します。

@CallbackService
public interface CallbackInterface {

- ターゲットWebサービスが明示的に呼び出すメソッドを作成します。このメソッドは、ターゲットWebサービスの呼出し元のクライアント・サービスにメッセージを自動的に返信するメソッドです。このメソッドの実装は、Javaインタフェース・ファイルであるこのファイルでは提供しません。どちらかというと、WebLogic Webサービス・ランタイムは、jwsc Antタスクでメソッドの実装を生成します。

public void callbackOperation (String msg);

注意:
このサンプルのコールバック・メソッドは、voidを返し、@Onewayアノテーションが付けられていますが、必ずしもこのように設定する必要はありません。

この項で説明したWebLogic固有のJWSアノテーションの詳細は、『Oracle WebLogic Server WebLogic Webサービス・リファレンス』のJWSアノテーション・リファレンスの項を参照してください。

クライアントWebサービスのbuild.xmlファイルの更新

クライアントWebサービスを実装するJWSファイルに対してjwsc Antタスクを実行すると、この項で説明するように、コールバックWebサービスも暗黙的に生成されます。

build.xmlファイルを更新して、ターゲットWebサービスを呼び出すクライアントWebサービスを生成するには、次のサンプルのようなtaskdefsおよびbuild-clientServiceターゲットを追加します。詳細は、サンプルの後の説明を参照してください。

<taskdef name="jwsc"
classname="weblogic.wsee.tools.anttasks.JwscTask" />

<target name="build-clientService">

<jwsc
srcdir="src"
destdir="${clientService-ear-dir}" >

<jws file="examples/webservices/callback/CallbackClientImpl.java" >

<clientgen
wsdl="http://${wls.hostname}:${wls.port}/callback/TargetService?WSDL"
packageName="examples.webservices.callback"
serviceName="TargetService" />

</jws>

</jwsc>

</target>

jwsc Antタスクの完全なクラス名を定義するには、taskdef Antタスクを使用します。

クライアントWebサービスをコンパイルするjwsc Antタスクを更新して、<jws>要素の<clientgen>子要素を含めます。これにより、デプロイされたTargetService WebサービスのJAX-RPCスタブが生成およびコンパイルされるようになります。jwsc Antタスクでは、これらのスタブが生成されたWARファイルに自動的にパッケージ化されるため、即座にクライアントWebサービスからアクセスできるようになります。このようにするのは、生成されたクラスの1つをCallbackClientImpl JWSファイルでインポートして使用するためです。

ターゲットWebサービスのWSDLには、ターゲットWebサービスから呼び出されるコールバックWebサービスを表す追加の<service>要素が含まれています。このため、jwsc Antタスクの<clientgen>子要素によってコールバックWebサービスも生成およびコンパイルされ、クライアントWebサービスと同じEARファイルにパッケージ化されます。

13 接続プロトコルとしてのJMSトランスポートの使用

この章では、非同期リクエスト-レスポンスを使用するWebLogic Java API for XML-based RPC (JAX-RPC) Webサービスで、JMSトランスポートを接続プロトコルとして使用する方法について説明します。

この章の内容は次のとおりです。

- JMSトランスポートの使用の概要

- Javaから開始するJMSトランスポートの使用: 主な手順

- WSDLから開始するJMSトランスポートの使用: 主な手順

- JMSトランスポートWebサービスのホストWebLogic Serverインスタンスの構成

- @WLJmsTransport JWSアノテーションの使用

- jwsc Antタスクの<WLJmsTransport>子要素の使用

- JMSトランスポートを使用するためのWSDLの更新

- JMSトランスポートを使用したWebLogic Webサービスの呼出し

JMSトランスポートの使用の概要

通常、クライアント・アプリケーションからWebLogic Webサービスを呼び出すときは、接続プロトコルとしてHTTP/Sが使用されます。しかし、クライアント・アプリケーションがトランスポートにJMSを使用するようにWebLogic Webサービスを構成することもできます。

JMSトランスポートを使用すると、信頼性、スケーラビリティ、サービス品質が向上します。Webサービスの信頼性のあるメッセージングの場合と同様に、メソッド呼出しがまだキューに入っているときにWebLogic Serverが停止しても、再起動すればすぐに処理が行われます。クライアントは、Webサービスを呼び出す際に呼出しからのレスポンスを待機しないため、クライアントの実行は続行可能です。ただし、JMSトランスポートを使用する場合は、HTTP/Sより若干オーバーヘッドが大きくなり、プログラムが複雑になります。

トランスポートを構成するには、後の項で説明するように、JWSアノテーションとjwsc Antタスクの子要素のどちらかを使用します。接続トランスポートとしてJMSを使用するようにWebLogic Webサービスを構成した場合、Webサービスの生成済WSDLで対応するポートに対して指定されたエンドポイント・アドレスのURLでは、http://ではなくjms://が使用されます。JMSエンドポイントのアドレスの例を次に示します。

jms://myHost:7001/transports/JMSTransport?URI=JMSTransportQueue

URLのURI=JMSTransportQueueセクションでは、JMSトランスポート機能用に構成されたJMSキューを指定しています。HTTPを使用してWebサービスを呼び出すことはできませんが、HTTPを使用してそのWebサービスのWSDLを参照できます。これにより、clientgenはやはりWebサービスのJAX-RPCスタブを生成できます。

指定する各トランスポートに対し、WebLogic ServerはWSDL内に追加のポートを生成します。このため、Webサービス呼出し時に使用できるトランスポート(JMS、HTTP、またはHTTPS)をクライアント・アプリケーションで選択できるようにするには、適切なJWSアノテーションまたはjwscの子要素を使用して、明示的にトランスポートを追加する必要があります。

注意:
JMSトランスポートの使用は、WebLogicの付加価値機能です。.NETクライアントなど、WebLogic以外のクライアント・アプリケーションでは、JMSポートを使用してWebサービスを呼び出すことができない場合があります。

Javaから開始するJMSトランスポートの使用: 主な手順

Javaから開始する際にJMSトランスポートを使用するには、以下の少なくとも1つのタスクを実行する必要があります。

- JWSファイルに@WLJmsTransportアノテーションを追加します。

- jwsc Antタスクに<WLJmsTransport>子要素を追加します。この設定は、JWSファイルで定義されたトランスポートをオーバーライドします。

注意:
JWSファイルのコーディング時にはニーズに最適なトランスポートがわからない場合があるため、トランスポートは、<WLJmsTransport>子要素を使用してビルド時に指定することをお薦めします。

次の手順では、Javaから開始する際に、JMSトランスポートを使用して現在のWebサービスを呼び出すために必要なすべての手順について説明します。

注意:
Webサービスを実装する基本的なJWSファイルが作成されており、JMSを使用して呼び出すWebサービスを構成することが前提となっています。また、Antベースの開発環境を設定済であり、かつjwsc Antタスクを実行してサービスをデプロイするためのターゲットを含む、作業用のbuild.xmlファイルがあることも前提となっています。

表13-1 Javaから開始するJMSトランスポートの使用手順

#

手順

説明

1

必要なJMSコンポーネント用にWebLogic Serverドメインを構成します。

「JMSトランスポートWebサービスのホストWebLogic Serverインスタンスの構成」を参照してください。

2

JWSファイルに@WLJmsTransportアノテーションを追加します。(オプション)

この手順はオプションです。現在のJWSに@WLJmsTransportアノテーションを追加しない場合、<WLJmsTransport>子要素をjwsc Antタスクに追加する必要があります(ステップ3を参照)。

「@WLJmsTransport JWSアノテーションの使用」を参照してください。

3

jwsc Antタスクに<WLJmsTransport>子要素を追加します。(オプション)

<WLJmsTransport>子要素を使用して、JWSファイルで定義されているトランスポートをオーバーライドします。この手順は、ステップ2で@WLJmsTransportアノテーションをJWSファイルに追加しなかった場合に必須です。それ以外の場合、この手順は省略可能です。

詳細については、「jwsc Antタスクの<WLJmsTransport>子要素の使用」を参照してください。

4

jwscタスクを呼び出すbuild.xml Antファイル内のターゲットを実行することにより、Webサービスをビルドします。

たとえば、jwsc Antタスクを呼び出すターゲットがbuild-serviceというものであれば、以下を実行します。

prompt> ant build-service

「jwsc WebLogic WebサービスAntタスクの実行」を参照してください。

5

WebサービスをWebLogic Serverにデプロイします。

「WebLogic Webサービスのデプロイとアンデプロイ」を参照してください。

JMSトランスポートを使用してWebサービスを呼び出すようにクライアント・アプリケーションを更新する方法については、「JMSトランスポートを使用したWebLogic Webサービスの呼出し」を参照してください。

WSDLから開始するJMSトランスポートの使用: 主な手順

WSDLから開始する際にJMSトランスポートを使用するには、以下の少なくとも1つのタスクを実行する必要があります。

- wsdlc Antタスクを実行する前に、JMSトランスポートを使用するようにWSDLを更新します。

- @WLJmsTransportアノテーションを追加するように、wsdlc Antタスクによって生成される途中まで作成済みのJWS実装ファイルを更新します。

- JWS実装ファイルの作成に使用されるjwsc Antタスクに<WLJmsTransport>子要素を追加します。この設定は、JWSファイルで定義されたトランスポートをオーバーライドします。

注意:
JWSファイルのコーディング時にはニーズに最適なトランスポートがわからない場合があるため、トランスポートは、<WLJmsTransport>子要素を使用してビルド時に指定することをお薦めします。

次の手順では、WSDLから開始する際に、JMSトランスポートを使用して現在のWebサービスを呼び出すために必要なすべての手順について説明します。

注意:
この手順では既存のWSDLファイルがあることを前提としています。

表13-2 WSDLから開始するJMSトランスポートの使用手順

#

手順

説明

1

必要なJMSコンポーネント用にWebLogic Serverドメインを構成します。

「JMSトランスポートWebサービスのホストWebLogic Serverインスタンスの構成」を参照してください。

2

JMSトランスポートを使用するようWSDLを更新する(オプション)

この手順はオプションです。JMSトランスポートを使用するようWSDLを更新しなかった場合、以下の少なくとも1つの作業を行う必要があります。

- 途中まで作成済みのJWSファイルを編集して@WLJmsTransportアノテーションをJWSファイルに追加します(ステップ4を参照)。

- <WLJmsTransport>子要素をjwsc Antタスクに追加します(ステップ5を参照)。

「JMSトランスポートを使用するためのWSDLの更新」を参照してください。

3

WSDLファイルに対してwsdlc Antタスクを実行します。

たとえば、wsdlc Antタスクを呼び出すターゲットがgenerate-from-wsdlというものであれば、以下を実行します。

prompt> ant generate-from-wsdl

「wsdlc WebLogic WebサービスAntタスクの実行」を参照してください。

4

途中まで作成済みのJWSファイルを更新します。

wsdlc Antタスクにより途中まで作成済のJWSファイルが生成されます。必要な動作をWebサービスに実装するには、独自のビジネス・コードをWebサービスに追加する必要があります。「wsdlcで生成される途中まで作成済のJWS実装クラス・ファイルの更新」を参照してください。

ステップ2で、JMSトランスポートを使用するようにWSDLを更新した場合、JWSファイルには、JMSトランスポートを定義する@WLJmsTransportアノテーションが含まれます。@WLJmsTransportアノテーションがJWSファイルに含まれない場合、以下の少なくとも1つの作業を行う必要があります。

- JWSファイルを編集して、@WLJmsTransportアノテーションをJWSファイルに追加します(「@WLJmsTransport JWSアノテーションの使用」を参照)。

- <WLJmsTransport>子要素をjwsc Antタスクに追加します(ステップ5を参照)。

5

jwsc Antタスクに<WLJmsTransport>子要素を追加します。(オプション)

<WLJmsTransport>子要素を使用して、JWSファイルで定義されているトランスポートをオーバーライドします。JWSファイルに@WLJmsTransportアノテーションが含まれない場合、この手順は必須です(ステップ4を参照)。それ以外の場合、この手順は省略可能です。

詳細については、「jwsc Antタスクの<WLJmsTransport>子要素の使用」を参照してください。

6

JWSファイルに対してjwsc Antタスクを実行し、Webサービスをビルドします。

wsdlc Antタスクによって生成されたアーティファクトと更新したJWS実装ファイルを指定して、Webサービスを実装するエンタープライズ・アプリケーションを生成します。「jwsc WebLogic WebサービスAntタスクの実行」を参照してください。

7

WebサービスをWebLogic Serverにデプロイします。

「WebLogic Webサービスのデプロイとアンデプロイ」を参照してください。

JMSトランスポートを使用してWebサービスを呼び出すようにクライアント・アプリケーションを更新する方法については、「JMSトランスポートを使用したWebLogic Webサービスの呼出し」を参照してください。

JMSトランスポートWebサービスのホストWebLogic Serverインスタンスの構成

JMSトランスポートWebサービスのデプロイ先となるWebLogic Serverインスタンスを構成する際には、Webサービスのランタイムで内部的に使用される、JMSサーバーやモジュールなどのJMSリソースを構成します。

これらのリソースは手作業でも構成できますが、構成ウィザードで、Webサービス固有の拡張テンプレートを使用してWebLogic Serverドメインを拡張することもできます。構成ウィザードを使用すると、必要な構成手順を大幅に簡素化できます。詳細は、「Webサービス機能用のドメイン構成」を参照してください。

注意:
または、WLSTを使用してリソースを構成できます。WLSTを使用したドメインの拡張の詳細は、『WebLogic Scripting Toolの理解』の既存ドメインの構成に関する項を参照してください。
Webサービスのリソースを含まないドメインは、Webサービス以外のシナリオおよび非同期のリクエスト/レスポンスが含まれないWebサービス・シナリオにおいて、適切に起動および実行されます。ただし、サーバー・ログに、非同期リソースが構成されていないこと、およびWebサービスの非同期レスポンス・サービスが完全にデプロイされていないことを示すINFOメッセージが表示されます。

リソースを手作業で構成する場合、以下の手順を実行します。

表13-3 JMSトランスポートWebサービスのホストWebLogic Serverインスタンスを手作業で構成する手順

#

手順

説明

1

ホストWebLogic Serverインスタンスが格納されたドメインのWebLogic Server管理コンソールを起動します。

ブラウザでWebLogic Server管理コンソールを起動するには、次のURLを入力します。

http://host:port/console

各要素の説明は次のとおりです。

- hostは、管理サーバーが動作しているコンピュータを指します。

- portは、管理サーバーが接続リクエストをリスニングしているポート番号を指します。管理サーバーのデフォルトのポート番号は7001です。

『Oracle WebLogic Server WebLogic Webサービスの理解』の管理コンソールの起動に関する項を参照してください。

3

JMSサーバーを作成します。

JMSサーバーを作成します。JMSサーバーがすでに存在する場合は、新しいJMSサーバーを作成せずにそれを使用できます。

Oracle WebLogic Server管理コンソール・オンライン・ヘルプのJMSサーバーの作成に関する項を参照してください。

4

JMSモジュールを作成し、キューを定義します。

JMSモジュールを作成し、その中にJMSキューを定義します。JMSモジュールがすでに存在する場合は、新しいJMSモジュールを作成せずにそれを使用することもできます。JMSキューを、1つ前の手順で作成したJMSサーバーにターゲット指定します。このJMSキューがローカルであることを必ず指定してください(通常は、ローカルJNDI名の設定により指定できます)。Oracle WebLogic Server管理コンソール・オンライン・ヘルプのJMSシステム・モジュールの作成に関する項とシステム・モジュールのキューの作成に関する項を参照してください。

JMSトランスポートWebサービスで、デフォルトWebサービスのキューを使用する場合は、JMSキューのJNDI名をweblogic.wsee.DefaultQueueに設定します。そうではなく、別のJNDI名を使用する場合は、@WLJmsTransportアノテーションまたはjwsc Antタスクの子要素<WLJmsTransport>を指定する際にキュー名を指定する必要があります。

クラスタ化の考慮事項:

クラスタ内でWebサービスのJMSトランスポート機能を使用する場合は、次の作業を行う必要があります。

- JMSキューの作成時に、分散キューではなくローカルJMSキューを作成します。

- このJMSキューをクラスタ内の各サーバーに明示的にターゲット指定します。

@WLJmsTransport JWSアノテーションの使用

JWSファイルをプログラムした時点で、Webサービスの呼出しにクライアント・アプリケーションで(HTTP/Sではなく) JMSトランスポートを使用することが決まっている場合は、@WLJmsTransportを使用してその呼出しの詳細を指定できます。後のビルド時に、「jwsc Antタスクの<WLJmsTransport>子要素の使用」に従い、jwsc Antタスクの<WLJmsTransport>子要素を指定して、JWSファイルで定義されている呼出しをオーバーライドし、さらにJMSトランスポート指定を追加できます。

@WLJmsTransportアノテーションを使用する際は、これらのガイドラインに従ってください:

- JWSファイルに含めることができる@WLJmsTransportアノテーションは1つのみです。

- これより前の部分で構成したJMSキューのJNDI名の指定にはqueue属性を使用します。デフォルトのWebサービス・キュー(weblogic.wsee.DefaultQueue)を使用する場合は、queue属性を指定する必要はありません。

- 接続ファクトリのJNDI名の指定にはconnectionFactory属性を使用します。この属性のデフォルト値は、WebLogic ServerインスタンスのデフォルトのJMS接続ファクトリです。

次の例では、@WLJmsTransportアノテーションを使用する簡単なJWSファイルを示します。関連するコードは太字で示しています。

package examples.webservices.jmstransport;

import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.jws.soap.SOAPBinding;

import weblogic.jws.WLJmsTransport;

@WebService(name="JMSTransportPortType",
serviceName="JMSTransportService",
targetNamespace="http://example.org")

@SOAPBinding(style=SOAPBinding.Style.DOCUMENT,
use=SOAPBinding.Use.LITERAL,
parameterStyle=SOAPBinding.ParameterStyle.WRAPPED)

// WebLogic-specific JWS annotation that specifies the context path and
// service URI used to build the URI of the Web Service is
// "transports/JMSTransport"

@WLJmsTransport(contextPath="transports", serviceUri="JMSTransport",
queue="JMSTransportQueue", portName="JMSTransportServicePort",
connectionFactory="JMSTransportConnectionFactory")

/**
* This JWS file forms the basis of simple Java-class implemented WebLogic
* Web Service with a single operation: sayHello
*/

public class JMSTransportImpl {

@WebMethod()
public String sayHello(String message) {
System.out.println("sayHello:" + message);
return "Here is the message: '" + message + "'";
}
}

jwsc Antタスクの<WLJmsTransport>子要素の使用

JMSトランスポートはjwsc Antタスクの<jws>要素の<WLJmsTransport>子要素を使用して、ビルド時にも指定できます。ビルド時にトランスポートを指定する理由としては、次のようなものが挙げられます。

- JWSファイルで指定した属性値をオーバーライドする必要があります。

- JWSファイルでは別のトランスポートが指定されており、ビルド時に、JMSをトランスポートとして使用すると決定しました。

- JWSファイルに@WLXXXTransportアノテーションが含まれていないため、デフォルトではHTTPトランスポートが使用されていますが、ビルド時にJMSトランスポートを使用してWebサービスを呼び出すと決定しました。

jwsc Antタスクに対してトランスポートを指定すると、それがJWSファイル内のすべてのトランスポート・アノテーションに優先されます。

次の例では、jwsc Antタスクに対してトランスポートを指定する方法を示します。

<target name="build-service">

<jwsc
srcdir="src"
destdir="${ear-dir}">
<jws file="examples/webservices/jmstransport/JMSTransportImpl.java">

<WLJmsTransport
contextPath="transports"
serviceUri="JMSTransport"
portName="JMSTransportServicePort"
queue="JMSTransportQueue"
connectionFactory="JMSTransportConnectionFactory"/>

</jws>

</jwsc>

</target>

上述の例では、「@WLJmsTransport JWSアノテーションの使用」に示したJWSファイルで指定されたものと同じ値をURLおよびJMSキューに対して指定する方法を示しています。

jwsc Antタスクの使用方法の詳細は、『Oracle WebLogic Server WebLogic Webサービス・リファレンス』のjwscに関する項を参照してください。

JMSトランスポートを使用するためのWSDLの更新

JMSトランスポートを使用するようにWSDLを更新するには、JMSトランスポート情報を定義する<wsdl:binding>定義と<wsdl:service>定義を追加する必要があります。これらの定義は、以下のいずれかの方法で追加できます。

- 既存のHTTPの<wsdl:binding>および<wsdl:service>定義を編集します。

- WSDLで複数のトランスポート・オプションを指定するには、既存のHTTPの<wsdl:binding>および<wsdl:service>定義をコピーし、JMSトランスポートを使用するように編集します。

どちらの場合でも、JMSトランスポートを使用するように<wsdl:binding>および<wsdl:service>定義を以下のように変更する必要があります。

- <wsdl:binding>要素の子要素<soapwsdl:binding>のtransport属性をhttp://www.openuri.org/2002/04/soap/jmsに設定します。例:

<binding name="JmsTransportServiceSoapBindingjms" type="tns:JmsTransportPortType">
<soap:binding style="document" transport="http://www.openuri.org/2002/04/soap/jms/"/>

- <wsdl:service>の子要素<soapwsdl:address>のlocation属性に、JMS形式のエンドポイントURLを指定します。例:

<s0:service name="JmsTransportService">
<s0:port binding="s1:JmsTransportServiceSoapBindingjms" name="JmsTransportServicePort">
<s2:address location="jms://localhost:7001/transports/JmsTransport?URI=JMSTransportQueue"/>
</s0:port>
</s0:service>

JMSトランスポートを使用したWebLogic Webサービスの呼出し

JMSトランスポートを使用してWebサービスを呼び出すクライアント・アプリケーションの記述は、HTTPトランスポートを使用する場合の記述と同様に行います。ただ1つ異なるのは、必ず、JMSキュー(@WLJmsTransportアノテーションまたはjwsc Antタスクの<WLJmsTransport>子要素で指定)とその他のJMSオブジェクトが作成済でなければならないという点です。詳細については、「Javaから開始するJMSトランスポートの使用: 主な手順」または「WSDLから開始するJMSトランスポートの使用: 主な手順」を参照してください。

HTTPを使用してJMSトランスポートで構成されたWebサービスを呼び出すことはできませんが、HTTPを使用してそのWebサービスのWSDLを参照することはできます。これにより、clientgen AntタスクはWebサービスのJAX-RPCスタブを作成することができます。たとえば、この項で示すWebサービスのWSDLのためのURLは、次のようになります。

http://host:port/transports/JMSTransport?WSDL

ただし、デプロイされたWebサービスのWSDLにおけるエンドポイント・アドレスでは、http://ではなくjms://が使用され、このアドレスには修飾子?URI=JMS_QUEUEが含まれるため、clientgen AntタスクはWebサービス呼出し時にJMSトランスポートを使用するために必要なスタブを自動作成し、クライアント・アプリケーション側で通常と違う処理を行う必要はありません。JMSエンドポイントのアドレスの例を次に示します。

jms://host:port/transports/JMSTransport?URI=JMSTransportQueue

注意:
JMSトランスポートを使用して呼び出すWebサービスをトランザクションのコンテキスト内でも実行することを指定した(つまり、JWSファイルに@weblogic.jws.Transactionalアノテーションが含まれている)場合は、そのサービスを呼び出す際に非同期リクエスト-レスポンスを使用する必要があります。そうしないと、デッドロックが発生して呼出しが失敗します。

Webサービスの呼出しについての一般情報は、「JAX-RPC Webサービス・クライアントの開発」を参照してください。

デフォルトのサービス・アドレスURLのオーバーライド

clientgenで生成されたJAX-RPCスタブを使用してWebサービスを呼び出すクライアント・アプリケーションを作成する場合、Webサービスのデフォルトのサービス・アドレスURLは、ServiceコンストラクタのWSDLファイル引数の<address>要素で指定したものとなります。

ただし、場合によっては、特にクラスタにデプロイされているWebLogic Webサービスを呼び出す際に、クラスタのアドレスまたはクラスタ内の管理対象サーバーのアドレスのリストを指定する場合には、このアドレスをオーバーライドする必要があることがあります。また、t3プロトコルを使用してWebサービスを呼び出すことが必要な場合もあります。JMSトランスポートの使用時にこのサービス・エンドポイントURLをオーバーライドするには、次の例で示すように、weblogic.wsee.jaxrpc.WLStub.JMS_TRANSPORT_JNDI_URLスタブ・プロパティを使用します。

package examples.webservices.jmstransport.client;

import weblogic.wsee.jaxrpc.WLStub;

import java.rmi.RemoteException;

import javax.xml.rpc.ServiceException;
import javax.xml.rpc.Stub;

/**
* This is a simple standalone client application that invokes the
* the <code>sayHello</code> operation of the JMSTransport web service.
*/

public class Main {

public static void main(String[] args)
throws ServiceException, RemoteException{

JMSTransportService service = new JMSTransportService_Impl(args[0] + "?WSDL" );
JMSTransportPortType port = service.getJMSTransportServicePort();

Stub stub = (Stub) port;

stub._setProperty(WLStub.JMS_TRANSPORT_JNDI_URL,
"t3://shackell01.amer.com:7001");
try {
String result = null;

result = port.sayHello("Hi there! ");

System.out.println( "Got JMS result: " + result );

} catch (RemoteException e) {
throw e;
}
}
}

デフォルトのTextMessageのかわりとしてのJMS BytesMessageの使用

JMSトランスポートを使用する場合、Webサービス・ランタイムは、デフォルトではjavax.jms.TextMessageオブジェクトを使用してメッセージを送信します。ほとんどのクライアント・アプリケーションはこのデフォルトのままで十分ですが、状況によっては普通のテキストではなくバイナリ・データを送信する必要がある場合もあります。その場合は、Webサービス・ランタイムでjavax.jms.BytesMessageを使用することをリクエストする必要があります。そのためには、クライアント・アプリケーションでWLStub.JMS_TRANSPORT_MESSAGE_TYPEスタブ・プロパティを使用し、値としてWLStub.JMS_BYTESMESSAGEを設定します。次に例を示します。

stub._setProperty(WLStub.JMS_TRANSPORT_MESSAGE_TYPE,
WLStub.JMS_BYTESMESSAGE);

Webサービス・ランタイムは、リクエストと同じメッセージ・データ型を使用してレスポンスを戻します。

このプロパティを設定できるクライアント・アプリケーションの例については、「デフォルトのサービス・アドレスURLのオーバーライド」を参照してください。

WSDLファイルへのHTTPアクセスの無効化

「JMSトランスポートを使用したWebLogic Webサービスの呼出し」で説明したように、デプロイされているWebサービスのWSDLには、デフォルトでHTTPでアクセスできるようになっています。WSDLファイルへのアクセスを無効にする場合(特に、ファイアウォールの外でWebサービスにアクセスできる場合)は、次のいずれかを実行します。

- JWSファイルで、weblogic.jws.WSDLアノテーションを使用してプログラム的にアクセスを無効にします。詳細は、『Oracle WebLogic Server WebLogic Webサービス・リファレンス』のweblogic.jws.WSDLに関する項を参照してください。

- Webサービスをデプロイした後に、WebLogic Server管理コンソールを使用してWSDLファイルへのアクセスを無効にします。この場合、構成情報は、アノテーションではなくデプロイメント・プラン内に格納されます。
このタスクをWebLogic Server管理コンソールを使用して実行する場合は、デプロイしたWebサービスの「構成」→「全般」ページに移動し、「動的WSDLの表示を有効化」チェック・ボックスの選択を解除します。この変更を有効にするには、構成をデプロイメント・プランに保存した後に、Webサービス(またはそのエンタープライズ・アプリケーション)を再デプロイ(更新)する必要があります。

14 SOAPメッセージ・ハンドラの作成と使用

この章では、WebLogic Java API for XML-based RPC (JAX-RPC) Webサービスで、SOAPメッセージ・ハンドラを作成および使用する方法について説明します。

この章の内容は次のとおりです。

- SOAPメッセージ・ハンドラの概要

- SOAPメッセージ・ハンドラのWebサービスへの追加: 主な手順

- SOAPメッセージ・ハンドラおよびハンドラ・チェーンの設計

- GenericHandlerクラスの作成

- JWSファイルでのハンドラの構成

- ハンドラ・チェーン構成ファイルの作成

- Webサービスのコンパイルと再ビルド

- クライアント側SOAPメッセージ・ハンドラの作成と使用

SOAPメッセージ・ハンドラの概要

Webサービスの中には、SOAPメッセージへのアクセスを必要とするものがあります。このSOAPメッセージに対してSOAPメッセージ・ハンドラを作成できます。

SOAPメッセージ・ハンドラは、Webサービスのリクエストとレスポンスの両方でSOAPメッセージをインターセプトするメカニズムです。ハンドラは、WebサービスそのものとWebサービスを呼び出すクライアント・アプリケーションの両方で作成することができます。

ハンドラ使用の簡単な例としては、SOAPメッセージのヘッダー部分の情報へのアクセスがあります。SOAPのヘッダーを使用してWebサービス固有の情報を格納しておき、ハンドラを使用してその情報を操作することができます。

SOAPメッセージ・ハンドラは、Webサービスのパフォーマンスを向上させるために使用することもできます。Webサービスがデプロイされてしばらくすると、同じパラメータを使用してWebサービスを呼び出すコンシューマが多いことに気付く場合があります。よく使用されるWebサービス呼出しの結果をキャッシュしておき(結果が静的であることが前提となります)、適宜、キャッシュしておいた結果をただちに戻すことによって、Webサービスを実装したバックエンド・コンポーネントを呼び出す必要がなくなり、Webサービスのパフォーマンスが向上します。このパフォーマンスの向上は、ハンドラを使用して、SOAPリクエスト・メッセージに頻繁に使用されるパラメータが含まれていないかチェックすることで実現できます。

次の表では、Webサービスでハンドラ・チェーンが構成されていることを指定するためにJWSファイル内で使用できる標準的なJWSアノテーションを示しています。その後の項で、これらのアノテーションの使用方法について、より詳細に説明します。詳細は、http://www.jcp.org/en/jsr/detail?id=181にある「Web Services MetaData for the Java Platform (JSR-181)仕様」を参照してください。

表14-1 SOAPメッセージ・ハンドラ・チェーンの構成に使用されるJWSアノテーション

JWSアノテーション

説明

javax.jws.HandlerChain

Webサービスを外部で定義されるハンドラ・チェーンと関連付けます。複数のWebサービスで同じハンドラ構成を共有する必要がある場合、またはハンドラ・チェーンが複数のトランスポートのハンドラで構成されている場合は、このアノテーションを使用します。

javax.jws.soap.SOAPMessageHandlers

各Webサービス操作の呼出し前と呼出し後に実行されるSOAPハンドラのリストを指定します。外部構成ファイルを使用するよりも、JWSファイルそのものにハンドラ構成情報を埋め込む方が望ましい場合は、(@HandlerChainではなく)このアノテーションを使用します。

@SOAPMessageHandlerアノテーションは、@SOAPMessageHandlersの配列です。ハンドラは、この配列内にリストされている順番で実行されます。

注意: このアノテーションは、JAX-RPC Webサービスでのみ機能します。

javax.jws.soap.SOAPMessageHandler

単一のSOAPメッセージ・ハンドラを@SOAPMessageHandlers配列で指定します。

次の表では、javax.xml.rpc.handler APIのメイン・クラスおよびインタフェースについて説明します。これらの一部は、ハンドラそのものの作成時に使用します。これらのAPIについては、後の節でより詳細に説明します。これらのAPIの詳細は、http://java.net/projects/jax-rpc/にある「JAX-RPC 1.1仕様」を参照してください。

表14-2 JAX-RPCハンドラのインタフェースとクラス

javax.xml.rpc.handlerのインタフェースとクラス

説明

Handler

ハンドラ作成時に実装される主なインタフェース。SOAPのリクエスト、レスポンス、およびフォルトを処理するメソッドが格納されています。

GenericHandler

Handlerインタフェースを実装する抽象クラス。ハンドラ作成時には、Handlerを直接実装するのではなく、このクラスを拡張します。

GenericHandlerクラスは、ハンドラの記述を容易にする便利な抽象クラスです。このクラスは、ライフサイクル・メソッドinitおよびdestroy、ならびに様々な処理メソッドのデフォルト実装を提供します。ハンドラの開発者は、派生したハンドラ実装クラスの一部として特化する必要があるメソッドのみをオーバーライドします。

HandlerChain

ハンドラのリストを表すインタフェース。HandlerChainインタフェースの実装クラスは、登録されているハンドラの呼出しに関するポリシーとメカニズムを抽象化します。

HandlerRegistry

HandlerRegistry内のハンドラのプログラムによる構成に対するサポートを提供するインタフェース。

HandlerInfo

ハンドラ・チェーン内のハンドラの情報が格納されているクラス。HandlerInfoインスタンスがHandler.initメソッドに渡されて、Handlerインスタンスが初期化されます。

MessageContext

ハンドラによって処理されたメッセージのコンテキストを抽出します。MessageContextプロパティにより、ハンドラ・チェーン内のハンドラは処理ステートを共有できます。

soap.SOAPMessageContext

SOAPメッセージの取得または更新に使用されるMessageContextインタフェースのサブインタフェース。

javax.xml.soap.SOAPMessage

実際のSOAPのリクエスト・メッセージまたはレスポンス・メッセージが入ったオブジェクト。ヘッダー、本文、添付ファイルが含まれます。

SOAPメッセージ・ハンドラのWebサービスへの追加: 主な手順

次の手順では、WebサービスにSOAPメッセージ・ハンドラを追加する主要な手順を説明します。

Webサービスを実装する基本的なJWSファイルを作成済であり、SOAPメッセージ・ハンドラおよびハンドラ・チェーンを追加してWebサービスを更新することが前提となっています。また、Antベースの開発環境を設定済であり、かつjwsc Antタスクを実行するためのターゲットを含む、作業用のbuild.xmlファイルがあることも前提となっています。詳細は、次の項を参照してください。

- 「JAX-RPC Webサービス開発者向けサンプル」

- 「JAX-RPC Webサービスの開発」

- JWSファイルのプログラミング

- 「JAX-RPC Webサービス・クライアントの開発」

表14-3 WebサービスへのSOAPメッセージ・ハンドラの追加手順

#

手順

説明

1

ハンドラとハンドラ・チェーンを設計します。

「SOAPメッセージ・ハンドラおよびハンドラ・チェーンの設計」を参照してください。

2

ハンドラ・チェーン内の各ハンドラについて、javax.xml.rpc.handler.GenericHandler抽象クラスを拡張するJavaクラスを作成します。

「GenericHandlerクラスの作成」を参照してください。

3

SOAPメッセージ・ハンドラを構成するためのアノテーションを追加して、JWSファイルを更新します。

「JWSファイルでのハンドラの構成」を参照してください。

4

JWSファイル内で@HandlerChain標準アノテーションを使用している場合は、ハンドラ・チェーンの構成ファイルを作成します。

「ハンドラ・チェーン構成ファイルの作成」を参照してください。

5

ハンドラ・チェーン内のすべてのハンドラ・クラスをコンパイルし、Webサービスを再ビルドします。

「Webサービスのコンパイルと再ビルド」を参照してください。

クライアント側のSOAPメッセージ・ハンドラおよびハンドラ・チェーンの作成については、「クライアント側SOAPメッセージ・ハンドラの作成と使用」を参照してください。

SOAPメッセージ・ハンドラおよびハンドラ・チェーンの設計

SOAPメッセージ・ハンドラおよびハンドラ・チェーンを設計するときには、以下の事項を決定する必要があります。

- すべての作業を実行するために必要なハンドラの数

- 実行の順序

ハンドラ・チェーン内の各ハンドラには、SOAPのリクエスト・メッセージを処理するメソッドとSOAPのレスポンス・メッセージを処理するメソッドが1つずつあります。順序付けされたハンドラのグループが、ハンドラ・チェーンです。Webサービスに、@HandlerChainと@SOAPMessageHandlerという2つのJWSアノテーションのうち1つを備えるハンドラ・チェーンが付加されていることを指定します。どちらをいつ使用するかは、後の項で説明します。

Webサービスを呼び出すときに、WebLogic Serverは次のようにハンドラを実行します。

1. ハンドラ・チェーン内のハンドラのhandleRequest()メソッドはすべて、JWSアノテーションで指定されている順序で実行されます。これらのhandleRequest()メソッドのいずれもが、SOAPのリクエスト・メッセージを変更できます。

2. ハンドラ・チェーン内の最後のハンドラのhandleRequest()メソッドが実行されると、WebLogic Serverは、Webサービスを実装するバックエンド・コンポーネントを呼び出し、最終的なSOAPのリクエスト・メッセージを渡します。

3. バックエンド・コンポーネントの実行が終了したら、ハンドラ・チェーン内のハンドラのhandleResponse()メソッドが、JWSアノテーションで指定されているのとは逆の順序で実行されます。これらのhandleResponse()メソッドのいずれもが、SOAPのレスポンス・メッセージを変更できます。

4. ハンドラ・チェーン内の最初のハンドラのhandleResponse()メソッドが実行されると、WebLogic Serverは、Webサービスを呼び出したクライアント・アプリケーションに最終的なSOAPレスポンス・メッセージを戻します。

たとえば、JWSファイルで@HandlerChain JWSアノテーションを使用して外部構成ファイルを指定することになっており、その構成ファイルでは、次の例に示す3つのハンドラが格納されたSimpleChainというハンドラ・チェーンを定義していると仮定します。

<jwshc:handler-config xmlns:jwshc="http://www.bea.com/xml/ns/jws"
xmlns:soap1="http://HandlerInfo.org/Server1"
xmlns:soap2="http://HandlerInfo.org/Server2"
xmlns="http://java.sun.com/xml/ns/j2ee" >

<jwshc:handler-chain>

<jwshc:handler-chain-name>SimpleChain</jwshc:handler-chain-name>

<jwshc:handler>
<handler-name>handlerOne</handler-name>
<handler-class>examples.webservices.soap_handlers.global_handler.ServerHandler1</handler-class>
</jwshc:handler>

<jwshc:handler>
<handler-name>handlerTwo</handler-name>
<handler-class>examples.webservices.soap_handlers.global_handler.ServerHandler2</handler-class>
</jwshc:handler>

<jwshc:handler>
<handler-name>handlerThree</handler-name>
<handler-class>examples.webservices.soap_handlers.global_handler.ServerHandler3</handler-class>
</jwshc:handler>

</jwshc:handler-chain>

</jwshc:handler-config>

次の図は、WebLogic Serverで各ハンドラのhandleRequest()メソッドとhandleResponse()メソッドが実行される順序を示しています。

図14-1 ハンドラ・メソッドの実行順序

通常、着信メッセージと発信メッセージで同じタイプの処理が必要となるので、各SOAPメッセージ・ハンドラには、リクエストSOAPメッセージとレスポンスSOAPメッセージを処理する別個のメソッドがあります。たとえば、SOAPリクエストにあるセキュア・データを復号化するhandleRequest()メソッドと、SOAPレスポンスを暗号化するhandleResponse()メソッドを持つ暗号化ハンドラを設計する場合があります。

一方、SOAPリクエストのみを処理し、それと同等のレスポンス処理は行わないハンドラを設計することもできます。

また、ハンドラ・チェーン内の次のハンドラを呼び出さず、そのまま、任意の時点でクライアント・アプリケーションにレスポンスを送信することも可能です。

GenericHandlerクラスの作成

SOAPメッセージ・ハンドラ・クラスでは、javax.rpc.xml.handler.GenericHandler抽象クラスを拡張する必要があります。この抽象クラス自体が、javax.rpc.xml.handler.Handlerインタフェースを実装します。

GenericHandlerクラスは、ハンドラの記述を容易にする便利な抽象クラスです。このクラスは、ライフサイクル・メソッドinit()およびdestroy()ならびにHandlerインタフェースの様々なhandleXXX()メソッドのデフォルト実装を提供します。ハンドラ・クラスを記述する際には、Handler実装クラスの一部としてカスタマイズが必要なメソッドのみをオーバーライドします。

特に、Handlerインタフェースには、GenericHandlerを拡張するハンドラ・クラス内で実装できる、次のメソッドが格納されています。

- init()
「Handler.init()メソッドの実装」を参照してください。

- destroy()
「Handler.destroy()メソッドの実装」を参照してください。

- getHeaders()
「Handler.getHeaders()メソッドの実装」を参照してください。

- handleRequest()
「Handler.handleRequest()メソッドの実装」を参照してください。

- handleResponse()
「Handler.handleResponse()メソッドの実装」を参照してください。

- handleFault()
「Handler.handleFault()メソッドの実装」を参照してください。

特に画像などの添付ファイルを処理する場合などには、ハンドラ内から直接SOAPメッセージを表示または更新しなければならない場合もあります。その場合には、javax.xml.soap.SOAPMessage抽象クラスを使用します。このクラスは、「https://saaj.dev.java.net/.」にあるSOAP With Attachments API for Java 1.1 (SAAJ)仕様の構成要素です。詳細については、「SAAJを使用したSOAPリクエスト・メッセージおよびレスポンス・メッセージの直接操作」を参照してください。

次の例は、SOAPのリクエストおよびレスポンス・メッセージをWebLogic Serverのログ・ファイルに出力する簡単なSOAPメッセージ・ハンドラを示しています。

package examples.webservices.soap_handlers.global_handler;

import javax.xml.namespace.QName;
import javax.xml.rpc.handler.HandlerInfo;
import javax.xml.rpc.handler.GenericHandler;
import javax.xml.rpc.handler.MessageContext;
import javax.xml.rpc.handler.soap.SOAPMessageContext;
import javax.xml.rpc.JAXRPCException;

import weblogic.logging.NonCatalogLogger;

/**
* This class implements a handler in the handler chain, used to access the SOAP
* request and response message.
* <p>
* This class extends the <code>javax.xml.rpc.handler.GenericHandler</code>
* abstract classs and simply prints the SOAP request and response messages to
* the server log file before the messages are processed by the backend
* Java class that implements the Web Service itself.
*/

public class ServerHandler1 extends GenericHandler {

private NonCatalogLogger log;

private HandlerInfo handlerInfo;

/**
*  Initializes the instance of the handler.  Creates a nonCatalogLogger to
*  log messages to.
*/

public void init(HandlerInfo hi) {

log = new NonCatalogLogger("WebService-LogHandler");
handlerInfo = hi;
}

/**
* Specifies that the SOAP request message be logged to a log file before the
* message is sent to the Java class that implements the Web Service.
*/

public boolean handleRequest(MessageContext context) {

SOAPMessageContext messageContext = (SOAPMessageContext) context;

System.out.println("** Request: "+messageContext.getMessage().toString());
log.info(messageContext.getMessage().toString());
return true;

}

/**
* Specifies that the SOAP response message be logged to a log file before the
* message is sent back to the client application that invoked the Web
* service.
*/

public boolean handleResponse(MessageContext context) {

SOAPMessageContext messageContext = (SOAPMessageContext) context;

System.out.println("** Response: "+messageContext.getMessage().toString());
log.info(messageContext.getMessage().toString());
return true;

}

/**
* Specifies that a message be logged to the log file if a SOAP fault is
* thrown by the Handler instance.
*/

public boolean handleFault(MessageContext context) {

SOAPMessageContext messageContext = (SOAPMessageContext) context;

System.out.println("** Fault: "+messageContext.getMessage().toString());
log.info(messageContext.getMessage().toString());
return true;

}

public QName[] getHeaders() {

return handlerInfo.getHeaders();

}

}

Handler.init()メソッドの実装

Handler.init()メソッドは、Handlerオブジェクトのインスタンスを作成し、そのインスタンスが自動的に初期化されるようにするために呼び出されます。そのシグネチャは次のとおりです。

public void init(HandlerInfo config) throws JAXRPCException {}

HandlerInfoオブジェクトには、SOAPメッセージ・ハンドラ情報、特に初期化パラメータが格納されています。HandlerInfo.getHandlerConfig()メソッドを使用してパラメータを取得すると、このメソッドは、名前と値のペアの入ったjava.util.Mapオブジェクトを返します。

初期化パラメータを処理する必要がある場合、または、他の初期化タスクを実行する必要がある場合は、init()メソッドを実装します。

初期化パラメータの使用例としては、デバッグのオン、オフ、メッセージやエラーを書き込むためのログ・ファイルの名前の指定などがあります。

Handler.destroy()メソッドの実装

Handler.destroy()メソッドは、Handlerオブジェクトのインスタンスを破棄するために呼び出されます。そのシグネチャは次のとおりです。

public void destroy() throws JAXRPCException {}

destroy()メソッドを実装すると、ハンドラのライフサイクルを通じて取得されたあらゆるリソースを解放できます。

Handler.getHeaders()メソッドの実装

Handler.getHeaders()メソッドは、このHandlerインスタンスで処理できるヘッダー・ブロックを取得します。そのシグネチャは次のとおりです。

public QName[] getHeaders() {}

Handler.handleRequest()メソッドの実装

Handler.handleRequest()メソッドは、バックエンド・コンポーネントによって処理される前にSOAPのリクエスト・メッセージをインターセプトするために呼び出されます。そのシグネチャは次のとおりです。

public boolean handleRequest(MessageContext mc)
throws JAXRPCException,SOAPFaultException  {}

このメソッドを実装すると、バックエンド・コンポーネントによって処理される前のSOAPメッセージ内のデータの復号化などのタスクが実行できます。

MessageContextオブジェクトは、SOAPメッセージ・ハンドラによって処理されたメッセージのコンテキストを抽出します。MessageContextプロパティにより、ハンドラ・チェーン内のハンドラは処理ステートを共有できます。

MessageContextのSOAPMessageContextサブインタフェースを使用すると、SOAPのリクエスト・メッセージの内容を取得または更新することができます。SOAPのリクエスト・メッセージそのものは、javax.xml.soap.SOAPMessageオブジェクトに格納されます。このオブジェクトの詳細は、「SAAJを使用してSOAPリクエスト・メッセージおよびレスポンス・メッセージの直接操作」を参照してください。

SOAPMessageContextクラスは、SOAPリクエストを処理する次の2つのメソッドを定義します。

- SOAPMessageContext.getMessage(): SOAPのリクエスト・メッセージの入ったjavax.xml.soap.SOAPMessageオブジェクトを返します。

- SOAPMessageContext.setMessage(javax.xml.soap.SOAPMessage): SOAPのリクエスト・メッセージを変更後、それを更新します。

SOAPリクエストのすべての処理をコーディングしたら、次のシナリオのいずれかをコーディングします。

- trueを返すことにより、ハンドラ・リクエスト・チェーン内の次のハンドラを呼び出します。
リクエスト・チェーンの次のハンドラは、@HandlerChainアノテーションによって指定された構成ファイル内の<handler-chain>要素の次の<handler>サブ要素と、@SOAPMessageHandlersアノテーションによって指定された配列内の次の@SOAPMessageHandlerのいずれかとして指定されます。チェーン内のすべてのハンドラが実行されたら、メソッドはWebサービスの構成に応じて、バックエンド・コンポーネントの呼出し、最終的なSOAPのリクエスト・メッセージの送信、または最後のハンドラのhandleResponse()メソッドの呼出しを行います。

- falseを返すことにより、ハンドラ・リクエスト・チェーンの処理をブロックします。
ハンドラ・リクエスト・チェーンの処理をブロックすると、Webサービスのこの呼出しについては、バックエンド・コンポーネントは実行されなくなります。Webサービスの一部の呼出しの結果をキャッシュしてあり、そのリストに現在の呼出しも含まれている場合は、この操作が便利な場合があります。

ハンドラ・リクエスト・チェーンの処理は中断されますが、WebLogic Serverが、現在のハンドラから順に、レスポンス・チェーンを呼び出します。たとえば、ハンドラ・チェーンに、handlerAとhandlerBという2つのハンドラがあると想定します。ここで、handlerAのhandleRequest()メソッドは、handlerBの対応するメソッドの前に呼び出されるものとします。handlerAで処理がブロックされると(したがってhandlerBのhandleRequest()メソッドは呼び出されません)、ハンドラ・レスポンス・チェーンはhandlerAで開始され、handlerBのhandleRequest()メソッドも呼び出されません。

- javax.xml.rpc.soap.SOAPFaultExceptionをスローして、SOAPフォルトを示します。
handleRequest()メソッドがSOAPFaultExceptionをスローすると、WebLogic Serverは、この例外を取得して、ハンドラ・リクエスト・チェーンの後続の処理を終了し、このハンドラのhandleFault()メソッドを呼び出します。

- あらゆるハンドラ固有の実行時エラーに対してJAXRPCExceptionをスローします。
handleRequest()メソッドがJAXRPCExceptionをスローすると、WebLogic Serverは、この例外を取得して、ハンドラ・リクエスト・チェーンの後続の処理を終了し、この例外をWebLogic Serverのログ・ファイルに記録し、このハンドラのhandleFault()メソッドを呼び出します。

Handler.handleResponse()メソッドの実装

Handler.handleResponse()メソッドは、SOAPのレスポンス・メッセージがバックエンド・コンポーネントによって処理された後、Webサービスを呼び出したクライアント・アプリケーションに戻される前に、そのメッセージをインターセプトするために呼び出されます。そのシグネチャは次のとおりです。

public boolean handleResponse(MessageContext mc) throws JAXRPCException {}

このメソッドを実装すると、クライアント・アプリケーションに返される前にSOAPメッセージに含まれているデータを暗号化したり、戻り値に処理を加えたりといったタスクを実行できます。

MessageContextオブジェクトは、SOAPメッセージ・ハンドラによって処理されたメッセージのコンテキストを抽出します。MessageContextプロパティにより、ハンドラ・チェーン内のハンドラは処理ステートを共有できます。

MessageContextのSOAPMessageContextサブインタフェースを使用すると、SOAPのレスポンス・メッセージの内容を取得または更新することができます。SOAPのレスポンス・メッセージそのものは、javax.xml.soap.SOAPMessageオブジェクトに格納されます。「SAAJを使用したSOAPリクエスト・メッセージおよびレスポンス・メッセージの直接操作」を参照してください。

SOAPMessageContextクラスは、SOAPレスポンスを処理する次の2つのメソッドを定義します。

- SOAPMessageContext.getMessage(): SOAPのレスポンス・メッセージの入ったjavax.xml.soap.SOAPMessageオブジェクトを返します。

- SOAPMessageContext.setMessage(javax.xml.soap.SOAPMessage): SOAPのレスポンス・メッセージを変更後、それを更新します。

SOAPレスポンスのすべての処理をコーディングしたら、次のシナリオのいずれかをコーディングします。

- trueを返すことにより、ハンドラ・レスポンス・チェーン内の次のハンドラを呼び出します。
ハンドラ・チェーンの次のレスポンスは、@HandlerChainアノテーションによって指定された構成ファイル内の<handler-chain>要素の前の<handler>サブ要素か、@SOAPMessageHandlersアノテーションによって指定された配列内の前の@SOAPMessageHandlerのいずれかとして指定されます(ハンドラ・チェーン上のレスポンスは、JWSファイルで指定されたのと逆の順序で実行されることに留意してください。詳細については、「SOAPメッセージ・ハンドラおよびハンドラ・チェーンの設計」を参照してください)。

ハンドラ・チェーン内のすべてのハンドラが実行されたら、メソッドは、Webサービスを呼び出したクライアント・アプリケーションに最終的なSOAPのレスポンス・メッセージを戻します。

- falseを返すことにより、ハンドラ・レスポンス・チェーンの処理をブロックします。
ハンドラ・レスポンス・チェーンの処理をブロックすると、レスポンス・チェーンにある残りのハンドラが、Webサービスのこの呼出しについては実行されなくなり、現在のSOAPメッセージがクライアント・アプリケーションに戻されます。

- あらゆるハンドラ固有の実行時エラーに対してJAXRPCExceptionをスローします。
handleRequest()メソッドがJAXRPCExceptionをスローすると、WebLogic Serverは、この例外を取得して、ハンドラ・リクエスト・チェーンの後続の処理を終了し、この例外をWebLogic Serverのログ・ファイルに記録し、このハンドラのhandleFault()メソッドを呼び出します。

Handler.handleFault()メソッドの実装

Handler.handleFault()メソッドは、SOAPメッセージ処理モデルに基づいてSOAP障害を処理します。そのシグネチャは次のとおりです。

public boolean handleFault(MessageContext mc) throws JAXRPCException  {}

このメソッドを実装すると、バックエンド・コンポーネントによって生成されたフォルトのほか、handleResponse()メソッドおよびhandleRequest()メソッドによって生成されたあらゆるSOAPフォルトの処理も扱うことができます。

MessageContextオブジェクトは、SOAPメッセージ・ハンドラによって処理されたメッセージのコンテキストを抽出します。MessageContextプロパティにより、ハンドラ・チェーン内のハンドラは処理ステートを共有できます。

MessageContextのSOAPMessageContextサブインタフェースを使用すると、SOAPメッセージの内容を取得または更新することができます。SOAPメッセージそのものは、javax.xml.soap.SOAPMessageオブジェクトに格納されます。「SAAJを使用したSOAPリクエスト・メッセージおよびレスポンス・メッセージの直接操作」を参照してください。

SOAPMessageContextクラスは、SOAPメッセージを処理する次の2つのメソッドを定義します。

- SOAPMessageContext.getMessage(): SOAPメッセージの入ったjavax.xml.soap.SOAPMessageオブジェクトを返します。

- SOAPMessageContext.setMessage(javax.xml.soap.SOAPMessage): SOAPのメッセージを変更後、それを更新します。

SOAPフォルトのすべての処理をコーディングしたら、次のいずれかを実行します。

- trueを返すことにより、ハンドラ・チェーン内の次のハンドラのhandleFault()メソッドを呼び出します。

- falseを返すことにより、ハンドラ・フォルト・チェーンの処理をブロックします。

SAAJを使用したSOAPリクエスト・メッセージおよびレスポンス・メッセージの直接操作

javax.xml.soap.SOAPMessage抽象クラスは、SOAP With Attachments API for Java 1.1 (SAAJ)仕様の構成要素です。(「https://saaj.dev.java.net/」を参照。)このクラスは、SOAPメッセージ・ハンドラ作成時にSOAPのリクエスト・メッセージおよびレスポンス・メッセージを操作するのに使用します。この節では、SOAPMessageオブジェクトの基本構造とSOAPメッセージの表示および更新に役立つメソッドのいくつかについて説明します。

SOAPMessageオブジェクトは、SOAPPartオブジェクト(SOAP XMLドキュメントそのものが入っています)、または同オブジェクトと添付ファイルで構成されています。

SOAPMessageクラスの詳細な説明については、SAAJに関するJavadocを参照してください。

SOAPPartオブジェクト

SOAPPartオブジェクトには、SOAPEnvelopeオブジェクトに格納されたXML SOAPドキュメントが入っています。このオブジェクトは、実際のSOAPのヘッダーと本文を取得するのに使用します。

次のJavaコードのサンプルは、Handlerクラスによって提供されたMessageContextオブジェクトからSOAPメッセージを取り出して、その各部を参照する方法を示しています。

SOAPMessage soapMessage =  messageContext.getMessage();
SOAPPart soapPart = soapMessage.getSOAPPart();
SOAPEnvelope soapEnvelope = soapPart.getEnvelope();
SOAPBody soapBody = soapEnvelope.getBody();
SOAPHeader soapHeader = soapEnvelope.getHeader();

AttachmentPartオブジェクト

javax.xml.soap.AttachmentPartオブジェクトには、SOAPメッセージに対するオプションの添付ファイルが入っています。添付ファイルは、SOAPメッセージの残りの部分とは異なり、XMLフォーマットの必須部分ではないので、その形式は、単純なテキストからイメージ・ファイルまで、様々です。

注意:
SOAPメッセージ・ハンドラから直接に添付ファイルjava.awt.Imageにアクセスする場合は、「SOAPメッセージ・ハンドラで画像添付ファイルの操作」で重要情報を参照してください。

添付ファイルを操作するには、SOAPMessageクラスの以下のメソッドを使用します。

- countAttachments(): このSOAPメッセージに含まれている添付ファイルの数を返します。

- getAttachments(): すべての添付ファイルを取り出し、(AttachmentPartオブジェクトとして) Iteratorオブジェクトに格納します。

- createAttachmentPart(): 他のタイプのObjectからAttachmentPartオブジェクトを作成します。

- addAttachmentPart(): 作成されたAttachmentPartオブジェクトをSOAPMessageに追加します。

SOAPメッセージ・ハンドラで画像添付ファイルの操作

この節では、添付ファイルjava.awt.ImageにアクセスするSOAPメッセージ・ハンドラを作成すること、およびclientgen Antタスクによって生成されたクライアントJAX-RPCスタブを使用するクライアント・アプリケーションからImageが送信されていることを前提としています。

clientgen Antタスクによって生成されたクライアント・コードでは、添付ファイルjava.awt.Imageはimage/gifではなくtext/xmlのMIMEタイプで、呼び出されるWebLogic Webサービスに送信され、画像は画像を表す整数のストリームにシリアライズされます。特に、このクライアント・コードは次の形式で画像をシリアライズします。

- int width

- int height

- int[] pixels

つまり、受信したImage添付ファイルを操作するSOAPメッセージ・ハンドラでは、このデータ・ストリームをデシリアライズして元の画像を作成し直す必要があるということです。

JWSファイルでのハンドラの構成

Webサービスのハンドラ・チェーンを構成するためにJWSファイルで使用できる標準的なアノテーションは、@javax.jws.HandlerChainおよび@javax.jws.soap.SOAPMessageHandlersの2つです。

@javax.jws.HandlerChain

@javax.jws.HandlerChainアノテーション(この章では簡単にするため@HandlerChainとも呼びます)を使用する場合は、file属性を使用して、Webサービスと関連付けるハンドラ・チェーンの構成が含まれた外部ファイルを指定します。構成には、チェーン内のハンドラのリスト、ハンドラが実行される順序、初期化パラメータなどが含まれます。

以下の条件の1つ以上が適用される場合は、@SOAPMessageHandlersアノテーションではなく@HandlerChainアノテーションをJWSファイルで使用します:

- 複数のWebサービスで同じ構成を共有したい。

- ハンドラ・チェーンに、複数のトランスポートのハンドラが含まれている。

- Webサービスを実装するJWSファイルを再コンパイルしないで、そのWebサービスのハンドラ・チェーン構成を変更できるようにしたい。

次のJWSファイルでは、@HandlerChainアノテーションの使用例を示します。関連のJavaコードは太字で示しています。

package examples.webservices.soap_handlers.global_handler;

import java.io.Serializable;

import javax.jws.HandlerChain;
import javax.jws.WebService;
import javax.jws.WebMethod;
import javax.jws.soap.SOAPBinding;

import weblogic.jws.WLHttpTransport;

@WebService(serviceName="HandlerChainService",
name="HandlerChainPortType")

// Standard JWS annotation that specifies that the handler chain called
// "SimpleChain", configured in the HandlerConfig.xml file, should fire
// each time an operation of the Web Service is invoked.

@HandlerChain(file="HandlerConfig.xml", name="SimpleChain")

@SOAPBinding(style=SOAPBinding.Style.DOCUMENT,
use=SOAPBinding.Use.LITERAL,
parameterStyle=SOAPBinding.ParameterStyle.WRAPPED)

@WLHttpTransport(contextPath="HandlerChain", serviceUri="HandlerChain",
portName="HandlerChainServicePort")

/**
* This JWS file forms the basis of simple Java-class implemented WebLogic
* Web Service with a single operation: sayHello.  The Web Service also
* has a handler chain associated with it, as specified by the
* @HandlerChain annotation.
*/

public class HandlerChainImpl  {

public String sayHello(String input) {
weblogic.utils.Debug.say( "in backend component. input:" +input );
return "'" + input + "' to you too!";
}
}

@HandlerChainアノテーションを使用する前に、前述の例に示すように、それをJWSファイルにインポートする必要があります。

@HandlerChainアノテーションのfile属性を使用し、ハンドラ・チェーンの構成情報を含む外部ファイルの名前を指定します。この属性の値はURLです。これは相対でも絶対でもかまいません。相対URLは、ファイルをコンパイルするためにjwsc Antタスクを実行した時点でのJWSファイルの場所を基準とします。

Webサービスと関連付ける構成ファイル内のハンドラ・チェーンの名前を指定するには、name属性を使用します。この属性の値は、構成ファイル内の<handler-chain>要素のname属性に対応します。

注意:
1つのJWSファイル内に複数の@HandlerChainアノテーションを指定すると、エラーになります。また、@HandlerChainアノテーションを@SOAPMessageHandlersアノテーションと一緒に使用しても、エラーになります。

外部構成ファイル作成の詳細は、「ハンドラ・チェーン構成ファイルの作成」を参照してください。

この項で説明した標準的なJWSアノテーションの詳細は、Web Services Metadata for the Java Platform仕様(http://www.jcp.org/en/jsr/detail?id=181)を参照してください。

@javax.jws.soap.SOAPMessageHandlers

注意:
このアノテーションは、Web Services Metadata for the Java Platform仕様(JSR-181)(http://www.jcp.org/en/jsr/detail?id=181)では非推奨となっています。

@javax.jws.soap.SOAPMessageHandlers(この項では簡単にするため@SOAPMessageHandlersとも呼びます)アノテーションを使用する場合、JWSファイル自体の中で、Webサービス操作の前と後に実行するSOAPメッセージ・ハンドラの配列を指定します(@SOAPMessageHandlerアノテーションで指定)。@SOAPMessageHandlerアノテーションには、ハンドラのクラス名、初期化パラメータ、ハンドラで処理されるSOAPヘッダーのリストなどを指定する属性が含まれます。JWSファイル自体の内部でハンドラのリストを指定するので、ハンドラ・チェーンの構成はWebサービス内に埋め込まれます。

以下の条件の1つ以上が適用される場合は、@SOAPMessageHandlersアノテーションを使用します:

- 外部のファイルで構成を指定するのではなく、Webサービス自体の内部にハンドラ・チェーンの構成を埋め込みたい。

- ハンドラ・チェーンにSOAPハンドラのみが含まれており、それ以外のトランスポート用のハンドラは含まれていない。

- ハンドラ・チェーンの構成を変更するたびにJWSファイルを再コンパイルしたい。

次のJWSファイルでは、@SOAPMessageHandlersアノテーションの簡単な使用例を示します。関連のJavaコードは太字で示しています。

package examples.webservices.soap_handlers.simple;

import java.io.Serializable;

import javax.jws.soap.SOAPMessageHandlers;
import javax.jws.soap.SOAPMessageHandler;
import javax.jws.soap.SOAPBinding;
import javax.jws.WebService;
import javax.jws.WebMethod;

import weblogic.jws.WLHttpTransport;

@WebService(name="SimpleChainPortType",
serviceName="SimpleChainService")

// Standard JWS annotation that specifies a list of SOAP message handlers
// that exeucte before and after an invocation of all operations in the
// Web Serice.

@SOAPMessageHandlers ( {
@SOAPMessageHandler (
className="examples.webservices.soap_handlers.simple.ServerHandler1"),
@SOAPMessageHandler (
className="examples.webservices.soap_handlers.simple.ServerHandler2")
} )

@SOAPBinding(style=SOAPBinding.Style.DOCUMENT,
use=SOAPBinding.Use.LITERAL,
parameterStyle=SOAPBinding.ParameterStyle.WRAPPED)

@WLHttpTransport(contextPath="SimpleChain", serviceUri="SimpleChain",
portName="SimpleChainServicePort")

/**
* This JWS file forms the basis of simple Java-class implemented WebLogic
* Web Service with a single operation: sayHello.  The Web Service also
* has a handler chain associated with it, as specified by the
* @SOAPMessageHandler/s annotations.
*/

public class SimpleChainImpl  {

// by default all public methods are exposed as operations

public String sayHello(String input)  {
weblogic.utils.Debug.say( "in backend component. input:" +input );
return "'" + input + "' to you too!";
}
}

@SOAPMessageHandlersアノテーションおよび@SOAPMessageHandlerアノテーションを使用する前に、前述の例に示すように、それらをJWSファイルにインポートする必要があります。これらのアノテーションは、javax.jws.soapパッケージに入っています。

@SOAPMessageHandlers配列で(@SOAPMessageHandlerアノテーションを使用して)ハンドラをリストした順序により、ハンドラの実行の順序(操作前なら順序どおりに、操作後なら逆順で)が指定されます。前述のサンプルでは、ハンドラ・チェーンにおいて2つのハンドラを構成しています。これらのハンドラのクラス名は、examples.webservices.soap_handlers.simple.ServerHandler1とexamples.webservices.soap_handlers.simple.ServerHandler2です。

@SOAPMessageHandlerのinitParams属性を使用すると、特定のハンドラにおいて予期されている初期化パラメータの配列を指定できます。@InitParam標準JWSアノテーションを使用し、次の例のように、名前と値のペアを指定します。

@SOAPMessageHandler(
className = "examples.webservices.soap_handlers.simple.ServerHandler1",
initParams = { @InitParam(name="logCategory", value="MyService")}
)

また、@SOAPMessageHandlerアノテーションには、ハンドラによって実装されるSOAPロールをリストするためのroles属性、およびハンドラによって処理されるSOAPヘッダーをリストするためのheaders属性も含まれています。

注意:
@SOAPMessageHandlersアノテーションを@HandlerChainアノテーションと一緒に使用すると、エラーになります。

この項で説明した標準的なJWSアノテーションの詳細は、Web Services Metadata for the Java Platform仕様(http://www.jcp.org/en/jsr/detail?id=181)を参照してください。

ハンドラ・チェーン構成ファイルの作成

JWSファイルで@HandlerChainアノテーションを使用して、ハンドラ・チェーンをWebサービスと関連付けることにした場合は、ハンドラ・チェーン内のハンドラのリスト、それらの実行順、初期化パラメータなどを指定する外部構成ファイルを作成する必要があります。

このファイルはJWSファイルの外部にあるため、この単一の構成ファイルを複数のWebサービスで使用するように構成し、エンタープライズ内のすべてのWebサービスに関してハンドラ構成ファイルを標準化することができます。加えて、すべてのWebサービスを再コンパイルすることなく、ハンドラ・チェーンの構成を変更できます。なお、非SOAPのトランスポートを使用するハンドラ・チェーンにハンドラを入れた場合、@SOAPMessageHandlerアノテーションではなく@HandlerChainアノテーションを使用することが必要となります。

構成ファイルは、次の簡単なサンプルに示すように、XMLを使用して1つまたは複数のハンドラ・チェーンをリストします。

<jwshc:handler-config xmlns:jwshc="http://www.bea.com/xml/ns/jws"
xmlns:soap1="http://HandlerInfo.org/Server1"
xmlns:soap2="http://HandlerInfo.org/Server2"
xmlns="http://java.sun.com/xml/ns/j2ee" >
<jwshc:handler-chain>
<jwshc:handler-chain-name>SimpleChain</jwshc:handler-chain-name>
<jwshc:handler>
<handler-name>handler1</handler-name>
<handler-class>examples.webservices.soap_handlers.global_handler.ServerHandler1</handler-class>
</jwshc:handler>
<jwshc:handler>
<handler-name>handler2</handler-name>
<handler-class>examples.webservices.soap_handlers.global_handler.ServerHandler2</handler-class>
</jwshc:handler>
</jwshc:handler-chain>
</jwshc:handler-config>

この例では、SimpleChainというハンドラ・チェーンに、handler1およびhandler2という2つのハンドラが入っています。これらは<handler-class>要素で指定されるクラス名で実装されます。2つのハンドラは、関連のWebサービス操作の前には昇順で実行され、操作実行後には逆順で実行されます。

ハンドラ初期化パラメータ、ハンドラによって実装されるSOAPロール、およびハンドラによって処理されるSOAPヘッダーを指定するには、それぞれ<handler>要素の<init-param>、<soap-role>、および<soap-header>子要素を使用します。

外部構成ファイルを定義するXMLスキーマ、その作成の詳細、および他のサンプルについては、Web Services Metadata for the Java Platform仕様(http://www.jcp.org/en/jsr/detail?id=181)を参照してください。

Webサービスのコンパイルと再ビルド

この項では、Webサービスをコンパイルおよびビルドする作業用のbuild.xml Antファイルがあり、そのビルド・ファイルを更新してハンドラ・チェーンを含めることを想定しています。このbuild.xmlファイルの作成の詳細は、「JAX-RPC Webサービスの開発」を参照してください。

メッセージ・ハンドラのコンパイルとビルドが含まれるように開発環境を更新するには、以下のガイドラインに従います。

- @HandlerChainまたは@SOAPMessageHandlersアノテーションでJWSファイルを更新後、jwsc Antタスクを再実行して、JWSファイルを再コンパイルし、新しいWebサービスを生成する必要があります。これは、JWSファイル内のアノテーションに変更を加えた場合は常に当てはまります。
JWSファイルで@HandlerChainアノテーションを使用し、jwsc Antタスクを再実行してWebサービスを再生成し、その後、外部構成ファイルのみを変更した場合は、2度目の変更を有効にするためにjwscを再実行する必要はありません。

- 以下の条件がすべて満たされていれば、jwsc AntタスクはSOAPメッセージ・ハンドラJavaファイルをハンドラ・クラスにコンパイル(およびその後それらを生成されたアプリケーションにパッケージ化)します。

- ハンドラ・クラスはJWSファイルの@HandlerChainまたは@SOAPMessageHandler(s)アノテーションにおいて参照されます。

- Javaファイルはsourcepath属性で指定されたディレクトリ内に置かれます。

- クラスは現在CLASSPATH内に存在しません。

ハンドラ・クラスをjwscで自動的にコンパイルするのではなく、ユーザー側でコンパイルする場合は、jwsc Antタスクを実行する前に、コンパイルされたクラスがCLASSPATH内にあることを確認してください。

- ハンドラ・チェーンが関連付けられているWebサービスのデプロイおよび呼出しは、ハンドラ・チェーンのないWebサービスのデプロイおよび呼出しと同様に行います。唯一の相違点は、Webサービスのどの操作を呼び出す場合でも、WebLogic Webサービス・ランタイムは、操作呼出しの前と後の両方で、ハンドラ・チェーン内のハンドラを実行するということです。

クライアント側SOAPメッセージ・ハンドラの作成と使用

ここまでの各項では、WebLogic Serverで動作するWebサービスの一環として実行される、サーバー側SOAPメッセージ・ハンドラを作成する方法について説明してきました。この他に、Webサービス操作を呼び出すクライアント・アプリケーションの一環として実行される、クライアント側ハンドラを作成することもできます。クライアント側ハンドラの場合は、以下のタイミングで二度実行されます。

- クライアント・アプリケーションがWebサービスにSOAPリクエストを送信する直前

- クライアント・アプリケーションがWebサービスからSOAPレスポンスを受信した直後

クライアント側SOAPメッセージ・ハンドラは、スタンドアロン・クライアントと、WebLogic Server内部で実行されるクライアントの、双方のために構成できます。

実際のJavaクライアント側ハンドラは、サーバー側ハンドラと同じ方法、つまりjavax.xml.rpc.handler.GenericHandler抽象クラスを拡張するJavaクラスを記述する方法で作成できます。多くの場合、WebLogic Serverで実行されるWebサービスとそのWebサービスを呼び出すクライアント・アプリケーションで、同じハンドラ・クラスを使用できます。たとえば、サーバーおよびクライアント用として、送信および受信したすべてのSOAPメッセージをログに記録する汎用ロギング・ハンドラ・クラスを記述できます。

サーバー側SOAPハンドラのプログラミングと同様に、クライアント側SOAPメッセージ・ハンドラを呼び出すclientgen AntタスクもXMLファイルを使用して指定します。ただし、次の手順で説明するように、このXMLファイルのXMLスキーマは少し異なります。

クライアント側SOAPメッセージ・ハンドラの使用: 主な手順

次の手順では、Webサービス操作を呼び出すクライアント・アプリケーションにクライアント側SOAPメッセージ・ハンドラを追加する主要な手順を説明します。

デプロイされたWebサービスを呼び出すクライアント・アプリケーションを作成済であり、クライアント側SOAPメッセージ・ハンドラおよびハンドラ・チェーンを追加してクライアント・アプリケーションを更新することを想定しています。また、Antベースの開発環境を設定済であり、かつclientgen Antタスクを実行するためのターゲットを含む、作業用のbuild.xmlファイルがあることが前提となっています。詳細は、「JAX-RPC Webサービス・クライアントの開発」を参照してください。

1. クライアント側SOAPハンドラと、それらのハンドラの実行順序を指定するハンドラ・チェーンを設計します。この手順は、視点がWebサービスからではなくクライアント・アプリケーションからとなる点を除けば、サーバー側SOAPメッセージ・ハンドラを設計するのとほぼ同じです。
「SOAPメッセージ・ハンドラおよびハンドラ・チェーンの設計」を参照してください。

2. ハンドラ・チェーン内の各ハンドラについて、javax.xml.rpc.handler.GenericHandler抽象クラスを拡張するJavaクラスを作成します。この手順は、チェーン内のハンドラをサーバーではなくクライアントで実行する点を除けば、サーバー側ハンドラの場合の手順と非常に似ています。
ハンドラ・クラスのプログラミングの詳細は、「GenericHandlerクラスの作成」を参照してください。サンプルについては、「クライアント側ハンドラ・クラスの例」を参照してください。

3. クライアント側SOAPハンドラの構成ファイルを作成します。このXMLファイルでは、ハンドラ・チェーン内のハンドラ、ハンドラが実行される順序、送信すべき初期化パラメータなどを記述します。
「クライアント側SOAPハンドラの構成ファイルの作成」を参照してください。

4. クライアント・アプリケーションのビルドに使用するbuild.xmlファイルを更新して、clientgen AntタスクにSOAPハンドラの構成ファイルの名前を指定します。また、build.xmlファイルによってハンドラ・ファイルがJavaクラスにコンパイルされ、クライアント・アプリケーションで使用できる状態になることも確認します。
「クライアント側SOAPハンドラの構成ファイルのclientgenへの指定」を参照してください。

5. 適切なタスクを実行して、クライアント・アプリケーションを再ビルドします。

prompt> ant build-client

次回クライアント・アプリケーションを実行したときには、SOAPリクエスト・メッセージの送信前とレスポンスの受信後に、構成ファイルに記述したSOAPメッセージ・ハンドラが自動的に実行されます。

注意:
clientgen Antタスクにハンドラの構成ファイルが指定されているかぎり、クライアント側SOAPメッセージ・ハンドラを呼び出すために実際のクライアント・アプリケーションを更新する必要はありません。ハンドラは、生成されたJAX-RPCスタブによって自動的に正しい順序で実行されます。

クライアント側ハンドラ・クラスの例

次の例では、Webサービスを呼び出すクライアント・アプリケーション用に構成できる単純なSOAPメッセージ・ハンドラ・クラスを示します。

package examples.webservices.client_handler.client;

import javax.xml.namespace.QName;
import javax.xml.rpc.handler.HandlerInfo;
import javax.xml.rpc.handler.GenericHandler;
import javax.xml.rpc.handler.MessageContext;

public class ClientHandler1 extends GenericHandler {

private QName[] headers;

public void init(HandlerInfo hi) {
System.out.println("in " + this.getClass() + " init()");
}

public boolean handleRequest(MessageContext context) {
System.out.println("in " + this.getClass() + " handleRequest()");
return true;
}

public boolean handleResponse(MessageContext context) {
System.out.println("in " + this.getClass() + " handleResponse()");
return true;
}

public boolean handleFault(MessageContext context) {
System.out.println("in " + this.getClass() + " handleFault()");
return true;
}

public QName[] getHeaders() {
return headers;
}
}

クライアント側SOAPハンドラの構成ファイルの作成

クライアント側SOAPハンドラの構成ファイルでは、ハンドラ・チェーン内のハンドラのリスト、ハンドラが実行される順序、初期化パラメータなどを指定します。このファイルの詳細は、「クライアント側ハンドラの構成ファイル用XMLスキーマ」を参照してください。

この構成ファイルでは、1つまたは複数のハンドラを含む1つのハンドラ・チェーンをXMLで記述します。次に単純な例を示します。

<weblogic-wsee-clientHandlerChain
xmlns="http://www.bea.com/ns/weblogic/90"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:j2ee="http://java.sun.com/xml/ns/j2ee">

<handler>
<j2ee:handler-name>clienthandler1</j2ee:handler-name>
<j2ee:handler-class>examples.webservices.client_handler.client.ClientHandler1</j2ee:handler-class>
<j2ee:init-param>
<j2ee:param-name>ClientParam1</j2ee:param-name>
<j2ee:param-value>value1</j2ee:param-value>
</j2ee:init-param>
</handler>

<handler>
<j2ee:handler-name>clienthandler2</j2ee:handler-name>
<j2ee:handler-class>examples.webservices.client_handler.client.ClientHandler2</j2ee:handler-class>
</handler>

</weblogic-wsee-clientHandlerChain>

この例では、ハンドラ・チェーンに2つのハンドラ(clienthandler1およびclienthandler2)が含まれており、<j2ee:handler-class>要素に指定されたクラス名で実装されています。これら2つのハンドラは、クライアント・アプリケーションがSOAPリクエストをWebサービスに送信する直前に指定の順序で実行され、クライアント・アプリケーションがWebサービスからのSOAPレスポンスを受信した直後に逆の順序で実行されます。

この例では、<j2ee:init-param>要素を使用して1つまたは複数の初期化パラメータをハンドラに指定する方法も示しています。

ハンドラによって実装されるSOAPロール、ハンドラによって処理されるSOAPヘッダー、およびハンドラが関連付けられているWSDLのポート名要素を指定するには、それぞれ、<handler>要素の子要素である<soap-role>、<soap-header>、および<port-name>を使用します。

クライアント側ハンドラの構成ファイル用XMLスキーマ

次のXMLスキーマ・ファイルでは、クライアント側SOAPハンドラの構成ファイルの構造を定義しています。

<?xml version="1.0" encoding="UTF-8"?>

<schema
targetNamespace="http://www.bea.com/ns/weblogic/90"
xmlns:wls="http://www.bea.com/ns/weblogic/90"
xmlns:j2ee="http://java.sun.com/xml/ns/j2ee"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified"
attributeFormDefault="unqualified"
>
<include schemaLocation="weblogic-j2ee.xsd"/>

<element name="weblogic-wsee-clientHandlerChain"
type="wls:weblogic-wsee-clientHandlerChainType">
<xsd:key name="wsee-clienthandler-name-key">
<xsd:annotation>
<xsd:documentation>

Defines the name of the handler. The name must be unique within the
chain.

</xsd:documentation>
</xsd:annotation>
<xsd:selector xpath="j2ee:handler"/>
<xsd:field xpath="j2ee:handler-name"/>
</xsd:key>
</element>

<complexType name="weblogic-wsee-clientHandlerChainType">
<sequence>
<xsd:element name="handler"
type="j2ee:service-ref_handlerType"
minOccurs="0" maxOccurs="unbounded">
</xsd:element>
</sequence>
</complexType>
</schema>

1つの構成ファイルで、1つのクライアント側ハンドラ・チェーンを指定します。構成ファイルのルートは<weblogic-wsee-clientHandlerChain>で、ファイルにはゼロ個以上の<handler>子要素(それぞれがチェーン内の各ハンドラを記述しています)が含まれます。

<handler>要素の構造は、Java EE 1.4 Web service client XML Schema(http://java.sun.com/xml/ns/j2ee/j2ee_web_services_client_1_1.xsd)で指定されているJava EEのservice-ref_handlerType複合型で記述します。

クライアント側SOAPハンドラの構成ファイルのclientgenへの指定

クライアント側SOAPハンドラの構成ファイルを指定するには、clientgen AntタスクのhandlerChainFile属性を使用します。次に、build.xmlファイルからの抜粋を示します。

<clientgen
wsdl="http://ariel:7001/handlers/ClientHandlerService?WSDL"
destDir="${clientclass-dir}"
handlerChainFile="ClientHandlerChain.xml"
packageName="examples.webservices.client_handler.client"/>

clientgenによって自動的に生成されたJAX-RPCスタブを使用すると、クライアント・アプリケーションがWebサービス操作を呼び出す前と後に、構成ファイルで記述されたハンドラが必ず正しい順序で実行されます。

15 Database Webサービスの使用

この章では、Database Webサービスの使用方法について説明します。

この章の内容は次のとおりです。

- Database Webサービスの概要

- SQLとXMLの間のタイプ・マッピング

Database Webサービスの概要

注意:
Oracle JDeveloperでのJAX-RPCサポートの中止により、PL/SQLデータベースWebサービスの開発時サポートはなくなりましたが、WebLogic Server実行時環境でのサポートは継続されます。
『Oracle JDeveloperによるアプリケーションの開発』のTopLinkデータベースWebサービス・プロバイダの作成に関する項で説明しているように、設計時にOracle TopLinkデータベースJAX-WS Webサービス・プロバイダを作成できます。

異機種環境と接続されていない環境で、Webサービスのインタフェースを介してストアド・プロシージャ、データおよびメタデータにアクセスするニーズが増加しています。Database Webサービスの技術は、データベースに対するWebサービスを有効にします。以下の2つの方向に機能します。

- Databaseコールイン — Webサービスとしてのデータベース・リソースへのアクセス

- Databaseコールアウト — データベースからの外部Webサービスの消費

Databaseコールイン

OracleデータベースがWebサービス・プロバイダに取り込まれると、Javaストアド・プロシージャ、PL/SQLパッケージ、詳細キュー、定義済のSQL問合せおよびDMLなどの機能を利用できます。

注意:
このリリースでは、問合せ、Java、DMLおよび詳細キュー以外のWebサービスの作成はサポートされません。

クライアント・アプリケーションは、問合せを実行し、Oracleデータベースからデータを取得して、標準のWebサービス・プロトコルを使用することによってストアド・プロシージャを呼び出します。Oracle固有のデータベースの接続プロトコルへの依存はありません。アプリケーションは、キャッシュされたWebLogic Serverへのすべての接続において適用できます。このアプローチは、異種の環境、分散型環境および接続されていない環境でとても役立ちます。

Database WebサービスはWebLogic Webサービスの一部であるため、一貫性のある統一された開発およびデプロイメント環境での利用が可能です。Webサービスの公開されたデータベースとWebサービス・クライアントの間で交換されるメッセージは、WebLogic Webサービスによって提供されている管理機能(セキュリティ、信頼性、監査およびロギング)のすべてを活用できます。

次の図は、Webサービスのコールインを示しています。

図15-1 データベースへのWebサービスの呼出し

次の手順では、前の図に示した処理を説明しています。

1. データベース・サービスのタイプに対するリクエストはアプリケーション・サーバーに受信します。サービス・エンドポイントは、暗黙にリクエストされたサービスのタイプを指定します。

2. JAX-RPC処理サーブレットは、リクエストをデコードするためにSOAPライブラリとXMLパーサーを参照します。

3. サーブレットは、公開されたデータベース操作に対応するクラスにリクエストを渡します。生成されたクラスは、データベースのPL/SQLパッケージ、問合せ、DML、AQストリーム、またはJavaクラスを表すことができます。

4. データベースは、レスポンスをJAX-RPC処理サーブレットに渡し、それをエンコードするためにJAX-RPC処理サーブレットはSOAPライブラリとXMLパーサーを参照します。

5. WSDLに基づいてフォーマットされたSOAPレスポンスがクライアントに返されます。

Databaseコールアウト

Webサービスを含むように、リレーショナル・データベース・ストレージ、索引、および検索機能を拡張できます。Webサービスを呼び出すことによって、データベースは、生成されたオンデマンドの動的データ(株価、為替レート、または気象情報など)の記録、集約、リフレッシュおよび問合せができます。サービスのコンシューマとしてのデータベース使用例として、複数のサプライヤからのインベントリ情報を取得してローカル・インベントリ情報を更新するために事前定義済のデータベース・ジョブから外部Webサービスを呼び出します。もう1つの例は、Web Crawlerの例です。データベース・ジョブはいくつかのソースから製品情報と価格情報を照合できるようスケジュールします。

以下の図に、データベース・コールアウトを示します。

図15-2 データベース内からのWebサービスの呼出し

次の手順では、前の図に示した処理を説明しています。

- SQL呼出しおよびPL/SQL呼出しの仕様 - ユーザー定義関数の呼出し(SQL文内で直接呼び出すか、ビューで呼び出す)または変数を介してWebサービスを呼び出します。

- UTL_DBWS PL/SQLパッケージを使用した動的Webサービスの呼出し。CallオブジェクトはWSDLに基づいて動的に作成され、その後、Webサービス操作を呼び出すことができます。
Oracle Database PL/SQLパッケージおよびタイプ・リファレンスは、UTL_DBWS PL/SQLパッケージ使用の詳細について説明します。

- Pure Java静的プロキシ・クラス - JAX-RPCを使用しているクライアント・プロキシ・クラスを生成します。サービスの場所が既知のため、UDDIレジストリ内のサービスをルックアップせずに、このメソッドはWebサービスを簡単に呼び出します。クライアント・プロキシ・クラスは、パラメータのマーシャリングとアンマーシャリングが含まれるSOAPリクエストを構成するすべての作業を実行します。

- JAX-RPC上のDII (Dynamic Invocation Interface)を使用したPure Java - 動的呼出しはSOAPリクエストを構成して、クライアント・プロキシを使用せずにサービスにアクセスする機能を提供します。

メソッドの使用は、SQLやPL/SQLから実行するか、Javaクラスから実行するか、またはサービスがあらかじめ知られているか(静的呼出し)、実行時にのみ知られているか(DII)、によって異なります。

SQLとXMLの間のタイプ・マッピング

次の項では、Webサービスがあらかじめ知られている(静的呼出し)場合、コールインおよびコールアウトに対するSQLとXMLの間のタイプ・マッピングについて説明します。

Webサービスが実行時に既知の場合、Dynamic Invocation Interface (DII)またはUTL_DBWS PL/SQLパッケージのみが使用されます。

Webサービスのコールインに対するSQLからXMLタイプへのマッピング

Database Webサービスのコールインでは、PL/SQLストアド・プロシージャまたはSQL文などのSQL操作が1つまたは複数のWebサービス操作にマップされます。SQL操作のパラメータは、SQLタイプからXMLタイプにマップされます。

注意:
複数の操作があるのは、OracleAS WebサービスがSQL値をXMLで表すためのデータ表現方法を複数提供しているためです。たとえば、SQL結果セットを様々な方法で表現できます。

次の表では、Webサービス・コールインのSQLからXMLへのマッピングについて説明します。最初の列では、SQLタイプをリストします。XMLタイプ(リテラル)、表の2番目の列は、use属性のデフォルトのリテラル値に対するSQLからXMLタイプへのマッピングを示します。XMLタイプ(エンコード)、3番目の列は、use属性のエンコード値に対するマッピングを示します。リテラル値とエンコード値は、SOAPメッセージの本文をエンコーディングするためのルールを示します。

表15-1 Webサービス・コールインに対するSQLからXMLタイプへのマッピング

SQLタイプ

XMLタイプ(リテラル)

XMLタイプ(エンコード)

INT

int

int

INTEGER

int

int

FLOAT

double

double

NUMBER

decimal

decimal

VARCHAR2

string

string

DATE

dateTime

dateTime

TIMESTAMP

dateTime

dateTime

BLOB

byte[]

byte[]

CLOB

String

String

LONG

String

String

RAW

byte[]

byte[]

Primitive PL/SQL indexby table

Array

Array

PL/SQL Boolean

boolean

boolean

PL/SQL indexby table

complexType

complexType

PL/SQL record

complexType

complexType

REF CURSOR (nameBeans)

Array

Array

REF CURSOR

nameXML)

any

test_xml

REF CURSOR

nameMLRowSet

swaRef

test_xml

SQL object

complexType

complexType

SQL table

complexType

complexType

SYS.XMLTYPE

any

test_xml

注意:
国別言語サポート(「NLS」または「グローバライゼーション・サポート」とも呼ばれます)の文字をSQL SYS.XMLTYPE値に使用している場合、正しく処理されません。

REF CURSORを返す問合せやPL/SQL関数は、下記にリストされている3つのメソッドによってマップされます。ここでの、nameは問合せかPL/SQL関数の名前です。

- nameBeans - このメソッドは配列を返します。配列の各要素はカーソルの1つの行を表すXSD複合型のインスタンスです。複合型のサブ要素はその行の列に対応します。

- nameXMLRowSet - このメソッドは、XML形式のOracleWebRowSetを含むswaRefまたはtext_xmlレスポンスを返します。

- nameXML - このメソッドは、Oracle XDBの行セットを含む任意のXMLまたはtext_xmlレスポンスを返します。

OUTとIN OUT PL/SQLの両方のパラメータは、WSDLファイルのIN OUTパラメータにマップされます。

表15-1では、2つの異なるマッピング・タイプを提供しています。1つはリテラル、もう1つはエンコード用に使用できます。デフォルトのマッピングはリテラルです。Database Webサービスに関しては、エンコードを使用する特別な理由はありません。エンコード使用の設定を呼び出すシナリオを使用する場合のために、エンコードに対するマッピングが提供されています。この章で説明されているすべてのトピックは、特に指定しない限りリテラル使用の設定を使用することを前提としています。

Webサービス・コールアウトに対するXMLからSQLタイプへのマッピング

Database Webサービスのコールアウトでは、XMLタイプがSQLタイプにマップされています。以下の表では、コールアウトに使用するXMLからSQLタイプへのマッピングについて説明します。

表15-2 Webサービス・コールアウトに対するXMLからSQLタイプへのマッピング

XML Type

SQLタイプ

int

NUMBER

float

NUMBER

double

NUMBER

decimal

NUMBER

dateTime

DATE

String

VARCHAR2

byte[]

RAW

complexType

SQL OBJECT

Array

SQL TABLE

test_xml

XML Type

A 信頼性のあるメッセージング用にパッケージ化されているWS-Policyファイル

この付録では、あらかじめパッケージ化されているWS-Policyファイルについて説明します。このファイルには、WebLogic Java API for XML-based RPC (JAX-RPC) Webサービスで信頼性のあるメッセージングをサポートするために使用できる標準的な信頼性のあるメッセージング・アサーションが含まれています。

この付録の内容は次のとおりです。

- DefaultReliability1.1.xml (WS-Policyファイル)

- Reliability1.1_SequenceTransportSecurity.xml (WS-Policyファイル)

- Reliability1.1_SequenceSTR.xml (WS-Policyファイル)

- Reliability1.0_1.1.xml (WS-Policy.xmlファイル)

- DefaultReliability.xml (WS-Policyファイル) [非推奨]

- LongRunningReliability.xml (WS-Policyファイル) [非推奨]

これらのあらかじめパッケージ化されたファイルを変更することはできません。これらの値がニーズに合ない場合は、独自のWS-Policyファイルを作成する必要があります。詳細は、「Webサービスの信頼性のあるメッセージングのWS-Policyファイルの作成」を参照してください。信頼性のあるメッセージングのポリシー・アサーションに関するリファレンス情報は、『Oracle WebLogic Server WebLogic Webサービス・リファレンス』のWebサービスの信頼性のあるメッセージングのポリシー・アサーションに関するリファレンスの項を参照してください。

DefaultReliability1.1.xml (WS-Policyファイル)

DefaultRealiability1.1.xml WS-Policyファイルは、サービス品質に関するポリシー・アサーションを指定します。Webサービスの信頼性のあるメッセージングのアサーションは、WS Reliable Messaging Policy Assertion 1.1(http://docs.oasis-open.org/ws-rx/wsrmp/200702/wsrmp-1.1-spec-os-01.pdf)に基づいています。

<?xml version="1.0"?>

<wsp:Policy
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
>
<wsrmp:RMAssertion
xmlns:wsrmp="http://docs.oasis-open.org/ws-rx/wsrmp/200702"
>
<wsrmp:DeliveryAssurance>
<wsp:Policy>
<wsrmp:ExactlyOnce />
</wsp:Policy>
</wsrmp:DeliveryAssurance>
</wsrmp:RMAssertion>
</wsp:Policy>

Reliability1.1_SequenceTransportSecurity.xml (WS-Policyファイル)

Reliability1.1_SequenceTransportSecurity.xmlファイルは、トランスポート・レベルのセキュリティおよびサービス品質に関するポリシー・アサーションを指定します。Webサービスの信頼性のあるメッセージングのアサーションは、WS Reliable Messaging Policy Assertion 1.1(http://docs.oasis-open.org/ws-rx/wsrmp/200702/wsrmp-1.1-spec-os-01.pdf)に基づいています。

<wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
<wsrmp:RMAssertion
xmlns:wsrmp="http://docs.oasis-open.org/ws-rx/wsrmp/200702">
<wsrmp:SequenceTransportSecurity/>
<wsrmp:DeliveryAssurance>
<wsp:Policy>
<wsrmp:ExactlyOnce/>
</wsp:Policy>
</wsrmp:DeliveryAssurance>
</wsrmp:RMAssertion>
</wsp:Policy>

Reliability1.1_SequenceSTR.xml (WS-Policyファイル)

Reliability1.1_SequenceSTR.xmlファイルは、信頼性のあるシーケンスでメッセージを保護するために、CreateSequenceメッセージで参照されるwsse:SecurityTokenReferenceをランタイムが使用するように指定します。Webサービスの信頼性のあるメッセージングのアサーションは、WS Reliable Messaging Policy Assertion 1.1(http://docs.oasis-open.org/ws-rx/wsrmp/200702/wsrmp-1.1-spec-os-01.pdf)に基づいています。

<wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
<wsrmp:RMAssertion
xmlns:wsrmp="http://docs.oasis-open.org/ws-rx/wsrmp/200702">
<wsrmp:SequenceSTR/>
<wsrmp:DeliveryAssurance>
<wsp:Policy>
<wsrmp:ExactlyOnce/>
</wsp:Policy>
</wsrmp:DeliveryAssurance>
</wsrmp:RMAssertion>
</wsp:Policy>

Reliability1.0_1.1.xml (WS-Policy.xmlファイル)

Reliability1.0_1.1.xml WS-Policy.xmlファイルは、Webサービスの信頼性のあるメッセージング・ポリシーのアサーションのバージョン1.1と1.0を結合します。このサンプルは、適切なポリシーの選択に基づいて実行時に適用されるポリシー・アサーションを決定します。適切なポリシーの選択の詳細は、「複数のポリシー選択肢の使用」を参照してください。

注意:
1.0のWebサービスの信頼性のあるメッセージング・アサーションには、接頭辞としてwsrmp10が付加されます。

<wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
<wsp:ExactlyOne>
<wsp:All>
<wsrmp10:RMAssertion
xmlns:wsrmp10="http://schemas.xmlsoap.org/ws/2005/02/rm/policy">
<wsrmp10:InactivityTimeout Milliseconds="600000"/>
<wsrmp10:BaseRetransmissionInterval Milliseconds="3000"/>
<wsrmp10:ExponentialBackoff/>
<wsrmp10:AcknowledgementInterval Milliseconds="200"/>
</wsrmp10:RMAssertion>
</wsp:All>
<wsp:All>
<wsrmp:RMAssertion
xmlns:wsrmp="http://docs.oasis-open.org/ws-rx/wsrmp/200702">
<wsrmp:SequenceSTR/>
<wsrmp:DeliveryAssurance>
<wsp:Policy>
<wsrmp:ExactlyOnce/>
</wsp:Policy>
</wsrmp:DeliveryAssurance>
</wsrmp:RMAssertion>
</wsp:All>
</wsp:ExactlyOne>
</wsp:Policy>

DefaultReliability.xml (WS-Policyファイル) [非推奨]

このWS-Policyファイルは非推奨となっています。Webサービスの信頼性のあるメッセージングのアサーションは、WS Reliable Messaging Policy Assertion Version 1.0(http://schemas.xmlsoap.org/ws/2005/02/rm/policy/)に基づいています。現在のリリースでは、信頼性のあるメッセージングのポリシー・アサーションの多くが、JWSアノテーションまたは構成を通じて管理されます。

DefaultReliability.xml WS-Policyファイルは、信頼性のあるメッセージングのポリシーのアサーションに一般的な値(非アクティブ・タイムアウト10分、確認応答の間隔200ミリ秒、基本的な再送信間隔3秒など)を指定します。

<?xml version="1.0"?>

<wsp:Policy
xmlns:wsrm="http://schemas.xmlsoap.org/ws/2005/02/rm/policy"
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
xmlns:beapolicy="http://www.bea.com/wsrm/policy"
>

<wsrm:RMAssertion >

<wsrm:InactivityTimeout
Milliseconds="600000" />
<wsrm:BaseRetransmissionInterval
Milliseconds="3000" />
<wsrm:ExponentialBackoff />
<wsrm:AcknowledgementInterval
Milliseconds="200" />
<beapolicy:Expires Expires="P1D" optional="true"/>
</wsrm:RMAssertion>

</wsp:Policy>

LongRunningReliability.xml (WS-Policyファイル) [非推奨]

このWS-Policyファイルは非推奨となっています。Webサービスの信頼性のあるメッセージングのアサーションは、WS Reliable Messaging Policy Assertion Version 1.0(http://schemas.xmlsoap.org/ws/2005/02/rm/policy/)に基づいています。現在のリリースでは、信頼性のあるメッセージングのポリシー・アサーションの多くが、JWSアノテーションまたは構成を通じて管理されます。

LongRunningRelibility.xml WS-Policyファイルは、DefaultReliability.xml WS-Policyファイルと同じような値を指定しますが、指定するアクティビティのタイムアウト間隔がより長い(24時間)点が異なります。「LongRunningReliability.xml (WS-Policyファイル) [非推奨]」を参照してください。

<?xml version="1.0"?>

<wsp:Policy
xmlns:wsrm="http://schemas.xmlsoap.org/ws/2005/02/rm/policy"
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
xmlns:beapolicy="http://www.bea.com/wsrm/policy"
>

<wsrm:RMAssertion >

<wsrm:InactivityTimeout
Milliseconds="86400000" />
<wsrm:BaseRetransmissionInterval
Milliseconds="3000" />
<wsrm:ExponentialBackoff />
<wsrm:AcknowledgementInterval
Milliseconds="200" />
<beapolicy:Expires Expires="P1M" optional="true"/>
</wsrm:RMAssertion>

</wsp:Policy>

オラクルの法律上の注意点について

コピーライトについて

Copyright © 1994-2016, Oracle and/or its affiliates.All rights reserved.

ライセンス制約の保証と結果的に生じる損害の免責

このソフトウェアおよび関連ドキュメントの使用と開示は、ライセンス契約の制約条件に従うものとし、知的財産に関する法律により保護されています。ライセンス契約で明示的に許諾されている場合もしくは法律によって認められている場合を除き、形式、手段に関係なく、いかなる部分も使用、複写、複製、翻訳、放送、修正、ライセンス供与、送信、配布、発表、実行、公開または表示することはできません。このソフトウェアのリバース・エンジニアリング、逆アセンブル、逆コンパイルは互換性のために法律によって規定されている場合を除き、禁止されています。

保証免責

ここに記載された情報は予告なしに変更される場合があります。また、誤りが無いことの保証はいたしかねます。誤りを見つけた場合は、オラクルまでご連絡ください。

制限付権利について

このソフトウェアまたは関連ドキュメントを、米国政府機関もしくは米国政府機関に代わってこのソフトウェアまたは関連ドキュメントをライセンスされた者に提供する場合は、次の通知が適用されます。

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations.As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs.No other rights are granted to the U.S. Government.

危険な用途への使用について

このソフトウェアまたはハードウェアは様々な情報管理アプリケーションでの一般的な使用のために開発されたものです。このソフトウェアまたはハードウェアは、危険が伴うアプリケーション(人的傷害を発生させる可能性があるアプリケーションを含む)への用途を目的として開発されていません。このソフトウェアまたはハードウェアを危険が伴うアプリケーションで使用する際、安全に使用するために、適切な安全装置、バックアップ、冗長性(redundancy)、その他の対策を講じることは使用者の責任となります。このソフトウェアまたはハードウェアを危険が伴うアプリケーションで使用したことに起因して損害が発生しても、Oracle Corporationおよびその関連会社は一切の責任を負いかねます。

商標と登録商標について

OracleおよびJavaはオラクルおよびその関連会社の登録商標です。その他の社名、商品名等は各社の商標または登録商標である場合があります。

Intel、Intel Xeonは、Intel Corporationの商標または登録商標です。すべてのSPARCの商標はライセンスをもとに使用し、SPARC International, Inc.の商標または登録商標です。AMD、Opteron、AMDロゴ、AMD Opteronロゴは、Advanced Micro Devices, Inc.の商標または登録商標です。UNIXは、The Open Groupの登録商標です。

第三者のコンテンツ、製品、サービスに対する免責事項

このソフトウェアまたはハードウェア、そしてドキュメントは、第三者のコンテンツ、製品、サービスへのアクセス、あるいはそれらに関する情報を提供することがあります。適用されるお客様とOracle Corporationとの間の契約に別段の定めがある場合を除いて、Oracle Corporationおよびその関連会社は、第三者のコンテンツ、製品、サービスに関して一切の責任を負わず、いかなる保証もいたしません。適用されるお客様とOracle Corporationとの間の契約に定めがある場合を除いて、Oracle Corporationおよびその関連会社は、第三者のコンテンツ、製品、サービスへのアクセスまたは使用によって損失、費用、あるいは損害が発生しても一切の責任を負いかねます。

アルファ版およびベータ版ドラフト・ドキュメントについて

このドキュメントが試作版の場合:

このドキュメントは試作版であり、デモおよび暫定使用のみを目的としたものです。このソフトウェアを使用するハードウェアに限定するものではありません。Oracle Corporationおよびその関連会社は、このドキュメントに関して一切の責任を負わず、いかなる保証もいたしません。また、このドキュメントを使用したことによって損失、費用、あるいは損害が発生しても、一切の責任を負いかねます。

非公開のアルファ版およびベータ版ドラフト・ドキュメントについて

このドキュメントが非公開の試作版の場合:

このドキュメントに含まれる情報は、情報の共有のみを目的としたものであって、顧客諮問委員会(Customer Advisory Board)のメンバーとしてのお客様の立場でのみ、またはお客様のベータ・トライアル契約のみに従って検討されるべきものとします。マテリアル、コード、または機能の提供をお約束するものではなく、購入決定を行う際の判断材料とすべきではありません。このドキュメントに記載されている特徴または機能の開発、リリースおよび時期については、オラクルの裁量により決定されます。

このドキュメントには、ソフトウェアまたは印刷物などの形式を問わず、オラクルが独占的な権利を有する財産的情報が含まれています。この機密資料へのアクセスと使用は、お客様とオラクルとの間で締結され、お客様が遵守に同意した、Oracle Master Agreement、Oracle License and Oracle Services Agreement (オラクル・ライセンスおよびサービスに関する契約書)、Oracle PartnerNetwork Agreement、Oracle Distribution Agreementまたはその他のライセンス契約の条件に従うものとします。このドキュメントとその内容の開示、コピー、複製および配布には、オラクルによる事前の承諾を必要とします。このドキュメントはライセンス契約の一部となるものではなく、オラクルおよびその子会社や関連会社との契約を構成するものではありません。

ドキュメントのアクセシビリティについて

オラクルのアクセシビリティについての詳細情報は、Oracle Accessibility ProgramのWebサイトhttp://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc を参照してください。

Oracle Supportへのアクセス

サポートをご契約のお客様には、My Oracle Supportを通して電子支援サービスを提供しています。詳細情報はhttp://www.oracle.com/pls/topic/lookup?ctx=acc&id=infoか、聴覚に障害のあるお客様はhttp://www.oracle.com/pls/topic/lookup?ctx=acc&id=trsを参照してください。