15.2.2 外部バインディングファイルによるカスタマイズ
外部バインディングファイルによるカスタマイズは，WSDLとは別にバインディング宣言をまとめて記述したファイルを用意し，そのファイルをWSDL文書と同時に読み込み，カスタマイズする方法です。外部バインディングファイルは，複数読み込むことができます。
外部バインディングファイルを使用して，パッケージ名をカスタマイズする例を次の図に示します。
|
|
![[図データ]](GRAPHICS/ZU111500.GIF)
外部バインディングファイルでカスタマイズする場合の留意点について説明します。
- 〈この項の構成〉
(1) jaxws:bindings要素の指定
外部バインディングファイルの場合も埋め込みによるバインディング宣言と同様に，jaxws:bindings要素をコンテナとして使用します。
ただし，埋め込みによるバインディング宣言とは異なり，jaxws:bindings要素をjaxws:bindings要素の子要素として記述できます。
jaxws:bindings要素の属性と，属性の指定有無による動作を次の表に示します。
|
項番 |
記述位置 |
要素 |
属性の指定 |
動作 |
|---|---|---|---|---|
|
1 |
ルートのjaxws:bindings※1 |
wsdlLocation |
あり |
属性は必ず指定してください。指定したロケーションのWSDLをカスタマイズ対象のWSDLファイルとします。指定方法については，「15.2.2(1)(a) wsdlLocation属性の記述形式」を参照してください。 |
|
2 |
なし |
属性を指定していない場合，外部バインディングファイルは無視されます（カスタマイズされないで正常終了します）。 |
||
|
3 |
node |
あり |
XPath 1.0形式で属性を指定できます。指定した要素をカスタマイズ対象とします。指定方法については，「15.2.2(1)(b) node属性の記述形式」を参照してください。 |
|
|
4 |
なし |
カスタマイズ対象の要素をWSDLのルート（wsdl:definitions要素）とします。 |
||
|
5 |
version |
あり |
"2.0"を指定できます。指定方法については，「15.2.2(1)(c) version属性の記述形式」を参照してください。 |
|
|
6 |
なし |
"2.0"が指定されていると見なされます。 |
||
|
7 |
非ルートのjaxws:bindings※2 |
wsdlLocation |
あり |
属性は指定できません。指定しても無視されます。 |
|
8 |
なし |
正常終了します。 |
||
|
9 |
node |
あり |
属性は必ず指定してください。指定した要素をカスタマイズ対象とします。指定方法については，「15.2.2(1)(b) node属性の記述形式」を参照してください。 |
|
|
10 |
なし |
カスタマイズ対象がないため，カスタマイズされないで正常終了します。 |
||
|
11 |
version |
あり |
属性は指定できません。指定しても無視されます。 |
|
|
12 |
なし |
正常終了します。 |
- 注※1
-
「ルートのjaxws:bindings」とは，外部バインディングファイルの最上位に記述されたjaxws:bindings要素を表します。
- 注※2
-
「非ルートのjaxws:bindings」とは，ルートのjaxws:bindingsの子要素以下に記述されたjaxws:bindings要素を表します。
(a) wsdlLocation属性の記述形式
jaxws:bindings要素のwsdlLocation属性に指定する値は，URLで指定します。URLによって指定するファイルは，リモートファイルでもローカルファイルでも，どちらでもかまいません。ローカルファイルの場合は，相対パスで指定することもできます。
誤った形式で記述した場合，またはファイルがない場合，標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51043-E）。
URLは，RFC 2396仕様の規則に従った文字列を使用してください。RFC 2396仕様の規則に従っていない文字列を使用する場合は，RFC 2396仕様の規則に従ってUTF-8でパーセントエンコーディングする必要があります。ただし，"&"はパーセントエンコーディングをしても使用できません。RFC 2396 仕様の規則に従わないで，エンコードもしていない文字や文字列を指定した場合の動作は保証されません。また，wsdlLocation属性に，WSDLファイル以外のファイルを指定した場合の動作は保証されません。
wsdlLocation属性の正しい記述例を示します。
<jaxws:bindings xmlns:jaxws=http://java.sun.com/xml/ns/jaxws wsdlLocation="file:///D:/tmp/example.wsdl" version="2.0"> ... </jaxws:bindings>
(b) node属性の記述形式
jaxws:bindings要素のnode属性に指定する値は，XPath 1.0形式で指定します。
誤った形式で記述した場合，標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51038-E）。
node属性の記述例を次に示します。この例では，wsdl:definitions/wsdl:portType要素のname属性が，AddNumbersImplの要素に対するバインディング宣言であることを示しています。
<jaxws:bindings node="wsdl:definitions/wsdl:portType[@name='AddNumbersImpl']"> ... </jaxws:bindings>
非ルートのjaxws:bindings要素のnode属性では，ルートのjaxws:bindings要素のnode属性で指定しているカスタマイズ対象要素からの相対パス（XPath 1.0形式）を指定できます。この場合の記述例を示します。
<jaxws:bindings node="wsdl:definitions/wsdl:portType[@name='UserInfoPortType']"
...
<jaxws:bindings node="../wsdl:service[@name='UserInfoService']">
...
</jaxws:bindings>
</jaxws:bindings>(2) 使用できるバインディング宣言
外部バインディングファイルを使用する場合に，Application ServerのJAX-WS機能で使用できるバインディング宣言の一覧を次の表に示します。各バインディング宣言については，JAX-WS 2.2仕様を参照してください。
|
要素名 |
属性名 |
説明 |
||
|---|---|---|---|---|
|
jaxws:bindings要素 |
wsdlLocation |
wsdlLocation属性には，カスタマイズ対象のWSDLファイルのファイルパス（URL）を記述します。 |
||
|
node |
node属性には，WSDL内のカスタマイズ対象の要素を記述します。 |
|||
|
version |
version属性には，WSDLのカスタマイズのバージョンを記述します。 |
|||
|
jaxws:bindings要素の子要素 |
− |
jaxws:bindings要素の子要素です。 |
||
|
┣ ┃ ┃ ┃ ┃ ┃ |
jaxws:package ┃ ┃ |
name |
name属性には，wsdl:definitions要素のtargetNamespace属性に対応するJavaパッケージ名を記述します。 |
|
|
┗ |
jaxws:javadoc |
− |
Javaパッケージに付加するJavadoc文字列です。 |
|
|
┣ ┃ |
jaxws:enableWrapperStyle |
− |
各要素に対するwrapperスタイルの有効／無効を表します。 |
|
|
┣ ┃ |
jaxws:enableAsyncMapping |
− |
各要素に対する非同期マッピングの有効／無効を表します。 |
|
|
┣ ┃ ┃ ┃ |
jaxws:class ┃ |
name |
name属性には，各要素に対応するクラス名を記述します。 |
|
|
┗ |
jaxws:javadoc |
− |
クラスに付加するJavadoc文字列です。 |
|
|
┣ ┃ ┃ ┃ |
jaxws:method ┃ |
name |
name属性には，各要素に対応するJavaメソッド名を記述します。 |
|
|
┗ |
jaxws:javadoc |
− |
メソッドに付加するJavadoc文字列です。 |
|
|
┣ ┃ ┃ ┃ ┃ ┃ ┃ ┃ ┃ ┃ ┃ |
jaxws:parameter |
part |
part属性には，wsdl:message要素のwsdl:part子要素を識別するXPath表現を記述します。 |
|
|
childElementName |
childElementName属性には，wsdl:part要素によって参照するグローバル型定義，またはグローバル要素宣言の子要素名を記述します。 |
|||
|
name |
name属性には，part属性およびchildElementName属性によって識別される要素のパラメタ名を記述します。 |
|||
|
┗ |
jaxws:provider |
− |
"true"を指定した場合，SEIは生成されません。生成されたサービスインタフェースでポートのgetterメソッドが省略されます。 jaxws:provider要素については，「15.2.7 jaxws:provider要素を記述した場合の動作」を参照してください。 |
|
- （凡例）
-
−：バインディング宣言に使用できる属性がないことを示します。
この表に示すように，WSDLでjaxws:bindings要素およびその子要素を記述できる位置は，JAX-WS 2.2仕様で規定されています。規定されていない位置にそれらの要素を記述した場合は，標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51029-E）。
各jaxws:bindings要素の子要素として記述できない要素を記述した場合は，標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51040-E）。
また，jaxws:bindings要素の属性およびその子要素に記述できない属性を記述した場合は，標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51029-E）。
なお，JAXB仕様のバインディング宣言は記述できません。記述した場合の動作は保証されません。
(3) 要素および属性の重複
jaxws:bindings要素およびその子要素内で属性が重複して記述されている場合，標準エラー出力とログにXML Processorのエラーメッセージが出力され，処理が終了されます。
外部バインディングファイルを使用して，同じカスタマイズ対象へのカスタマイズを重複して指定することはできません。指定した場合の動作は保証されません。
(4) wsdl:import要素で読み込むWSDLに対するカスタマイズ
wsdl:import要素でインポートするWSDLに対して外部バインディングファイルでカスタマイズする場合，jaxws:bindings要素のwsdlLocation属性でwsdl:import要素でインポートするWSDLを指定してください。
wsdl:import要素でインポートするWSDLをカスタマイズするときに，誤ってwsdl:import元のWSDLを指定すると，jaxws:bindings要素のnode属性で示したカスタマイズ対象が見つかりません。このときに，標準エラー出力とログにエラーメッセージが出力され，処理が終了されます（KDJW51187-E）。