XML マップのしくみ
XML マップとスクリプトは、サービスと通信対象のコンポーネントの間で XML メッセージをやり取りするネットワークと Web サービス（JWS ファイル）の間の変換レイヤとして機能します。マップまたはスクリプトを作成すると、Java 宣言の型が XML メッセージの内容とどのように対応するのかを WebLogic Server に通知できます。実行時に、WebLogic Server はサービスとネットワークの間で XML メッセージを転送するときにマップまたはスクリプトを実行します。
XML マップは、JWS または CTRL ファイルの、それが使用される Java 宣言の直前に挿入できます。また、別のファイルで XML マップまたはスクリプトを作成し、宣言の前に置いた注釈を基に参照する形式にもできます。
マップまたはスクリプトが実行されたときに何が起こるのかについての詳細は、XML マップからスクリプト関数を使用するを参照してください。
メソッドまたはコールバックは、パラメータ値をマッピングするマップと戻り値をマッピングするマップの 2 つの XML マップを持つことがあります。それらのマップは、それぞれ parameter-xml マップおよび return-xml マップと呼ばれます。たとえば、次のようなメソッド宣言を考えてください。
public String searchRequest(String productName, String serialNumber, int quantity)
この宣言のパラメータは serialNumber と quantity で、戻り値の型は String です。デフォルト マップは次のようになります。
/**
* @jws:operation
* @jws:parameter-xml xml-map::
* <searchRequest>
* <productName serialNumber="{serialNumber}">{productName}</productName>
* <quantity>{quantity}</quantity>
* </searchRequest>
*
* ::
* @jws:return-xml xml-map::
* <searchRequestResponse>
* <return>{return}</return>
* </searchRequestResponse>
*
* ::
*/
public String searchRequest (String productName, String serialNumber, int quantity)
この例で、XML 要素と属性の名前 （<searchRequest>、<productName>、serialNumber、<return> など）は、メソッドのシグネチャの内容を反映しています。また、メソッドのパラメータは実際の値としてメッセージに入るものを取得する代替変数として {} で囲まれています。
注意: このマップはそれが適用される宣言の直前の注釈に格納されますが、独立した XMLMAP ファイルに格納して、JWS ファイルの注釈から参照することもできます。別のファイルでのマップの格納については、再利用可能な XML マップを作成するを参照してください。
このデフォルト parameter-xml マップは、メソッド呼び出しを伝達する XML メッセージが次のようであることを前提とします。
<searchRequest> <productName serialNumber="12345">Widget</productName> <quantity>3</quantity> </searchRequest>
ただし、クライアントはサービスを利用したいが、そのクライアントの業界内の協定に基づいて異なるメッセージ フォーマットが使用されているというケースもあります。たとえば、そのクライアントからのメッセージは次のようであるかもしれません。
<queryData> <partName partID="12345">Widget</partName> <partQuantity>3</partQuantity> </queryData>
XML マップは、まさにこのような状況を克服するために設計されます。searchRequest メソッドについては、予期されるリクエスト メッセージで使用される XML フォーマットに似たマップを設計することができます。そのマップでは、要素コンテンツや属性値などが、そのコンテンツや値をメソッドのパラメータに導く括弧付きのプレースホルダで置換されます。次に、searchRequest メソッドの parameter-xml マップの例を示します。
/**
* @jws:operation
* @jws:parameter-xml xml-map::
* <searchRequest>
* <queryData>
* <partName partID="{serialNumber}">{productName}</partName>
* <partQuantity>{quantity}</partQuantity>
* </queryData>
* </searchRequest>
* ::
*/
public String searchRequest (String productName, String serialNumber, int quantity)
{ ... }
XML マップは XML メッセージの予期される形式に基づいて設計されるので、XML マップを作成するプロセスは常にマッチングされるサンプルの XML ドキュメントから始めます。たとえば、XML メッセージの形式に対するクライアントの制約に従ってマップを作成する場合は、そのクライアントからのサンプル メッセージを入手することが最初のステップとなります。
注意: ルート タグ（前出の例の <searchRequest> タグなど）は、特定の JWS ファイル内のすべてのマップの中でユニークでなければなりません。このため、名前がメソッド名と一致するタグの中にマップを配置するようにすることをお勧めします（つまりはメソッドもユニークでなければならない）。
作成した XML マップは、2 つの場所のいずれかに配置できます。まず、XML マップは（編集しやすいように）Java ソース コードとインラインで配置できます。また、（再利用できるように）独立したマップ ファイルに配置することも可能です。
マップを Java ソース コードとインラインで配置する場合は、[マップおよびインタフェースの編集] ダイアログを使用します。このダイアログは、作成したマップを、そのマップが適用されるメソッド、コールバック、またはコールバック ハンドラの宣言の直前に配置します。この位置に配置されたマップは、対応する Java 宣言のみで使用できます。しかし、宣言の直前にマップを配置すると、検索と編集がしやすいというメリットもあります。たとえば、ソース コードとインラインで配置された XML マップは、デザイン ビューで対応するアイコンをダブルクリックするだけで、[マップおよびインタフェースの編集] ダイアログを使用して容易に編集できます。
[マップおよびインタフェースの編集] ダイアログの使い方の詳細については、[マップおよびインタフェースの編集] ダイアログで XML マップを追加または編集するにはを参照してください。
独立したマップ ファイルを作成するときには、.xmlmap という拡張子でテキスト ファイルを作成し、XML マップをその中に格納します。独立したマップ ファイルにマップを配置すると、そのファイルを共通のリソースとして使用することができます。たとえば、Web サービスのすべてのメソッド、コールバック、およびコールバック ハンドラでそのファイルを使用できます。
マップの機能を提供するコードは、マップ ファイルの XML マップとソース コードのマップの両方で同じものです。つまり、マップを作成してそれを Java ソース コードとインラインで配置し、その後、マップの機能に変更を加えることなくそのマップをマップ ファイルに移動することができます。マップ ファイルのマップ コードは、ソース コードから呼び出せるように <xm:xml-map> タグで囲まなければならないという点でのみ異なります。
マップ ファイルのより具体的な情報については、再利用可能な XML マップを作成するを参照してください。