document/literal の wrapped パターンを WSDL の設計に使用する

WSDL (Web Services Description Language) のバインディング・スタイルとしては、RPC スタイルまたは document スタイルのいずれかを選択することができますが、この双方のスタイルの利点を併せ持つものとして document/literal の wrapped パターンを選択することもできます。

Vivek Gupta, Technical Architect, Tata Consultancy Services

Vivek 氏には、10 年を超える Java/J2EE の経験があります。彼はこれまで、Java ベースのプロジェクトのために Web サービスの設計と開発を行い、WSDL を設計する上でのベスト・プラクティスを提供してきました。



2011年 6月 24日

はじめに

WSDL で document/literal スタイルのメッセージングを使用して、相互運用性の高い Web サービスを定義する場合、document/literal の wrapped パターンとして知られる「パターン」が、サービス・プロバイダーの間で広く採用されています。このパターンは、WSDL の RPC/literal スタイルのメッセージングと document/literal スタイルのメッセージングの両方の最も優れた特徴を採り入れています。その特徴とは以下に挙げるものです。

  1. SEI (Service Endpoint Interface) 操作の名前を SOAP メッセージに挿入するという特徴 ― これは RPC/literal の特徴です。
  2. W3C の XML Schema に基づいて SOAP メッセージを完全に定義するという特徴 ― これは document/literal の特徴です。

WSDL によって Web サービスを記述する際に定義するのは、Web サービスのインターフェース、そのインターフェースに対する操作、その操作とトランスポート・プロトコルとのバインディング、そして操作を利用できるネットワーク・アドレスです。WSDL バインディングには、Web サービスをメッセージング・プロトコルにバインドする方法 (つまり、サービスとの間で交換されるメッセージのフォーマットまたは構造と、そのメッセージを送信するためのトランスポート・プロトコル) が記述されます。今日の Web サービスで最もよく使用されるメッセージング・プロトコルは、SOAP メッセージング・プロトコルです (それ以外の選択肢としては、REST ベースのメッセージを使用する方法があります)。SOAP メッセージング・プロトコルを使用する Web サービスの場合、バインディングの「スタイル」としては、「RPC (Remote-Procedure-Call: リモート・プロシージャー・コール)」スタイルと「document (文書)」スタイルのいずれかをとることができます。どちらのバインディング・スタイルを選択するかは、Web サービスの操作に対する入出力メッセージと、それらに対応した SOAP リクエスト/レスポンス・メッセージの構造とを WSDL で定義する上で、非常に重要になります。この 2 つのバインディング・スタイルに対し、メッセージの表現方法として WS-I (Web Services Interoperability Organization) の勧告でサポートされているのは、「literal (リテラル)」による方法だけです (literal では、要素や型はスキーマによって定義され、またシリアライズは W3C の XML Schema の定義に従います)。

document/literal スタイルでのメッセージングには、document/literal の wrapped パターンとして知られるパターンが存在します。これは単なるパターンであり、WSDL の仕様には含まれていません。このパターンについては JSR 224 (JAX-WS: Java API for XML-Based Web Services) で触れられています。

この記事では、このパターンを WSDL で使用する場合の規則について説明しますが、特に WSDL を設計する際に、このパターンを使用する方法に重点を置きます。これ以降のセクションでは、この document/literal の wrapped パターンについて説明します。


document/literal スタイル ( wrapped パターン) の SOAP メッセージングに対する規則

