repo_zf1/documentation/manual/ja/module_specs/Zend_Soap_Wsdl.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 15685 -->
<sect1 id="zend.soap.wsdl">
    <title>WSDLアクセッサ</title>

    <note>
        <para>
            WSDL文書による操作を行なうために、
            内部的にZend_Soap_Serverコンポーネントによって<classname>Zend_Soap_Wsdl</classname>が使われます。
            それでも、このクラスにより提供される機能を独自の必要性によって使うこともできます。
            Zend_Soap_Wsdlパッケージは、パーサーとWSDL文書のビルダーを含みます。
        </para>
        <para>
            あなたに使う予定がなければ、この節を読み飛ばすことができます。
        </para>
    </note>

    <sect2 id="zend.soap.wsdl.constructor">
        <title>Zend_Soap_Wsdlコンストラクタ</title>
        <para>
            <classname>Zend_Soap_Wsdl</classname>コンストラクタは３つのパラメータをとります:
            <orderedlist>
                <listitem>
                    <simpara><code>$name</code> - 記述されたウェブサービスの名前。</simpara>
                </listitem>
                <listitem>
                    <simpara>
                        <code>$uri</code> - WSDLが利用できるURI
                        (ファイルシステムのファイルへのリファレンスでも可)
                    </simpara>
                </listitem>
                <listitem>
                    <simpara>
                        <code>$strategy</code> - 複雑な型（オブジェクト）を検出する方策を
                        識別するために用いられるオプションのフラグです。
                        これはバージョン1.7以前はブール値 <code>$extractComplexTypes</code>でしたが、
                        後方互換性のためにまだブール値として設定できます。
                        デフォルトで、1.6の検出動作が設定されます。
                        複雑な型の検出の方策について詳しくは、この節をご覧下さい:
                        <xref linkend="zend.soap.wsdl.types.add_complex" />
                    </simpara>
                </listitem>
            </orderedlist>
        </para>
    </sect2>

    <sect2 id="zend.soap.wsdl.addmessage">
        <title>addMessage()メソッド</title>
        <para>
            <code>addMessage($name, $parts)</code>メソッドは、新しいメッセージの説明をWSDL文書に加えます。
            (/definitions/message 要素)
        </para>
        <para>
            <classname>Zend_Soap_Server</classname>および<classname>Zend_Soap_Client</classname>の機能に関して、
            各々のメッセージはメソッドと対応します。
        </para>
        <para>
           <code>$name</code>パラメータはメッセージの名前を示します。
        </para>
        <para>
           <code>$parts</code>パラメータはSOAP呼び出しパラメータを表すメッセージ部分の配列です。
           それは連想配列です: 'part name' (SOAP呼び出しパラメータ名) =&gt; 'part type'.
        </para>
        <para>
            型マッピングの管理は<code>addTypes()</code>や<code>addTypes()</code>、
            および<code>addComplexType()</code>メソッド（下記参照）を用いて実行されます。
        </para>
        <note>
            <para>
                メッセージ部分は 'element' または 'type' 属性を型決定のために使います。
                (<ulink url="http://www.w3.org/TR/wsdl#_messages"/>をご覧ください).
            </para>
            <para>
                'element' 属性は、データ型定義の対応する要素を参照しなければなりません。
                'type' 属性は、対応するcomplexType項目を参照します。
            </para>
            <para>
                標準XSD型のすべてで 'element' および 'complexType' 定義の両方があります。
                (<ulink url="http://schemas.xmlsoap.org/soap/encoding/"/>参照)
            </para>
            <para>
                <classname>Zend_Soap_Wsdl::addComplexType()</classname>メソッドを用いて追加されるであろう、
                標準ではない型のすべてがWSDL文書の '/definitions/types/schema/' セクションの 'complexType' ノードで記述されます。
            </para>
            <para>
                そして<code>addMessage()</code>メソッドは型を表現するために、
                常に 'type' 属性を使います。
            </para>
        </note>
    </sect2>

    <sect2 id="zend.soap.wsdl.add_port_type">
        <title>addPortType()メソッド</title>
        <para>
            <code>addPortType($name)</code>メソッドは指定されたポートタイプ名で
            WSDL文書 (/definitions/portType) に新規のポートタイプを追加します。
        </para>
        <para>
            Zend_Soap_Serverの実装に関して定義されるウェブサービスメソッドのセットと結びつきます。
        </para>
        <para>
            詳しくは<ulink url="http://www.w3.org/TR/wsdl#_porttypes"/>をご覧ください。
        </para>
    </sect2>

    <sect2 id="zend.soap.wsdl.add_port_operation">
        <title>addPortOperation()メソッド</title>
        <para>
            <code>addPortOperation($portType, $name, $input = false, $output = false, $fault = false)</code>
            メソッドは、新しいポート・オペレーションをWSDL文書 (/definitions/portType/operation) の
            指定されたポート・タイプに加えます。
        </para>
        <para>
            各々のポート・オペレーションはZend_Soap_Server実装では、
            クラス・メソッド（ウェブサービスがクラスに基づくならば）
            または関数（ウェブサービスがメソッドセットに基づくならば）に対応します。
        </para>
        <para>
            それも、指定されたパラメータ、<code>$input</code>や<code>$output</code>および<code>$fault</code>に従って、
            対応するポート・オペレーション・メッセージを加えます。
            <note>
                <para>
                    <classname>Zend_Soap_Server</classname>クラスに基づいてサービスを記述するために、
                    Zend_Soap_Serverコンポーネントは各々のポート・オペレーションのために2つのメッセージを生成します:
                    <itemizedlist>
                        <listitem>
                            <para>
                                <code>$methodName . 'Request'</code>という名前で入力メッセージ。
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <code>$methodName . 'Response'</code>という名前で出力メッセージ。
                            </para>
                        </listitem>
                    </itemizedlist>
                </para>
            </note>
        </para>
        <para>
            詳しくは<ulink url="http://www.w3.org/TR/wsdl#_request-response"/>をご覧ください。
        </para>
    </sect2>

    <sect2 id="zend.soap.wsdl.add_binding">
        <title>addBinding()メソッド</title>
        <para>
            <code>addBinding($name, $portType)</code>メソッドは、新しいバインディングをWSDL文書 (/definitions/binding) に加えます。
        </para>
        <para>
            'binding' WSDL文書ノードでは、
            メッセージ形式と特定のportTypeによって定義されるオペレーションとメッセージに関するプロトコル詳細を定義します。
            (<ulink url="http://www.w3.org/TR/wsdl#_bindings"/>をご覧ください)
        </para>
        <para>
            メソッドはバインディング・ノードをつくって、それを返します。
            それから、実際のデータで満たすために使われるかもしれません。
        </para>

        <para>
            Zend_Soap_Serverの実装ではWSDL文書の 'binding' 要素のために<code>$serviceName . 'Binding'</code> の名前が使われます。
        </para>
    </sect2>

    <sect2 id="zend.soap.wsdl.add_binding_operation">
        <title>addBindingOperation()メソッド</title>
        <para>
            <code>addBindingOperation($binding, $name, $input = false, $output = false, $fault = false)</code>
            メソッドはバインディング要素 (/definitions/binding/operation) に指定された名前で操作を追加します。
        </para>
        <para>
            指定されたパラメータに従って、
            入力・出力・false値を持つ 'operation' 要素を加えるために、
            入力（<code>$binding</code>パラメータ）として<code>addBinding()</code>によって返される
            <code>XML_Tree_Node</code>オブジェクトをそのメソッドは取得します。
        </para>
        <para>
            Zend_Soap_Serverの実装で、 'soap:body' 要素を
            '&lt;soap:body use="encoded" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/&gt;
            として定義している入出力エントリで、
            ウェブサービス・メソッドごとに対応するバインディング・エントリを加えます。
        </para>
        <para>
            詳しくは<ulink url="http://www.w3.org/TR/wsdl#_bindings"/>をご覧ください。
        </para>
    </sect2>

    <sect2 id="zend.soap.wsdl.add_soap_binding">
        <title>addSoapBinding()メソッド</title>
        <para>
            <code>addSoapBinding($binding, $style = 'document', $transport = 'http://schemas.xmlsoap.org/soap/http')</code>
            メソッドは、指定されたスタイルとトランスポート（Zend_Soap_Serverの実装では、HTTPについてRPCスタイルを使用します）で
            SOAPバインディング項目 ('soap:binding') をバインディング要素（それは、あるポートタイプにすでにリンクされます）に追加します。
        </para>
        <para>
            '/definitions/binding/soap:binding' 要素は、
            バインディングがSOAPプロトコル形式に束縛されることを示すのに用いられます。
        </para>
        <para>
            詳しくは<ulink url="http://www.w3.org/TR/wsdl#_bindings"/>をご覧ください。
        </para>
    </sect2>

    <sect2 id="zend.soap.wsdl.add_soap_operation">
        <title>addSoapOperation()メソッド</title>
        <para>
            <code>addSoapOperation($binding, $soap_action)</code>メソッドは、
            SOAP操作項目 ('soap:operation') を指定されたアクションでバインディング要素に加えます。
            'soap:operation' 要素の 'style' 属性は、（RPC指向か文書指向の）プログラミング・モデルが
            <code>addSoapBinding()</code>メソッドを使用しているかもしれないので使われません。
        </para>
        <para>
            '/definitions/binding/soap:operation' 要素の 'soapAction' 属性は、
            この操作のためにSOAPActionヘッダの値を指定します。
            この属性はHTTPを通じたSOAPで必須です。
            他のトランスポートのために指定しては<emphasis>いけません</emphasis>。
        </para>
        <para>
            Zend_Soap_Serverの実装では、SOAP操作アクション名のために
            <code>$serviceUri . '#' . $methodName</code>を使います。
        </para>
        <para>
            詳しくは<ulink url="http://www.w3.org/TR/wsdl#_soap:operation"/>をご覧ください。
        </para>
    </sect2>

    <sect2 id="zend.soap.wsdl.add_service">
        <title>addService()メソッド</title>
        <para>
            <code>addService($name, $port_name, $binding, $location)</code>メソッドは
            指定したウェブサービス名やポートタイプ及びバインディング、ロケーションとともに
            WSDL文書に '/definitions/service' 要素を追加します。
        </para>
        <para>
            WSDL 1.1では、サービスごとにいくつかのポートタイプ(操作のセット)を持つことができます。
            この能力はZend_Soap_Serverの実装では使われず、
            <classname>Zend_Soap_Wsdl</classname>クラスでサポートされません。
        </para>
        <para>
            Zend_Soap_Serverの実装に使用します:
            <itemizedlist>
                <listitem>
                    <para>
                        ウェブサービス名として<code>$name . 'Service'</code>
                    </para>
                </listitem>
                <listitem>
                    <para>
                        ポートタイプ名として<code>$name . 'Port'</code>
                    </para>
                </listitem>
                <listitem>
                    <para>
                        バインディング名として<code>'tns:' . $name . 'Binding'</code>
                            <footnote>
                                <para>
                                    <code>'tns:' namespace</code>はスクリプトのURI
                                    (<code>'http://'  .$_SERVER['HTTP_HOST'] . $_SERVER['SCRIPT_NAME']</code>)
                                    として定義されます。
                                </para>
                            </footnote>
                    </para>
                </listitem>
                <listitem>
                    <para>
                        クラスを使うウェブサービスの定義のためのサービスURIとしてスクリプトのURI
                        <footnote><para><code>'http://'  .$_SERVER['HTTP_HOST'] . $_SERVER['SCRIPT_NAME']</code></para></footnote>
                    </para>
                </listitem>
            </itemizedlist>
            <code>$name</code>がクラスを使うウェブサービス定義モードのためのクラス名と
            関数のセットを使うウェブサービス定義モードのためのスクリプト名前であるところ。
        </para>
        <para>
            詳しくは<ulink url="http://www.w3.org/TR/wsdl#_services"/>をご覧ください。
        </para>
    </sect2>

    <sect2 id="zend.soap.wsdl.types">
        <title>型のマッピング</title>
        <para>
            Zend_Soap WSDLアクセッサの実装では、PHPとSOAP型の間で以下の型マッピングを使用します:
            <itemizedlist>
                <listitem>
                    <para>PHP文字列 &lt;-&gt; <code>xsd:string</code></para>
                </listitem>
                <listitem>
                    <para>PHP integer &lt;-&gt; <code>xsd:int</code></para>
                </listitem>
                <listitem>
                    <para>PHP floatおよびdouble値 &lt;-&gt; <code>xsd:float</code></para>
                </listitem>
                <listitem>
                    <para>PHPブール値 &lt;-&gt; <code>xsd:boolean</code></para>
                </listitem>
                <listitem>
                    <para>PHP配列 &lt;-&gt; <code>soap-enc:Array</code></para>
                </listitem>
                <listitem>
                    <para>PHPオブジェクト &lt;-&gt; <code>xsd:struct</code></para>
                </listitem>
                <listitem>
                    <para>
                        PHPクラス &lt;-&gt; 複雑な型のストラテジーに基づいた (<xref linkend="zend.soap.wsdl.types.add_complex" />参照)
                        <footnote>
                            <para>
                                デフォルトで、<classname>Zend_Soap_Wsdl</classname>は複雑な型のための検出アルゴリズムとして
                                <classname>Zend_Soap_Wsdl_Strategy_DefaultComplexType</classname>クラスで生成されます。
                                AutoDiscoverコンストラクタの最初のパラメータは、
                                <classname>Zend_Soap_Wsdl_Strategy_Interface</classname>を実装した、
                                どんな複雑な型ストラテジーでも、クラスの名前を持つ文字列でもとります。
                                <code>$extractComplexType</code>との後方互換性のために、
                                ブール変数は、以下の方法で解析されます:
                                もしtrueなら、<classname>Zend_Soap_Wsdl_Strategy_DefaultComplexType</classname>、
                                もしfalseなら、<classname>Zend_Soap_Wsdl_Strategy_AnyType</classname>。
                            </para>
                        </footnote>
                    </para>
                </listitem>
                <listitem>
                    <para>PHP void &lt;-&gt; 空の型</para>
                </listitem>
                <listitem>
                    <para>なんらかの理由でこれらの型のいずれとも型が一致しなければ、<code>xsd:anyType</code>が使われます。</para>
                </listitem>
            </itemizedlist>

            <code>xsd:</code> が "http://www.w3.org/2001/XMLSchema" ネームスペースであるところでは、
            <code>soap-enc:</code> は "http://schemas.xmlsoap.org/soap/encoding/" ネームスペースで、
            <code>tns:</code> はサービスのための "target namespace" です。
        </para>

        <sect3 id="zend.soap.wsdl.types.retrieve">
            <title>型情報の取得</title>
            <para>
                <code>getType($type)</code>メソッドは、指定されたPHP型をマップするために用いられるかもしれません:

            <programlisting language="php"><![CDATA[
...
$wsdl = new Zend_Soap_Wsdl('My_Web_Service', $myWebServiceUri);

...
$soapIntType = $wsdl->getType('int');

...
class MyClass {
    ...
}
...
$soapMyClassType = $wsdl->getType('MyClass');
]]></programlisting>
            </para>
        </sect3>

        <sect3 id="zend.soap.wsdl.types.add_complex">
            <title>複雑な型の情報を追加する</title>
            <para>
                <code>addComplexType($type)</code>メソッドは、
                複雑な型（PHPクラス）をWSDL文書に追加するために使われます。
            </para>

            <para>
                メソッド・パラメータの対応する複雑な型を追加するか、型を返すために、
                <code>getType()</code>メソッドによってそれは自動的に使われます。
            </para>

            <para>
                その検出とビルドのアルゴリズムは、複雑な型に対して現在実装中の検出ストラテジーに基づきます。
                文字列でのクラス名指定、
                または、コンストラクタの第３パラメータとして<classname>Zend_Soap_Wsdl_Strategy_Interface</classname>を実装したインスタンス、
                または、Zend_Soap_Wsdlの<code>setComplexTypeStrategy($strategy)</code>関数の利用のいずれかにより、
                検出ストラテジーを設定できます。
                以下の検出ストラテジーが、現在存在します:
            </para>

            <itemizedlist>
                <listitem>
                    <para>クラス<classname>Zend_Soap_Wsdl_Strategy_DefaultComplexType</classname>:
                    デフォルトで許可されます（第3のコンストラクタ・パラメータが設定されないとき）。
                    クラス型の public 属性項目を反復して、
                    複雑なオブジェクト型のサブタイプとして登録します。</para>
                </listitem>
                <listitem>
                    <para>クラス<classname>Zend_Soap_Wsdl_Strategy_AnyType</classname>:
                    単純なXSD型 xsd:anyType に、すべての複雑な型を投げます。
                    複雑な型検出のこのショートカットが
                    PHPのような型検査の弱い言語により、うまく取り扱われるかどうか注意してください。</para>
                </listitem>
                <listitem>
                    <para>クラス<classname>Zend_Soap_Wsdl_Strategy_ArrayOfTypeSequence</classname>:
                    このストラテジーにより、以下のようにタイプの戻りパラメータを指定できます:
                    <code>int[]</code>または<code>string[]</code>.
                    それは単純なPHP型（例えばint）、文字列、ブール値、floatなどを取り扱えるばかりではなく、
                    タイプの配列の入れ子の配列も指定できます。</para>
                </listitem>
                <listitem>
                    <para>クラス<classname>Zend_Soap_Wsdl_Strategy_ArrayOfTypeComplex</classname>:
                    このストラテジーにより、非常に複雑な多数のオブジェクトを見つけることができます。
                    オブジェクト型は<classname>Zend_Soap_Wsdl_Strategy_DefaultComplexType</classname>に基づいて
                    検出されます。配列はその定義の周囲を包まれます。</para>
                </listitem>
                <listitem>
                    <para>クラス<classname>Zend_Soap_Wsdl_Strategy_Composite</classname>:
                    このストラテジーは、<code>connectTypeToStrategy($type, $strategy)</code>メソッドを通じて
                    希望するストラテジーにPHPの複雑な型（クラス名）を接続することによって、
                    すべてのストラテジーを結合することができます。
                    完全なタイプマップを、<code>$type</code> -> <code>$strategy</code> のペアを持つ配列として
                    コンストラクタに与えられます。
                    もし未知の型の追加が必要であれば、第２パラメータで使われるデフォルト・ストラテジーを指定します。
                    このパラメータのデフォルトは、<classname>Zend_Soap_Wsdl_Strategy_DefaultComplexType</classname>です。</para>
                </listitem>
            </itemizedlist>

            <para>
                <code>addComplexType()</code>メソッドは、指定されたPHPクラスの名前で、
                記述された複雑な型ごとに '/definitions/types/xsd:schema/xsd:complexType' 要素を生成します。
            </para>

            <para>
                クラスのプロパティは、プロパティをWSDL記述にインクルードしておくために、記述されたPHP型でdocblock部を持って<emphasis>いなければなりません</emphasis>。
            </para>

            <para>
                <code>addComplexType()</code>は型がWSDL文書の型セクションの範囲内ですでに記述されるかどうか調べます。
            </para>

            <para>
                このメソッドが型定義部で２回以上再帰で呼ばれると、それは重複を防ぎます。
            </para>

            <para>
                詳しくは<ulink url="http://www.w3.org/TR/wsdl#_types"/>をご覧ください。
            </para>

        </sect3>
    </sect2>

    <sect2 id="zend.soap.wsdl.add_documentation">
        <title>addDocumentation()メソッド</title>
        <para>
            <code>addDocumentation($input_node, $documentation)</code>メソッドは、
            オプションの 'wsdl:document' 要素を用いて人間の読める文書を追加します。
        </para>
        <para>
            '/definitions/binding/soap:binding' 要素は、
            バインディングがSOAPプロトコル構成にバインドされることを示すために使われます。
        </para>
        <para>
            詳しくは<ulink url="http://www.w3.org/TR/wsdl#_documentation"/>をご覧ください。
        </para>
    </sect2>

    <sect2 id="zend.soap.wsdl.retrieve">
        <title>確定したWSDL文書を取得</title>
        <para>
            <code>toXML()</code>や<code>toDomDocument()</code>および<code>dump($filename = false)</code>メソッドは、
            WSDL文書をXMLやDOMの構造もしくはファイルとして取得するために使われるかもしれません。
        </para>
    </sect2>

    <sect2 id="zend.soap.wsdl.parser">
        <title>WSDL文書をパース</title>

        <para>
            Zend_Soap_WsdlはSOAPウェブサービス（クライアントとサーバー）をユニットテストおよびコード生成する際に、
            その主要なアプリケーションがあるWSDL文書のためのパーサーも有します。
            下記にどのようにパーサーを使うか例を示します:
        </para>

        <programlisting language="php"><![CDATA[
// WSDLをDOMDocumentに読み込み
$dom = new DOMDocument();
$dom->loadXML($wsdlString);

// パーサ作成
$parser = Zend_Soap_Wsdl_Parser::factory($dom);
$result = $parser->parse();

// ウェブサービス名
echo $result->getName();

// 接続ポートと内部要素
foreach($result->ports AS $port) {
    echo $port->getName();
    foreach($port->bindings AS $binding) {
        echo $binding->getName();

        foreach($binding->operations AS $operation) {
            echo $operation->getName();
            echo $operation->inputMessage->getName();
            echo $operation->outputMessage->getName();
        }
    }
}
// あなたはバインディング、メッセージ、
// 操作および他の要素に直接アクセスすることもできます。
foreach($result->operations AS $operation) {
    // 処理
}
foreach($result->bindings AS $binding {
    // 処理
}
foreach($result->messages AS $message) {
    // 処理
}
foreach($result->services AS $service) {
    // 処理
}
foreach($result->types AS $type) {
    // 処理
}
]]></programlisting>

        <para>
            それぞれの要素および文書を一意に識別する
            <code>getName()</code>および<code>getDocumentation()</code>関数を代理する
            インターフェース<classname>Zend_Soap_Wsdl_Element_Interface</classname>をすべての要素は実装します。
            すべての要素はより詳細な状態を示す public プロパティーを持ち、
            さらに簡単に反復してアクセスできる入れ子の依存関係も有します。
        </para>
    </sect2>

</sect1>