documentation/manual/ja/module_specs/Zend_Soap_Wsdl.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <!-- EN-Revision: 21740 -->
   4 <sect1 id="zend.soap.wsdl">
   5     <title>WSDLアクセッサ</title>
   6
   7     <note>
   8         <para>
   9             WSDL文書による操作を行なうために、
  10             内部的に<classname>Zend_Soap_Server</classname>コンポーネントによって<classname>Zend_Soap_Wsdl</classname>が使われます。
  11             それでも、このクラスにより提供される機能を独自の必要性によって使うこともできます。
  12             <classname>Zend_Soap_Wsdl</classname>パッケージは、パーサーとWSDL文書のビルダーを含みます。
  13         </para>
  14         <para>
  15             あなたに使う予定がなければ、この節を読み飛ばすことができます。
  16         </para>
  17     </note>
  18
  19     <sect2 id="zend.soap.wsdl.constructor">
  20         <title>Zend_Soap_Wsdlコンストラクタ</title>
  21         <para>
  22             <classname>Zend_Soap_Wsdl</classname>コンストラクタは３つのパラメータをとります:
  23             <orderedlist>
  24                 <listitem>
  25                     <simpara><code>$name</code> - 記述されたウェブサービスの名前。</simpara>
  26                 </listitem>
  27                 <listitem>
  28                     <simpara>
  29                         <code>$uri</code> - WSDLが利用できる<acronym>URI</acronym>
  30                         (ファイルシステムのファイルへのリファレンスでも可)
  31                     </simpara>
  32                 </listitem>
  33                 <listitem>
  34                     <simpara>
  35                         <code>$strategy</code> - 複雑な型（オブジェクト）を検出する方策を
  36                         識別するために用いられるオプションのフラグです。
  37                         これはバージョン1.7以前はブール値 <code>$extractComplexTypes</code>でしたが、
  38                         後方互換性のためにまだブール値として設定できます。
  39                         デフォルトで、1.6の検出動作が設定されます。
  40                         複雑な型の検出の方策について詳しくは、この節をご覧下さい:
  41                         <xref linkend="zend.soap.wsdl.types.add_complex" />
  42                     </simpara>
  43                 </listitem>
  44             </orderedlist>
  45         </para>
  46     </sect2>
  47
  48     <sect2 id="zend.soap.wsdl.addmessage">
  49         <title>addMessage()メソッド</title>
  50         <para>
  51             <methodname>addMessage($name, $parts)</methodname>メソッドは、新しいメッセージの説明をWSDL文書に加えます。
  52             (/definitions/message 要素)
  53         </para>
  54         <para>
  55             <classname>Zend_Soap_Server</classname>および<classname>Zend_Soap_Client</classname>の機能に関して、
  56             各々のメッセージはメソッドと対応します。
  57         </para>
  58         <para>
  59            <code>$name</code>パラメータはメッセージの名前を示します。
  60         </para>
  61         <para>
  62            <code>$parts</code>パラメータは<acronym>SOAP</acronym>呼び出しパラメータを表すメッセージ部分の配列です。
  63            それは連想配列です: 'part name' (<acronym>SOAP</acronym>呼び出しパラメータ名) =&gt; 'part type'.
  64         </para>
  65         <para>
  66             型マッピングの管理は<methodname>addTypes()</methodname>や<methodname>addTypes()</methodname>、
  67             および<methodname>addComplexType()</methodname>メソッド（下記参照）を用いて実行されます。
  68         </para>
  69         <note>
  70             <para>
  71                 メッセージ部分は 'element' または 'type' 属性を型決定のために使います。
  72                 (<ulink url="http://www.w3.org/TR/wsdl#_messages"/>をご覧ください).
  73             </para>
  74             <para>
  75                 'element' 属性は、データ型定義の対応する要素を参照しなければなりません。
  76                 'type' 属性は、対応するcomplexType項目を参照します。
  77             </para>
  78             <para>
  79                 標準XSD型のすべてで 'element' および 'complexType' 定義の両方があります。
  80                 (<ulink url="http://schemas.xmlsoap.org/soap/encoding/"/>参照)
  81             </para>
  82             <para>
  83                 <methodname>Zend_Soap_Wsdl::addComplexType()</methodname>メソッドを用いて追加されるであろう、
  84                 標準ではない型のすべてがWSDL文書の '/definitions/types/schema/' セクションの 'complexType' ノードで記述されます。
  85             </para>
  86             <para>
  87                 そして<methodname>addMessage()</methodname>メソッドは型を表現するために、
  88                 常に 'type' 属性を使います。
  89             </para>
  90         </note>
  91     </sect2>
  92
  93     <sect2 id="zend.soap.wsdl.add_port_type">
  94         <title>addPortType()メソッド</title>
  95         <para>
  96             <methodname>addPortType($name)</methodname>メソッドは指定されたポートタイプ名で
  97             WSDL文書 (/definitions/portType) に新規のポートタイプを追加します。
  98         </para>
  99         <para>
 100             <classname>Zend_Soap_Server</classname>の実装に関して定義されるウェブサービスメソッドのセットと結びつきます。
 101         </para>
 102         <para>
 103             詳しくは<ulink url="http://www.w3.org/TR/wsdl#_porttypes"/>をご覧ください。
 104         </para>
 105     </sect2>
 106
 107     <sect2 id="zend.soap.wsdl.add_port_operation">
 108         <title>addPortOperation()メソッド</title>
 109         <para>
 110             <methodname>addPortOperation($portType, $name, $input = false, $output = false, $fault = false)</methodname>
 111             メソッドは、新しいポート・オペレーションをWSDL文書 (/definitions/portType/operation) の
 112             指定されたポート・タイプに加えます。
 113         </para>
 114         <para>
 115             各々のポート・オペレーションは<classname>Zend_Soap_Server</classname>実装では、
 116             クラス・メソッド（ウェブサービスがクラスに基づくならば）
 117             または関数（ウェブサービスがメソッドセットに基づくならば）に対応します。
 118         </para>
 119         <para>
 120             それも、指定されたパラメータ、<code>$input</code>や<code>$output</code>および<code>$fault</code>に従って、
 121             対応するポート・オペレーション・メッセージを加えます。
 122             <note>
 123                 <para>
 124                     <classname>Zend_Soap_Server</classname>クラスに基づいてサービスを記述するために、
 125                     <classname>Zend_Soap_Server</classname>コンポーネントは各々のポート・オペレーションのために2つのメッセージを生成します:
 126                     <itemizedlist>
 127                         <listitem>
 128                             <para>
 129                                 <code>$methodName . 'Request'</code>という名前で入力メッセージ。
 130                             </para>
 131                         </listitem>
 132                         <listitem>
 133                             <para>
 134                                 <code>$methodName . 'Response'</code>という名前で出力メッセージ。
 135                             </para>
 136                         </listitem>
 137                     </itemizedlist>
 138                 </para>
 139             </note>
 140         </para>
 141         <para>
 142             詳しくは<ulink url="http://www.w3.org/TR/wsdl#_request-response"/>をご覧ください。
 143         </para>
 144     </sect2>
 145
 146     <sect2 id="zend.soap.wsdl.add_binding">
 147         <title>addBinding()メソッド</title>
 148         <para>
 149             <methodname>addBinding($name, $portType)</methodname>メソッドは、新しいバインディングをWSDL文書 (/definitions/binding) に加えます。
 150         </para>
 151         <para>
 152             'binding' WSDL文書ノードでは、
 153             メッセージ形式と特定のportTypeによって定義されるオペレーションとメッセージに関するプロトコル詳細を定義します。
 154             (<ulink url="http://www.w3.org/TR/wsdl#_bindings"/>をご覧ください)
 155         </para>
 156         <para>
 157             メソッドはバインディング・ノードをつくって、それを返します。
 158             それから、実際のデータで満たすために使われるかもしれません。
 159         </para>
 160
 161         <para>
 162             <classname>Zend_Soap_Server</classname>の実装ではWSDL文書の 'binding' 要素のために<code>$serviceName . 'Binding'</code> の名前が使われます。
 163         </para>
 164     </sect2>
 165
 166     <sect2 id="zend.soap.wsdl.add_binding_operation">
 167         <title>addBindingOperation()メソッド</title>
 168         <para>
 169             <methodname>addBindingOperation($binding, $name, $input = false, $output = false, $fault = false)</methodname>
 170             メソッドはバインディング要素 (/definitions/binding/operation) に指定された名前で操作を追加します。
 171         </para>
 172         <para>
 173             指定されたパラメータに従って、
 174             入力・出力・false値を持つ 'operation' 要素を加えるために、
 175             入力（<code>$binding</code>パラメータ）として<methodname>addBinding()</methodname>によって返される
 176             <code>XML_Tree_Node</code>オブジェクトをそのメソッドは取得します。
 177         </para>
 178         <para>
 179             <classname>Zend_Soap_Server</classname>の実装で、 'soap:body' 要素を
 180             '&lt;soap:body use="encoded" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/&gt;
 181             として定義している入出力エントリで、
 182             ウェブサービス・メソッドごとに対応するバインディング・エントリを加えます。
 183         </para>
 184         <para>
 185             詳しくは<ulink url="http://www.w3.org/TR/wsdl#_bindings"/>をご覧ください。
 186         </para>
 187     </sect2>
 188
 189     <sect2 id="zend.soap.wsdl.add_soap_binding">
 190         <title>addSoapBinding()メソッド</title>
 191         <para>
 192             <methodname>addSoapBinding($binding, $style = 'document', $transport = 'http://schemas.xmlsoap.org/soap/http')</methodname>
 193             メソッドは、指定されたスタイルとトランスポート（<classname>Zend_Soap_Server</classname>の実装では、<acronym>HTTP</acronym>についてRPCスタイルを使用します）で
 194             <acronym>SOAP</acronym>バインディング項目 ('soap:binding') をバインディング要素（それは、あるポートタイプにすでにリンクされます）に追加します。
 195         </para>
 196         <para>
 197             '/definitions/binding/soap:binding' 要素は、
 198             バインディングが<acronym>SOAP</acronym>プロトコル形式に束縛されることを示すのに用いられます。
 199         </para>
 200         <para>
 201             詳しくは<ulink url="http://www.w3.org/TR/wsdl#_bindings"/>をご覧ください。
 202         </para>
 203     </sect2>
 204
 205     <sect2 id="zend.soap.wsdl.add_soap_operation">
 206         <title>addSoapOperation()メソッド</title>
 207         <para>
 208             <methodname>addSoapOperation($binding, $soap_action)</methodname>メソッドは、
 209             <acronym>SOAP</acronym>操作項目 ('soap:operation') を指定されたアクションでバインディング要素に加えます。
 210             'soap:operation' 要素の 'style' 属性は、（RPC指向か文書指向の）プログラミング・モデルが
 211             <methodname>addSoapBinding()</methodname>メソッドを使用しているかもしれないので使われません。
 212         </para>
 213         <para>
 214             '/definitions/binding/soap:operation' 要素の 'soapAction' 属性は、
 215             この操作のためにSOAPActionヘッダの値を指定します。
 216             この属性は<acronym>HTTP</acronym>を通じた<acronym>SOAP</acronym>で必須です。
 217             他のトランスポートのために指定しては<emphasis>いけません</emphasis>。
 218         </para>
 219         <para>
 220             <classname>Zend_Soap_Server</classname>の実装では、<acronym>SOAP</acronym>操作アクション名のために
 221             <code>$serviceUri . '#' . $methodName</code>を使います。
 222         </para>
 223         <para>
 224             詳しくは<ulink url="http://www.w3.org/TR/wsdl#_soap:operation"/>をご覧ください。
 225         </para>
 226     </sect2>
 227
 228     <sect2 id="zend.soap.wsdl.add_service">
 229         <title>addService()メソッド</title>
 230         <para>
 231             <methodname>addService($name, $port_name, $binding, $location)</methodname>メソッドは
 232             指定したウェブサービス名やポートタイプ及びバインディング、ロケーションとともに
 233             WSDL文書に '/definitions/service' 要素を追加します。
 234         </para>
 235         <para>
 236             WSDL 1.1では、サービスごとにいくつかのポートタイプ(操作のセット)を持つことができます。
 237             この能力は<classname>Zend_Soap_Server</classname>の実装では使われず、
 238             <classname>Zend_Soap_Wsdl</classname>クラスでサポートされません。
 239         </para>
 240         <para>
 241             <classname>Zend_Soap_Server</classname>の実装に使用します:
 242             <itemizedlist>
 243                 <listitem>
 244                     <para>
 245                         ウェブサービス名として<code>$name . 'Service'</code>
 246                     </para>
 247                 </listitem>
 248                 <listitem>
 249                     <para>
 250                         ポートタイプ名として<code>$name . 'Port'</code>
 251                     </para>
 252                 </listitem>
 253                 <listitem>
 254                     <para>
 255                         バインディング名として<code>'tns:' . $name . 'Binding'</code>
 256                             <footnote>
 257                                 <para>
 258                                     <code>'tns:' namespace</code>はスクリプトの<acronym>URI</acronym>
 259                                     (<code>'http://' .$_SERVER['HTTP_HOST'] . $_SERVER['SCRIPT_NAME']</code>)
 260                                     として定義されます。
 261                                 </para>
 262                             </footnote>
 263                     </para>
 264                 </listitem>
 265                 <listitem>
 266                     <para>
 267                         クラスを使うウェブサービスの定義のためのサービス<acronym>URI</acronym>としてスクリプトの<acronym>URI</acronym>
 268                         <footnote><para><code>'http://' .$_SERVER['HTTP_HOST'] . $_SERVER['SCRIPT_NAME']</code></para></footnote>
 269                     </para>
 270                 </listitem>
 271             </itemizedlist>
 272             <code>$name</code>がクラスを使うウェブサービス定義モードのためのクラス名と
 273             関数のセットを使うウェブサービス定義モードのためのスクリプト名前であるところ。
 274         </para>
 275         <para>
 276             詳しくは<ulink url="http://www.w3.org/TR/wsdl#_services"/>をご覧ください。
 277         </para>
 278     </sect2>
 279
 280     <sect2 id="zend.soap.wsdl.types">
 281         <title>型のマッピング</title>
 282         <para>
 283             <classname>Zend_Soap</classname> WSDLアクセッサの実装では、<acronym>PHP</acronym>と<acronym>SOAP</acronym>型の間で以下の型マッピングを使用します:
 284             <itemizedlist>
 285                 <listitem>
 286                     <para><acronym>PHP</acronym>文字列 &lt;-&gt; <code>xsd:string</code></para>
 287                 </listitem>
 288                 <listitem>
 289                     <para><acronym>PHP</acronym> integer &lt;-&gt; <code>xsd:int</code></para>
 290                 </listitem>
 291                 <listitem>
 292                     <para><acronym>PHP</acronym> floatおよびdouble値 &lt;-&gt; <code>xsd:float</code></para>
 293                 </listitem>
 294                 <listitem>
 295                     <para><acronym>PHP</acronym>ブール値 &lt;-&gt; <code>xsd:boolean</code></para>
 296                 </listitem>
 297                 <listitem>
 298                     <para><acronym>PHP</acronym>配列 &lt;-&gt; <code>soap-enc:Array</code></para>
 299                 </listitem>
 300                 <listitem>
 301                     <para><acronym>PHP</acronym>オブジェクト &lt;-&gt; <code>xsd:struct</code></para>
 302                 </listitem>
 303                 <listitem>
 304                     <para>
 305                         <acronym>PHP</acronym>クラス &lt;-&gt; 複雑な型のストラテジーに基づいた (<xref linkend="zend.soap.wsdl.types.add_complex" />参照)
 306                         <footnote>
 307                             <para>
 308                                 デフォルトで、<classname>Zend_Soap_Wsdl</classname>は複雑な型のための検出アルゴリズムとして
 309                                 <classname>Zend_Soap_Wsdl_Strategy_DefaultComplexType</classname>クラスで生成されます。
 310                                 AutoDiscoverコンストラクタの最初のパラメータは、
 311                                 <classname>Zend_Soap_Wsdl_Strategy_Interface</classname>を実装した、
 312                                 どんな複雑な型ストラテジーでも、クラスの名前を持つ文字列でもとります。
 313                                 <code>$extractComplexType</code>との後方互換性のために、
 314                                 ブール変数は、以下の方法で解析されます:
 315                                 もし <constant>TRUE</constant> なら、<classname>Zend_Soap_Wsdl_Strategy_DefaultComplexType</classname>、
 316                                 もし <constant>FALSE</constant> なら、<classname>Zend_Soap_Wsdl_Strategy_AnyType</classname>。
 317                             </para>
 318                         </footnote>
 319                     </para>
 320                 </listitem>
 321                 <listitem>
 322                     <para><acronym>PHP</acronym> void &lt;-&gt; 空の型</para>
 323                 </listitem>
 324                 <listitem>
 325                     <para>なんらかの理由でこれらの型のいずれとも型が一致しなければ、<code>xsd:anyType</code>が使われます。</para>
 326                 </listitem>
 327             </itemizedlist>
 328
 329             <code>xsd:</code> が "http://www.w3.org/2001/XMLSchema" ネームスペースであるところでは、
 330             <code>soap-enc:</code> は "http://schemas.xmlsoap.org/soap/encoding/" ネームスペースで、
 331             <code>tns:</code> はサービスのための "target namespace" です。
 332         </para>
 333
 334         <sect3 id="zend.soap.wsdl.types.retrieve">
 335             <title>型情報の取得</title>
 336             <para>
 337                 <methodname>getType($type)</methodname>メソッドは、指定された <acronym>PHP</acronym> 型をマップするために用いられるかもしれません:
 338
 339             <programlisting language="php"><![CDATA[
 340 ...
 341 $wsdl = new Zend_Soap_Wsdl('My_Web_Service', $myWebServiceUri);
 342
 343 ...
 344 $soapIntType = $wsdl->getType('int');
 345
 346 ...
 347 class MyClass {
 348     ...
 349 }
 350 ...
 351 $soapMyClassType = $wsdl->getType('MyClass');
 352 ]]></programlisting>
 353             </para>
 354         </sect3>
 355
 356         <sect3 id="zend.soap.wsdl.types.add_complex">
 357             <title>複雑な型の情報を追加する</title>
 358             <para>
 359                 <methodname>addComplexType($type)</methodname>メソッドは、
 360                 複雑な型（<acronym>PHP</acronym>クラス）をWSDL文書に追加するために使われます。
 361             </para>
 362
 363             <para>
 364                 メソッド・パラメータの対応する複雑な型を追加するか、型を返すために、
 365                 <methodname>getType()</methodname>メソッドによってそれは自動的に使われます。
 366             </para>
 367
 368             <para>
 369                 その検出とビルドのアルゴリズムは、複雑な型に対して現在実装中の検出ストラテジーに基づきます。
 370                 文字列でのクラス名指定、
 371                 または、コンストラクタの第３パラメータとして<classname>Zend_Soap_Wsdl_Strategy_Interface</classname>を実装したインスタンス、
 372                 または、<classname>Zend_Soap_Wsdl</classname>の<code>setComplexTypeStrategy($strategy)</code>関数の利用のいずれかにより、
 373                 検出ストラテジーを設定できます。
 374                 以下の検出ストラテジーが、現在存在します:
 375             </para>
 376
 377             <itemizedlist>
 378                 <listitem>
 379                     <para>クラス<classname>Zend_Soap_Wsdl_Strategy_DefaultComplexType</classname>:
 380                     デフォルトで許可されます（第3のコンストラクタ・パラメータが設定されないとき）。
 381                     クラス型の public 属性項目を反復して、
 382                     複雑なオブジェクト型のサブタイプとして登録します。</para>
 383                 </listitem>
 384                 <listitem>
 385                     <para>クラス<classname>Zend_Soap_Wsdl_Strategy_AnyType</classname>:
 386                     単純なXSD型 xsd:anyType に、すべての複雑な型を投げます。
 387                     複雑な型検出のこのショートカットが
 388                     <acronym>PHP</acronym>のような型検査の弱い言語により、うまく取り扱われるかどうか注意してください。</para>
 389                 </listitem>
 390                 <listitem>
 391                     <para>クラス<classname>Zend_Soap_Wsdl_Strategy_ArrayOfTypeSequence</classname>:
 392                     このストラテジーにより、以下のようにタイプの戻りパラメータを指定できます:
 393                     <code>int[]</code>または<code>string[]</code>.
 394                     Zend Framework バージョン 1.9 以降、
 395                     それは単純な<acronym>PHP</acronym>型（例えばint）、文字列、ブール値、floatなどを取り扱えるばかりではなく、
 396                     オブジェクトおよびオブジェクトの配列も指定できます。</para>
 397                 </listitem>
 398                 <listitem>
 399                     <para>クラス<classname>Zend_Soap_Wsdl_Strategy_ArrayOfTypeComplex</classname>:
 400                     このストラテジーにより、非常に複雑な多数のオブジェクトを見つけることができます。
 401                     オブジェクト型は<classname>Zend_Soap_Wsdl_Strategy_DefaultComplexType</classname>に基づいて
 402                     検出されます。配列はその定義の周囲を包まれます。</para>
 403                 </listitem>
 404                 <listitem>
 405                     <para>クラス<classname>Zend_Soap_Wsdl_Strategy_Composite</classname>:
 406                     このストラテジーは、<methodname>connectTypeToStrategy($type, $strategy)</methodname>メソッドを通じて
 407                     希望するストラテジーに<acronym>PHP</acronym>の複雑な型（クラス名）を接続することによって、
 408                     すべてのストラテジーを結合できます。
 409                     完全なタイプマップを、<code>$type</code> -> <code>$strategy</code> のペアを持つ配列として
 410                     コンストラクタに与えられます。
 411                     もし未知の型の追加が必要であれば、第２パラメータで使われるデフォルト・ストラテジーを指定します。
 412                     このパラメータのデフォルトは、<classname>Zend_Soap_Wsdl_Strategy_DefaultComplexType</classname>です。</para>
 413                 </listitem>
 414             </itemizedlist>
 415
 416             <para>
 417                 <methodname>addComplexType()</methodname>メソッドは、指定された<acronym>PHP</acronym>クラスの名前で、
 418                 記述された複雑な型ごとに '/definitions/types/xsd:schema/xsd:complexType' 要素を生成します。
 419             </para>
 420
 421             <para>
 422                 クラスのプロパティは、プロパティをWSDL記述にインクルードしておくために、記述された<acronym>PHP</acronym>型でdocblock部を持って<emphasis>いなければなりません</emphasis>。
 423             </para>
 424
 425             <para>
 426                 <methodname>addComplexType()</methodname>は型がWSDL文書の型セクションの範囲内ですでに記述されるかどうか調べます。
 427             </para>
 428
 429             <para>
 430                 このメソッドが型定義部で２回以上再帰で呼ばれると、それは重複を防ぎます。
 431             </para>
 432
 433             <para>
 434                 詳しくは<ulink url="http://www.w3.org/TR/wsdl#_types"/>をご覧ください。
 435             </para>
 436
 437         </sect3>
 438     </sect2>
 439
 440     <sect2 id="zend.soap.wsdl.add_documentation">
 441         <title>addDocumentation()メソッド</title>
 442         <para>
 443             <methodname>addDocumentation($input_node, $documentation)</methodname>メソッドは、
 444             オプションの 'wsdl:document' 要素を用いて人間の読める文書を追加します。
 445         </para>
 446         <para>
 447             '/definitions/binding/soap:binding' 要素は、
 448             バインディングが<acronym>SOAP</acronym>プロトコル構成にバインドされることを示すために使われます。
 449         </para>
 450         <para>
 451             詳しくは<ulink url="http://www.w3.org/TR/wsdl#_documentation"/>をご覧ください。
 452         </para>
 453     </sect2>
 454
 455     <sect2 id="zend.soap.wsdl.retrieve">
 456         <title>確定したWSDL文書を取得</title>
 457         <para>
 458             <methodname>toXML()</methodname>や<methodname>toDomDocument()</methodname>および<methodname>dump($filename = false)</methodname>メソッドは、
 459             WSDL文書を<acronym>XML</acronym>やDOMの構造もしくはファイルとして取得するために使われるかもしれません。
 460         </para>
 461     </sect2>
 462
 463 </sect1>