WSDL を設計する際に従う必要のある、wrapped パターンに対する規則を以下に挙げます。

  1. WSDL の入出力メッセージには「part (パート)」の定義は「1 つ」しか存在してはならない
    wrapped パターンは、document/literal の形式の 1 つです。WS-I に準拠した document/literal サービスを定義する場合、入力メッセージの本体の part は最大でも 1 つしかなく、また出力メッセージの本体の part も最大で 1 つしかありません。また各メソッドのパラメーターを、メッセージ定義内の別々の部分として定義しては『なりません』 (メソッドのパラメーターは WSDL の types セクションで定義されます)。
  2. part の定義はラッパー要素である
    各 part の定義は、document スタイルのメッセージングにするために定義された要素を参照する必要があります (型を参照するのではありません。型は RPC で使用されます)。この要素定義はインポートすることも、WSDL 文書の types セクションに含めることもできます。これらの要素定義は「ラッパー」要素です (これが wrapped パターンという名前の由来です)。これらのラッパー要素内の要素の構造として、入出力パラメーターを定義します。
  3. part 要素の型の子要素は、SEI メソッドのパラメーターである
    入力ラッパー要素は、一連の要素で構成された複合型として定義する必要があります。この一連の要素内の各々の子要素の型は、サービス・インターフェースにおける操作のパラメーターとして (WSDL のコード生成ツールを使用して) 生成されます。
  4. 入力ラッパー要素の名前は、操作の名前と一致する必要がある
    入力ラッパー要素の名前は、WSDL での Web サービス操作の名前と同じでなければなりません。
  5. <出力ラッパー要素の名前> = <操作の名前> + "Response"
    出力ラッパー要素の名前は、操作の名前に「Response」を追加した名前にすることができます (ただし必ずそうしなければならないわけではありません)。(例えば、操作の名前が「add」の場合、出力ラッパー要素の名前は「addResponse」となるはずです。)
  6. WSDL のバインディング・セクションでは、soap:binding style = "document" にする
    この wrapped パターンのスタイルは document/literal なので、バインディングを定義するための soap:binding では style="document" を指定する必要があり (ただしこれはデフォルト値なので、この属性の指定は省略しても構いません)、soap:body の定義では use="literal" を指定する必要があります。それ以外に指定をしてはなりません。soap:body の定義の中で、namespace 属性や encodingStyle 属性を指定してはなりません。

このパターンの説明には、「Which style of WSDL should I use?」で用いられている図式を使用しました。

下記のリスト 1 を見ると、ラッパー要素「myMethod」が portType セクションの操作名「myMethod」に一致していることがわかります。

リスト 1. myMethod 用の document/literal の wrapped パターンによる WSDL
<types>
    <schema>
        <element name="myMethod">
            <complexType>
                <sequence>
                    <element name="x" type="xsd:int"/>
                </sequence>
            </complexType>
        </element>
        <element name="myMethod Response">
            <complexType>
                <sequence>
                    <element name="z" type="xsd:int"/>
                </sequence>
            </complexType>
        </element>
    </schema>
</types>
<message name="myMethodRequest">
    <part name="parameters" element="myMethod"/>
</message>
<message name="myMethodResponse">
    <part name="parameters" element="myMethodResponse"/>
</message>
<portType name="PT">
    <operation name="myMethod">
        <input message="myMethodRequest"/>
        <output message="myMethodResponse"/>
    </operation>
</portType>
<binding.../>

SOAP リクエスト・メッセージをリスト 2 に示します。

リスト 2. myMethod 用の document/literal の wrapped パターンによる SOAP メッセージ
<SOAP-ENV:Body>
    <myMethod>
        <x>-0</x>
        <y>3.14</y>
    </myMethod>
</SOAP-ENV:Body>

以下に示すのは、JWSDP 2.0 の「wsimport」機能を利用して WSDL から生成された Java SEI のスナップショットです。この WSDL は、document/literal の wrapped パターンを使用しました。このリストを見るとわかるように、メソッド名は入力要素名と一致します。

リスト 3. myMethod 用の document/literal の wrapped パターンによる WSDL 上で実行される wsimport から生成された Java SEI
/**
  *This class was generated by JAXWS SI.
  *JAX-WS RI 2.0-b62-ea3
  *Generated source version: 2.0
  *
  */
  @WebService(name ="PT", wsdlLocation = "PT.wsdl")
  public interface PT {

  /**
  *
  *@param y
  *@param x
  *@return
  *   returns int
  */
  @WebMethods
  @WebResult(name ="z")
  @RequestWrapper(localname = "myMethod", className = "myMethod")
  @ResponseWrapper(localname = "myMethodResponse", className = "MyMethodResponse")

  public int myMethod (
    @WebParam(name = "x", targetNameSpace = "")
    int x,
    @WebParam(name = "y", targetNameSpace = "")
    float y);
}

document/literal スタイル ( wrapped パターン) の利点

