|
WebLogic Web サービス プログラマーズ ガイド
|
WebLogic Web サービス デプロイメント記述子の要素
web-services.xml デプロイメント記述子ファイルには、1 つまたは複数の WebLogic Web サービスを記述する情報が格納されます。 この情報には、Web サービスの操作を実装するバックエンド コンポーネント、パラメータおよび戻り値として使用される非組み込みデータ型、SOAP メッセージをインターセプトする SOAP メッセージ ハンドラなどの詳細情報が含まれます。他のすべてのデプロイメント記述子の場合と同様に、web-services.xml も XML ファイルです。
この章では、異なる形式を使用して web-services.xml ファイルについて説明します。
階層図
次の図は、web-services.xml 要素の階層を示しています。
要素について
アルファベット順に構成された以降の節では、web-services.xml ファイルの各要素を説明します。
さまざまなタイプの WebLogic Web サービス 用の Web サービス デプロイメント記述子ファイルのサンプルについては、Sample web-services.xml Filesを参照してください。
components
Web サービスを実装するバックエンド コンポーネントを定義します。
WebLogic Web サービスは、以下の 1 つまたは複数のコンポーネントを使用して実装できます。
- ステートレス セッション EJB
- JMS 送り先
- Java クラス
この要素には属性はありません。
ejb-link
EJB JAR ファイル内のどの EJB を使用してステートレス セッション EJB バックエンド コンポーネントを実装するかを指定します。
|
属性
|
説明
|
データ型
|
必須/任意
|
|
path
|
次の形式の EJB の名前。
jar-name#ejb-name
jar-name は、ステートレス セッション EJB を含んでいる JAR ファイル (Web サービス EAR ファイル内に含まれている) の名前を指す。名前には、最上位の EAR ファイルへの相対パス名が含まれている必要がある。
ejb-name は、EJB JAR ファイル内の ejb-jar.xml デプロイメント記述子内の <ejb-name> 要素に対応するステートレス セッション EJB の名前を指す。
例 : myapp.jar#StockQuoteBean
|
String
|
必須
|
fault
この操作の呼び出しでエラーが発生した場合に送出される SOAP 障害を指定します。
この要素は必須ではありません。
|
属性
|
説明
|
データ型
|
必須/任意
|
|
name
|
パラメータの名前。
|
String
|
必須
|
|
class-name
|
SOAP ハンドラを実装する完全修飾 Java クラス。
|
String
|
必須
|
handler
ハンドラ チェーン内の SOAP メッセージハンドラを指定します。 1 つのハンドラ チェーンは 1 つまたは複数のハンドラで構成できます。
ハンドラを実装する Java クラスに初期化パラメータが必要な場合は、<handler> 要素の <init-params> 子要素を任意に使用してパラメータを指定します。
|
属性
|
説明
|
データ型
|
必須/任意
|
|
class-name
|
SOAP メッセージ ハンドラを実装する完全修飾 Java クラス。
|
String
|
必須
|
handler-chain
特定のハンドラ チェーンを構成する SOAP メッセージ ハンドラをリストします。1 つの WebLogic Web サービスでは、任意数のハンドラ チェーンを定義できます (0 でもかまわない)。
ハンドラ(<handler> 子要素により定義される)がリストされる順番は重要です。 デフォルトでは、ハンドラの handleRequest() メソッドは、<handler-chain> 要素の子要素としてリストされている順に実行されます。ハンドラの handleResponse() メソッドは、リストされているものとは逆の順序で実行されます。
|
属性
|
説明
|
データ型
|
必須/任意
|
|
name
|
このハンドラ チェーンの名前。
|
String
|
必須
|
handler-chains
この web-services.xml ファイルで記述された Web サービスに使用されている SOAP メッセージ ハンドラ チェーンを記述する <handler-chain> 要素のリストを含んでいます。1 つの WebLogic Web サービスでは、任意数のハンドラ チェーンを定義できます (0 でもかまわない)。
この要素は、属性を持ちません。
init-param
ハンドラの初期化パラメータのうちの 1 つを表す名前と値の組み合わせを指定します。
|
属性
|
説明
|
データ型
|
必須/任意
|
|
name
|
パラメータの名前。
|
String
|
必須
|
|
value
|
パラメータの値。
|
String
|
必須
|
init-params
ハンドラを実装する Java クラスに受け渡される初期化パラメータのリストを含んでいます。
この要素は、属性を持ちません。
java-class
Web サービスの 1 つまたは複数の操作を実装する Java クラス コンポーネントを記述します。
|
属性
|
説明
|
データ型
|
必須/任意
|
|
name
|
このコンポーネントの名前。
|
String
|
必須
|
|
class-name
|
このコンポーネントを実装する Java クラスの完全修飾名。
|
String
|
必須
|
jms-receive-queue
Web サービス内の操作のうちの 1 つが JMS キューにマップされることを指定します。この要素は、JMS キューからデータを受信する Web サービス操作の指定に使用されます。
通常は、メッセージ プロデューサがメッセージを特定の JMS キューに入れ、この Web サービス操作を呼び出すクライアントがポーリングを行ってメッセージを受信します。
|
属性
|
説明
|
データ型
|
必須/任意
|
|
name
|
このコンポーネントの名前。
|
String
|
必須
|
|
connection-factory
|
WebLogic Server が JMS 接続オブジェクトの作成に使用する JMS 接続ファクトリの JNDI 名。
|
String
|
必須
|
|
provider-url
|
WebLogic Server 以外の JMS 実装への接続に使用される URL。
|
String
|
任意
|
|
initial-context-factory
|
WebLogic Server 以外の JMS 実装のためのコンテキスト ファクトリ。
|
String
|
任意
|
jms-receive-topic
Web サービス内の操作のうちの 1 つが JMS トピックにマップされることを指定します。この要素は、JMS トピックからデータを受信する Web サービス操作の指定に使用されます。
通常は、メッセージ プロデューサがメッセージを特定の JMS トピックに入れ、この Web サービス コンポーネントを呼び出すクライアントがポーリングを行ってメッセージを受信します。
|
属性
|
説明
|
データ型
|
必須/任意
|
|
name
|
このコンポーネントの名前。
|
String
|
必須
|
|
connection-factory
|
WebLogic Server が JMS 接続オブジェクトの作成に使用する JMS 接続ファクトリの JNDI 名。
|
String
|
必須
|
|
provider-url
|
WebLogic Server 以外の JMS 実装への接続に使用される URL。
|
String
|
任意
|
|
initial-context-factory
|
WebLogic Server 以外の JMS 実装のためのコンテキスト ファクトリ。
|
String
|
任意
|
jms-send-destination
Web サービス内の操作のうちの 1 つが JMS 送り先 (キューまたはトピック) にマップされることを指定します。この要素は、JMS 送り先にデータを送信する Web サービス操作の指定に使用されます。
通常は、メッセージが JMS 送り先に送信された後に、メッセージ コンシューマ (メッセージ駆動型 Bean など) がそのメッセージを使用します。
|
属性
|
説明
|
データ型
|
必須/任意
|
|
name
|
このコンポーネントの名前。
|
String
|
必須
|
|
connection-factory
|
WebLogic Server が JMS 接続オブジェクトの作成に使用する JMS 接続ファクトリの JNDI 名。
|
String
|
必須
|
|
provider-url
|
WebLogic Server 以外の JMS 実装への接続に使用される URL。
|
String
|
任意
|
|
initial-context-factory
|
WebLogic Server 以外の JMS 実装のためのコンテキスト ファクトリ。
|
String
|
任意
|
jndi-name
JNDI ツリーにバインドされているオブジェクトへの参照を指定します。参照の対象は、ステートレス セッション EJB または JMS 送り先になります。
|
属性
|
説明
|
データ型
|
必須/任意
|
|
path
|
JNDI コンテキスト ルートからオブジェクトへのパス名。
|
String
|
必須
|
operation
Web サービスの 1 つの操作をコンフィグレーションします。この要素の属性の値と組み合わせによって、次の種類の操作をコンフィグレーションできます。
- ステートレス セッション EJB または Java クラスのメソッドの呼び出し。この種類の操作を指定するには、component 属性をステートレス セッション EJB または Java クラス コンポーネントの名前に設定し、method 属性をメソッドの名前に設定します。
- JMS バックエンド コンポーネントの呼び出し。この種類の操作を指定するには、component 属性を JMS コンポーネントの名前に設定します。
- ハンドラ チェーン上の SOAP メッセージ ハンドラの連続呼び出しとバックエンド コンポーネントの呼び出し。この種類の操作を指定するには、component 属性をコンポーネントの名前に設定し、handler-chain 属性を対象のハンドラ チェーンの名前に設定します。
- ハンドラ チェーン上の SOAP メッセージ ハンドラの連続呼び出し (ただし、バックエンド コンポーネントは呼び出さない)。この種類の操作を指定する場合は、component 属性と method 属性を設定せずに、handler-chain 属性を対象のハンドラ チェーンの名前に設定します。
操作のパラメータと戻り値を明示的に指定するには、<params> 子要素を使用します。
|
属性
|
説明
|
データ型
|
必須/任意
|
|
name
|
生成された WSDL で使用される操作の名前。
この属性が未指定の場合、操作の名前はメソッド名または SOAP メッセージ ハンドラ チェーン名にデフォルトで設定される。
|
String
|
任意
|
|
component
|
この操作を実装するコンポーネントの名前。
この属性の値は、該当する <component> 要素の name 属性に対応する。
|
String
|
任意
|
|
method
|
操作を実装する EJB または Java クラスのメソッドの名前 (component 属性で操作がステートレス セッション EJB または Java クラスで実装されることを指定した場合)。
アスタリスク (*) を使用すると、全メソッドを指定できる。
EJB または Java クラスがメソッドをオーバーロードしない場合は、次のように、メソッド名しか指定する必要がない。
method="sell"
ただし、EJB または Java クラスがメソッドをオーバーロードする場合は、次のように、全シグネチャを指定する。
method="sell(int)"
|
String
|
任意
|
|
handler-chain
|
この操作を実装する SOAP メッセージ ハンドラ チェーンの名前。
この属性の値は、該当する <handler-chain> 要素の name 属性に対応する。
|
String
|
任意
|
|
invocation-style
|
操作が SOAP 要求の受信と SOAP 応答の送信の両方を行うか、SOAP 応答の返信は行わずに SOAP 要求の受信のみを行うかを指定する。
この属性には、request-response (デフォルト値) または one-way のいずれかの値のみを指定できる。
注意: この操作を実装するバックエンド コンポーネントが、ステートレス セッション EJB または Java クラスのメソッドである場合にこの属性を one-way に設定すると、メソッドにより void が返される。
|
String
|
任意
|
|
portTypeName
|
この操作が属する WSDL ファイルのポートの種類。ポートの種類から成るカンマ区切りリストを指定することにより、この操作を複数のポートの種類に含めることができる。この Web サービスの WSDL の生成時に、独立した <portType> 要素が指定した個々のポートの種類用に作成される。
デフォルト値は、<web-service> 要素の portType 属性の値。
|
String
|
任意
|
operations
<operations> 要素は、この Web サービスの明示的に宣言された操作をグループ化します。
この要素は、属性を持ちません。
param
<param> 要素は操作の単一パラメータを指定します。
パラメータは、オペレーションを実装するメソッドを定義した順序と同じ順序で指定する必要があります。<param> 要素の数は、メソッドのパラメータ数と一致する必要があります。
|
属性
|
説明
|
データ型
|
必須/任意
|
|
name
|
生成された WSDL で使用される in パラメータの名前。
この属性が未指定の場合、パラメータ名はパラメータのデータ型に基づいて、intvalue1、intvalue2、traderesult などになる。
|
String
|
任意
|
|
location
|
in パラメータの値を含む要求 SOAP メッセージの部分 (ヘッダー、本文、または添付ファイル)。
この属性の有効な値は、Body、Header、または attachment。デフォルト値は Body。
Body を指定すると、RPC 操作の呼び出しに関する通常の SOAP 規則に基づき、パラメータの値が SOAP 本文から抽出される。 Header を指定すると、type 属性の値を名前に持つ SOAP ヘッダー要素から値が抽出される。
attachment を指定すると、SOAP エンベロープではなく SOAP 添付ファイルからパラメータの値が抽出される。JAX-RPC 仕様で指定されているように、SOAP 添付ファイルから抽出できるのは、以下の Java データ型のみ。
|
String
|
任意
|
|
style
|
in パラメータ (標準入力パラメータ、戻り値として使用される out パラメータ、または値の入出力の両方に使用される inout パラメータ) のスタイル。
この属性の有効な値は、in、out、または inout。
パラメータを out または inout に指定すると、バックエンド コンポーネントのメソッド内のパラメータの Java クラスが javax.xml.rpc.holders.Holder インタフェースを実装する。
|
String
|
必須
|
|
type
|
パラメータの XML スキーマデータ型。
|
NMTOKEN
|
必須
|
|
class-name
|
パラメータのデータ型の Java 表現の Java クラス名。
この属性が未指定の場合、WebLogic Server は、パラメータの Java クラスの操作を実装するバックエンド コンポーネントを参照する。
この属性の指定が必要となるのは、パラメータの XML 表現と Java 表現間のマッピングをデフォルトとは異なるものにする場合のみである。たとえば、xsd:int はデフォルトでは Java プリミティブ int 型にマップされるため、これを java.lang.Integer にマップするにはこの属性を使用する。
|
NMTOKEN
|
通常は必須。属性の説明を参照。
|
params
<params> 要素は、操作の明示的に宣言されたパラメータとオペレーションの戻り値をグループ化します。
オペレーションのパラメータや戻り値は明示的にリストする必要はありません。<operation> 要素に <params> 子要素がない場合、WebLogic Server はオペレーションを実装するバックエンド コンポーネントを参照してパラメータと戻り値を決定します。 Web サービスの WSDL ファイルの生成時に、WebLogic Server は対応するメソッドのパラメータと戻り値の名前を使用します。
以下の場合には、オペレーションのパラメータと戻り値を明示的にリストしてください。
- 生成された WSDL のパラメータおよび戻り値の名前は、そのオペレーションを実装するメソッドの名前とは異なる名前とする必要がある場合。
- パラメータを SOAP の要求ヘッダーまたは応答ヘッダーにある名前にマップする必要がある場合。
- out または inout パラメータを使用する必要がある場合。
操作のパラメータを指定するには、<param> 子要素を使用します。
操作の戻り値を指定するには、<return-param> 子要素を使用します。
<params> 要素は、属性を持ちません。
return-param
<return-param> 要素は、Web サービス操作の戻り値を指定します。
1つの操作に指定できる <return-param> 要素は 1 つのみです。
|
属性
|
説明
|
データ型
|
必須/任意
|
|
name
|
生成された WSDL ファイルで使用される戻りパラメータの名前。
この属性が未指定の場合、戻りパラメータの名前は result になる。
|
String
|
任意
|
|
location
|
戻りパラメータの値を含む応答 SOAP メッセージの部分 (ヘッダーまたは本文)。
この属性の有効な値は、Body または Header。デフォルト値は Body。
Body を指定すると、戻りパラメータの値が SOAP 本文に追加される。Header を指定すると、type 属性の値を名前に持つ SOAP ヘッダー要素として値が追加される。
|
String
|
任意
|
|
type
|
戻りパラメータの XML スキーマ データ型。
|
NMTOKEN
|
必須
|
|
class-name
|
戻りパラメータのデータ型の Java 表現の Java クラス名。
この属性が未指定の場合、WebLogic Server は操作を実装するバックエンド コンポーネントを参照して戻りパラメータの Java クラスを決定する。
この属性は、次の場合に指定が必要になる。
|
NMTOKEN
|
通常は必須。属性の説明を参照。
|
stateless-ejb
Web サービスの 1 つまたは複数の操作を実装するステートレス セッション EJB コンポーネントを指定します。
|
属性
|
説明
|
データ型
|
必須/任意
|
|
name
|
ステートレス EJB コンポーネントの名前。
注意: 名前は web-services.xml ファイル内のもので、ejb-jar.xml ファイル内の EJB の名前は参照しません。
|
String
|
必須
|
type-mapping
<type-mapping> 要素には、<types> 要素に定義されている XML データ型とその Java 表現間のマッピングのリストが含まれています。
<types> 要素内の各データ型に対し、そのデータ型を実装する Java クラスや、データをシリアライズ/デシリアライズする方法などをリストした <type-mapping-entry> 要素があります。
この要素には属性はありません。
type-mapping-entry
<types> 要素内の単一 XML データ型とその Java 表現間のマッピングを指定します。
|
属性
|
説明
|
データ型
|
必須/任意
|
|
class-name
|
対応する XML データ型にマップされる Java クラスの完全修飾名。
|
String
|
必須
|
|
element
|
Java データ型にマップされる XML データ型の名前。データ型の XML スキーマ定義で <element> 要素を使用する場合にのみ指定する。
|
NMTOKEN
|
element または type のいずれか 1 つ (両方ではない) が必須。
|
|
type
|
Java データ型にマップされる XML データ型の名前。データ型の XML スキーマ定義で <type> 要素を使用する場合にのみ指定する。
|
NMTOKEN
|
element または type のいずれか 1 つ (両方ではない) が必須。
|
|
serializer
|
データを Java から XML に変換する Java クラスの完全修飾名。
|
String
|
データ型が、組み込みデータ型の使用法にリストされている WebLogic Web サービス実行時でサポートされている組み込みデータ日付ではない場合にのみ必須。
|
|
deserializer
|
データを XML から Java に変換する Java クラスの完全修飾名。
|
String
|
データ型が、組み込みデータ型の使用法にリストされている WebLogic Web サービス実行時でサポートされている組み込みデータ日付ではない場合にのみ必須。
|
types
XML スキーマ表記法に基づいて、Web サービス オペレーションのパラメータまたは戻り値の型として使用される非組み込みデータ型を記述します。
XML スキーマを使用して非組み込みデータ型の XML 表現を記述する詳細については、http://www.w3.org/TR/xmlschema-0/ を参照してください。
次の例では、stockSymbol (String データ型) と numberTraded (Integer 型) の 2 つの要素を含む TradeResult というデータ型の XML スキーマ宣言を示します。
<types>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:stns="java:examples.webservices"
attributeFormDefault="qualified"
elementFormDefault="qualified"
targetNamespace="java:examples.webservices">
<xsd:complexType name="TradeResult">
<xsd:sequence>
<xsd:element maxOccurs="1"
name="stockSymbol"
type="xsd:string" minOccurs="1">
</xsd:element>
<xsd:element maxOccurs="1"
name="numberTraded"
type="xsd:int"
minOccurs="1">
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:schema>
</types>
web-service
単一 Web サービスを定義します。
Web サービスは次のコンポーネントで定義されます。
- 操作を実装するバックエンド コンポーネント(ステートレス セッション EJB、Java クラス、JMS コンシューマ、JMS プロデューサなど)。
- Web サービス オペレーションのパラメータまたは戻り値として使用される非組み込みデータ型のデータ型宣言の任意セット。
- 非組み込みデータ型のシリアライゼーション クラスと Java クラスを指定する XML/Java データ型マッピングの任意セット。
- Web サービスでサポートされる操作の宣言。
|
属性
|
説明
|
データ型
|
必須/任意
|
|
name
|
Web サービスの名前。
|
String
|
必須
|
|
targetNamespace
|
この Web サービスのネームスペース。
|
String
|
必須
|
|
uri
|
Web サービス の URI。Web サービスを呼び出す URL で後に使用される。
注意: /TraderService のように、先頭に「/」を必ず指定すること。
|
String
|
必須
|
|
protocol
|
サービスの呼び出しに使用されるプロトコル。
有効な値は http または https。デフォルトは http。
|
String
|
任意
|
|
exposeHomePage
|
Web サービスのホーム ページを外部にエクスポーズするかどうかを指定する。
この属性の有効な値は、True および False。 デフォルト値は True。 つまり、ホーム ページはデフォルトで外部からアクセス可能となる。
|
Boolean
|
任意
|
|
exposeWSDL
|
Web サービスの自動生成された WSDL を外部にエクスポーズするかどうかを指定する。
この属性の有効な値は、True および False。 デフォルト値は True。 つまり、WSDL はデフォルトで外部からアクセス可能となる。
|
Boolean
|
任意
|
|
style
|
Web サービスのオペレーションが RPC 指向かドキュメント指向かを指定する。
RPC 指向の WebLogic Web サービス オペレーションでは、SOAP エンコーディングを使用する。ドキュメント指向の WebLogic Web サービス オペレーションでは、リテラル エンコーディングを使用する。
有効な値は rpc および document。デフォルト値は rpc。
警告: この属性で document を指定した場合、Web サービスのオペレーションを実装するメソッドはすべて、パラメータが 1 つでなければならない。
注意: style 属性は Web サービス全体に適用されるので、1 つの <web-service> 要素で指定されたすべてのオペレーションが RPC 指向またはドキュメント指向のいずれかでなければならない。同じ Web サービスで 2 つのスタイルを混在させることはできない。
|
String
|
任意
|
|
portName
|
この Web サービスの動的に生成された WSDL の <service> 要素の <port> 子要素の名前。
デフォルト値は、この要素の name 属性に Port を付加した値。たとえば、この Web サービスの名前が TraderService の場合、ポート名は TraderServicePort。
|
String
|
任意
|
|
portTypeName
|
この Web サービスの動的に生成された WSDL で、デフォルトの <portType> 要素の名前。
デフォルト値は、この要素の name 属性に Port を付加した値。たとえば、この Web サービスの名前が TraderService の場合、portType 名は TraderServicePort。
|
String
|
任意
|
|
ignoreAuthHeader
|
SOAP リクエストの Authorization HTTP ヘッダが Web サービスで無視されることを指定する。
注意: この属性は、慎重に使用する必要がある。 この属性の値を True に設定すると、Web サービスを構成する EJB、Web アプリケーション、またはエンタープライズ アプリケーションでアクセス制御のセキュリティ制約が定義されている場合でも、WebLogic Server は Web サービスを呼び出そうとしているクライアント アプリケーションの認証を絶対に行わない。 つまり、認証資格を持たないクライアント アプリケーションでも、セキュリティ制約が定義されている Web サービスを呼び出せることになる。
有効な値は True および False。 デフォルト値は False。
|
Boolean
|
任意
|
web-services
web-services.xml デプロイメント記述子のルート要素です。
この要素は、属性を持ちません。