このパターンに従うと以下の利点があると考えられます。

  1. document/literal スタイル ( wrapped パターン) は、Web サービス・プロバイダーの間に広く受け入れられている
    document/literal の wrapped パターンにより、非常に相互運用性の高い Web サービスを設計することができ、このパターンは Web サービスを定義する上でのデファクト・スタンダードとして、サービス・プロバイダーのコミュニティーで広く受け入れられています。この document/literal の wrapped パターンは Microsoft の環境から進化したものであり、以下の事実があります。
    1. Microsoft は RPC/literal を明示的にはサポートしていません。
    2. Microsoft のツールはデフォルトで、この document/literal の wrapped パターンを使用して WSDL を生成します。

      そのため、相互運用性の点から、この document/literal の wrapped パターンは必然的によく使用されるようになります。

      このパターンには以下の 2 つの利点があります。
    1. soap:Body の下にある SOAP メッセージ全体を、スキーマに対して検証することができます。
    2. このパターンでは soap:Body の下にある子要素が 1 つのみに制限されるため、「必ず」 WS-I に準拠します。

このパターンはこのように相互運用性が高いため、Web サービスの他のメッセージング・スタイル (RPC/literal や、document/literal の bare パターンなど) よりも広く業界に受け入れられています。また、IBM の WebSphere ツールは、Web サービスの開発にボトムアップ方式を使用する際は、このパターンで WSDL を生成します。

  1. SOAP エンジンが SOAP リクエストを適切な Web サービス・プロバイダーに「ディスパッチ」することができる
    SOAP エンジンには、このパターンを使用する利点があります。SOAP エンジンでは、(XML から Java/C# などへの) アンマーシャリングの際、RPC スタイルで利用可能となるものと同じ明確で単純な命名規則を利用できるからです。このため SOAP エンジンでは、受信される (WS-Address ではない) SOAP リクエスト・メッセージに含まれるパラメーターを突き合わせるという余分な処理が不要になります。
図 1. エンドポイントの実装にディスパッチされる SOAP メッセージ
エンドポイントの実装にディスパッチされる SOAP メッセージ

このパターンの場合、SOAP エンジンは SOAP メッセージのディスパッチ先となるインターフェースとメソッドの名前を wsdl:portType を用いて判断します。業界における SOAP エンジンの先駆者 (例えば Apache Axis2) によるディスパッチ・プロセスでは、SOAP メッセージの soap:Body の下にある最初の子要素を操作名にマッピングします。

Web サービスのデプロイメント記述子には、document/literal の wrapped パターンの情報が含まれています。Web サービスの中に 2 つの異なるメソッドがあり、その 2 つのメソッドの入力パラメーターに同じ名前のものがある場合、SOPA エンジンは、SOAP メッセージがディスパッチされるべき操作の正確な名前を、判断しにくくなります。document/literal の wrapped パターンの場合、操作名はマッピングされています。そのため、ある Web サービスにおいて、メソッドごとに入力パラメーターの名前を変える、という追加の制約は必要ありません。

  1. 最適な方法
    このスタイルは一般的には、保守性、包括性、移植性、そして (ある程度の) パフォーマンスを向上させる最適な方法とみなされています。このパターンによって、パフォーマンスが向上する主な理由は以下のとおりです。
    1. エンコーディングを全く使用していません (これは literal を使用することによる利点です)。
    2. SOAP メッセージの複雑なデータ構造を直接解析することができ、また検証を最適化することができます (これは document スタイルのメッセージングによる利点です)。
    3. あるテストでは、RPC/literal よりもパフォーマンスが高いという結果も出ています。
  2. 複数の入力パラメーターを持つ Web サービス操作に適している
    複数のパラメーターを取るメソッドがあり、そのメソッドを Web サービスとして公開したい場合には、WS-I に準拠するのと同時に、以下の 2 つのいずれかを選択する必要があります。
    1. RPC/literal
    2. document/literal ( wrapped パターン)

document/literal ( bare パターン) を使用することはできません。WS-I により、SOAP メッセージの soap:Body 要素の下に複数の子要素を持つことはできないからです。document/literal ( wrapped パターン) の方が RPC/literal よりも優れている点は、soap:Body の下にあるメッセージ全体がスキーマで定義され、スキーマ・パーサーを利用して検証を行える点です。RPC/literal では、Web サービスの操作名とパート名は XML Schema に含まれません。

  1. document/literal ( wrapped パターン) の方が、document/literal ( bare パターン) よりも優れている点
    document/literal ( wrapped パターン) は、document/literal スタイルのメッセージング形式の 1 つです。しかし、document/literal スタイルのメッセージング全般を、制約付きの document/literal ( wrapped パターン) と比較すると、document/literal ( bare パターン) を使用する SOAP メッセージの欠点は、受信した XML 文書に対応する Web サービスの操作はどれであるかについての詳細情報がメッセージの中に含まれていない点であることがわかります。そのため、ある Web サービスの 2 つの異なる操作が、同じ型のメソッド・パラメーターを持つ場合、SOAP エンジンはどちらの操作にディスパッチすればよいのか判断しにくくなります。RPC スタイルのメッセージングには、操作の情報が含まれています。document/literal ( wrapped パターン) によるデザイン・パターンでは、操作の入力パラメーターを表すラッパー要素を文書に追加することで、操作の情報が含まれないという欠点を解消しています。

考察: オーバーロードされたメソッドと、document/literal の wrapped パターン

メソッドのオーバーロード

リスト 4. オーバーロードされた add メソッド
public void add(int addReq){}
public void add(String addReq){}
  1. この document/literal の wrapped パターンは、メソッドをオーバーロードする場合には使用することはできません。このパターンを使用してメソッドをオーバーロードするためには、同じ名前を持つ 2 つの要素が WSDL の型/スキーマの中に必要となります。これを XML Schema の規則 (異なる名前空間) を使用して実現することはできますが、Web サービスの場合にはメソッドのオーバーロードは推奨されません。
  2. WS-I Basic Profile 1.0 (R2304 を参照) では、wsdl:portType 内の操作の名前は一意でなければならないと規定されています。そのため、WS-I に準拠するためには、いかなる場合であっても操作をオーバーロードすることはできません。
  3. WSDL 2.0 は操作のオーバーロードをサポートしていません。そのため、オーバーロードされた操作は将来性がなく、避ける必要があります。

まとめ

この記事では、WSDL を設計する際に、document/literal の wrapped パターンがもたらす付加価値について、またメソッドをオーバーロードするプログラミング方式の欠点について説明しました。しかし WS-I 勧告では、メソッドをオーバーロードすること自体が推奨されなくなっています。そのため、「相互運用可能な」Web サービスを設計するためには、document/literal スタイルの wrapped パターンのバインディングで Web サービスを定義するしか選択肢は残されていません。

この document/literal の wrapped パターンは広く受け入れられており、高い相互運用性も備えているため、エンタープライズ・システムの Web サービスとサービス指向アーキテクチャー (SOA) との間の密接な関係に付加価値をもたらしています。そしてそこでは、異種混成のシステムが互いにやり取りし、ボトムアップ方式の設計手法もトップダウン方式の設計手法も各々が同じように一般的に採用されています。

参考文献

コメント

developerWorks: サイン・イン

必須フィールドは(*)で示されます。


IBM ID が必要ですか?
IBM IDをお忘れですか?


パスワードをお忘れですか?
パスワードの変更

「送信する」をクリックすることにより、お客様は developerWorks のご使用条件に同意したことになります。 ご使用条件を読む

 


お客様が developerWorks に初めてサインインすると、お客様のプロフィールが作成されます。会社名を非表示とする選択を行わない限り、プロフィール内の情報(名前、国/地域や会社名)は公開され、投稿するコンテンツと一緒に表示されますが、いつでもこれらの情報を更新できます。

送信されたすべての情報は安全です。

ディスプレイ・ネームを選択してください



developerWorks に初めてサインインするとプロフィールが作成されますので、その際にディスプレイ・ネームを選択する必要があります。ディスプレイ・ネームは、お客様が developerWorks に投稿するコンテンツと一緒に表示されます。

ディスプレイ・ネームは、3文字から31文字の範囲で指定し、かつ developerWorks コミュニティーでユニークである必要があります。また、プライバシー上の理由でお客様の電子メール・アドレスは使用しないでください。

必須フィールドは(*)で示されます。

3文字から31文字の範囲で指定し

「送信する」をクリックすることにより、お客様は developerWorks のご使用条件に同意したことになります。 ご使用条件を読む

 


送信されたすべての情報は安全です。


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=60
Zone=SOA and web services
ArticleID=681609
ArticleTitle=document/literal の wrapped パターンを WSDL の設計に使用する
publish-date=06242011