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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 24249 -->
<sect1 id="zend.soap.server">
    <title>Zend_Soap_Server(日本語)</title>

    <para>
        <classname>Zend_Soap_Server</classname>クラスは、
        ウェブ・サービス部分の開発を<acronym>PHP</acronym>プログラマーにとって簡単にすることを目的としています。
    </para>

    <para>
        それは、ウェブサービス<acronym>API</acronym>を定義するクラスまたは機能を使って、
        WSDLモードまたは非WSDLモードで使われるかもしれません。
    </para>

    <para>
        <classname>Zend_Soap_Server</classname>コンポーネントがWSDLモードで動くとき、
        サーバオブジェクトの挙動とトランスポート層オプションを定義する
        すでに用意されたWSDLドキュメントを使います。
    </para>

    <para>
        WSDLドキュメントは
        <link linkend="zend.soap.autodiscovery.introduction">Zend_Soap_AutoDiscoveryコンポーネント</link>
        によって提供される機能によって自動的に生成されるか、
        または、<link linkend="zend.soap.wsdl"><classname>Zend_Soap_Wsdl</classname>クラス</link>や、
        その他の<acronym>XML</acronym>生成ツールを使って、
        手動で構成されます。
    </para>

    <para>
        非WSDLモードが使われるならば、
        すべてのプロトコル・オプションはオプション・メカニズムを用いて設定されなければなりません。
    </para>

    <sect2 id="zend.soap.server.constructor">
        <title>Zend_Soap_Serverコンストラクタ</title>
        <para>
            <classname>Zend_Soap_Server</classname>コンストラクタは、
            WSDLモードと非WSDLモードとでは少し使い方が違います。
        </para>

        <sect3 id="zend.soap.server.constructor.wsdl_mode">
            <title>WSDLモードのためのZend_Soap_Serverコンストラクタ</title>
            <para>
                WSDLモードで動作する場合、<classname>Zend_Soap_Server</classname>コンストラクタは２つの引数を受け取ります:
                <orderedlist>
                    <listitem>
                        <para>
                            <code>$wsdl</code> WSDLファイルの<acronym>URI</acronym>
                            <footnote>
                                <para>
                                    あとで<methodname>setWsdl($wsdl)</methodname>メソッドを使って
                                    設定されるかもしれません。
                                </para>
                            </footnote>
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            <code>$options</code> - <acronym>SOAP</acronym>サーバオブジェクトを作成するためのオプション
                            <footnote>
                                <para>
                                    オプションは後で<methodname>setOptions($options)</methodname>を使って
                                    設定されるかもしれません。
                                </para>
                            </footnote>
                        </para>
                        <para>
                            WSDLモードでは下記のオプションが許されています:
                            <itemizedlist>
                                <listitem>
                                    <para>
                                        'soap_version' ('soapVersion') - 使用する<acronym>SOAP</acronym>バージョン (SOAP_1_1 または SOAP_1_2)
                                    </para>
                                </listitem>
                                <listitem>
                                    <para>
                                        'actor' - サーバのためのアクター<acronym>URI</acronym>。
                                    </para>
                                </listitem>
                                <listitem>
                                    <para>
                                        'classmap' ('classMap') -
                                        一部の WSDL 型を<acronym>PHP</acronym>クラスにマップするために使います。
                                    </para>
                                    <para>
                                        このオプションは、キーとしてWSDL型、値として<acronym>PHP</acronym>クラス名をもつ配列でなければなりません。
                                    </para>
                                </listitem>
                                <listitem>
                                    <para>
                                        'encoding' - 内部文字エンコーディング。 (対外的なエンコーディングとしてUTF-8が常に使われます)
                                    </para>
                                </listitem>
                                <listitem>
                                    <para>
                                        'wsdl' <methodname>setWsdl($wsdlValue)</methodname>呼び出しと同じです。
                                    </para>
                                </listitem>
                            </itemizedlist>
                        </para>
                    </listitem>
                </orderedlist>
            </para>
        </sect3>

        <sect3 id="zend.soap.server.wsdl_mode">
            <title>非WSDLモードのためのZend_Soap_Serverコンストラクタ</title>
            <para>
                非WSDLモードで<classname>Zend_Soap_Server</classname>機能を使うつもりなら、
                最初のコンストラクタ・パラメータは<constant>NULL</constant>に設定し<emphasis>なければなりません</emphasis>。
            </para>
            <para>
                この場合、'uri' オプションを設定しなければなりません。（下記参照）
            </para>

            <para>
                ２番目のコンストラクタ・パラメータ (<code>$options</code>) は、
                <acronym>SOAP</acronym>サーバオブジェクトを作成するためのオプション配列です
                <footnote>
                    <para>
                        オプションは後で<methodname>setOptions($options)</methodname>メソッドを使って
                        設定されるかもしれません。
                    </para>
                </footnote>
            </para>
            <para>
                非WSDLモードでは下記のオプションが許されています:
                <itemizedlist>
                    <listitem>
                        <para>
                            'soap_version' ('soapVersion') - 使用する<acronym>SOAP</acronym>バージョン (SOAP_1_1 または SOAP_1_2)
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            'actor' - サーバのためのアクター<acronym>URI</acronym>。
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            'classmap' ('classMap') -
                            一部の WSDL 型を<acronym>PHP</acronym>クラスにマップするために使います。
                        </para>
                        <para>
                            このオプションは、キーとしてWSDL型、値として<acronym>PHP</acronym>クラス名をもつ配列でなければなりません。
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            'encoding' - 内部文字エンコーディング。 (対外的なエンコーディングとしてUTF-8が常に使われます)
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            'uri' (必須) - <acronym>SOAP</acronym>サーバのための<acronym>URI</acronym>ネームスペース
                        </para>
                    </listitem>
                </itemizedlist>
            </para>
        </sect3>
    </sect2>

    <sect2 id="zend.soap.server.api_define_methods">
        <title>ウェブ・サービスAPIを定義するメソッド</title>

        <para>
            <acronym>SOAP</acronym>を通して<acronym>PHP</acronym>コードにアクセスすることを許可したいときに、
            ウェブサービス<acronym>API</acronym>を定義する2つの方法があります。
        </para>

        <para>
            最初の一つは、ウェブサービス<acronym>API</acronym>を完全に記述しなければならない<classname>Zend_Soap_Server</classname>オブジェクトに対して、
            いくつかのクラスを付与することです:
        </para>

        <programlisting language="php"><![CDATA[
...
class MyClass {
    /**
     * このメソッドは ...
     *
     * @param integer $inputParam
     * @return string
     */
    public function method1($inputParam) {
        ...
    }

    /**
     * このメソッドは ...
     *
     * @param integer $inputParam1
     * @param string  $inputParam2
     * @return float
     */
    public function method2($inputParam1, $inputParam2) {
        ...
    }

    ...
}
...
$server = new Zend_Soap_Server(null, $options);
// クラスをSOAPサーバにバインド
$server->setClass('MyClass');
// 初期化済みのオブジェクトをSOAPサーバにバインド
$server->setObject(new MyClass());
...
$server->handle();
]]></programlisting>

        <note>
            <title>重要</title>

            <para>
                対応するウェブサービスWSDLを準備するautodiscover機能を使うつもりならば、
                メソッドdocblockを使って各々のメソッドを完全に記述しなければなりません。
            </para>
        </note>

        <para>
            ウェブサービス<acronym>API</acronym>を定義する２つ目の方法は、
            関数のセットや<methodname>addFunction()</methodname>または<methodname>loadFunctions()</methodname>メソッドを使うことです:
        </para>

        <programlisting language="php"><![CDATA[
...
/**
 * この関数は...
 *
 * @param integer $inputParam
 * @return string
 */
function function1($inputParam) {
    ...
}

/**
 * この関数は...
 *
 * @param integer $inputParam1
 * @param string  $inputParam2
 * @return float
 */
function function2($inputParam1, $inputParam2) {
    ...
}
...
$server = new Zend_Soap_Server(null, $options);
$server->addFunction('function1');
$server->addFunction('function2');
...
$server->handle();
]]></programlisting>
    </sect2>

    <sect2 id="zend.soap.server.request_response">
        <title>リクエストおよびレスポンスオブジェクトの操作</title>
        <note>
            <title>高度な利用</title>
            <para>
                このセクションではリクエスト/レスポンス処理の高度なオプションを説明します。
                スキップされるかもしれません。
            </para>
        </note>

        <para>
            <classname>Zend_Soap_Server</classname>コンポーネントは自動的にリクエスト/レスポンス処理を実行します。
            しかし、その処理を捕まえて何らかの事前もしくは事後の処理をさせることもできます。
        </para>

        <sect3 id="zend.soap.server.request_response.request">
            <title>リクエスト処理</title>

            <para>
                <methodname>Zend_Soap_Server::handle()</methodname>メソッドは、
                標準的な入力ストリーム ('php://input') からリクエストを取得します。
                それは、<methodname>handle()</methodname>メソッドにオプションのパラメータを供給することによって、
                または、<methodname>setRequest()</methodname>メソッドを用いてリクエストを設定することによって
                上書きされるかもしれません:
            </para>

            <programlisting language="php"><![CDATA[
...
$server = new Zend_Soap_Server(...);
...
// オプションの $request パラメータを使ってリクエストを設定
$server->handle($request);
...
// setRequest() メソッドを使ってリクエストを設定
$server->setRequest();
$server->handle();
]]></programlisting>

            <para>
                リクエストオブジェクトは以下のどれかを用いて表されるかもしれません:
                <itemizedlist>
                    <listitem>
                        <para>
                            DOMDocument (<acronym>XML</acronym>にキャストされます)
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            DOMNode (
                            所有者のドキュメントは横取りされて<acronym>XML</acronym>にキャストされます)
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            SimpleXMLElement (<acronym>XML</acronym>にキャストされます)
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            stdClass (__toString() が呼び出されて、有効な<acronym>XML</acronym>であることが確かめられます)
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            string (有効な<acronym>XML</acronym>であることが確かめられます)
                        </para>
                    </listitem>
                </itemizedlist>
            </para>

            <para>
                最後に処理されたリクエストは<methodname>getLastRequest()</methodname>メソッドを使って<acronym>XML</acronym>文字列として取得されます:
            </para>

            <programlisting language="php"><![CDATA[
...
$server = new Zend_Soap_Server(...);
...
$server->handle();
$request = $server->getLastRequest();
]]></programlisting>
        </sect3>

        <sect3 id="zend.soap.server.request_response.response">
            <title>レスポンスの事前処理</title>

            <para>
                <methodname>Zend_Soap_Server::handle()</methodname>メソッドは、出力ストリームに生成されたレスポンスを自動的に送ります。
                それは<methodname>setReturnResponse()</methodname>にパラメータとして
                <constant>TRUE</constant>または<constant>FALSE</constant>を与えてブロックできます。
                <footnote>
                    <para>
                        戻るレスポンスフラグの現在の状態は
                        <methodname>setReturnResponse()</methodname> メソッドによりリクエストされます。
                    </para>
                </footnote>
                生成されたレスポンスはこの場合、<methodname>handle()</methodname>メソッドにより戻されます。
            </para>

            <programlisting language="php"><![CDATA[
...
$server = new Zend_Soap_Server(...);
...
// 標準出力に送る代わりに、
//handle() メソッドの返り値としてレスポンスを取得
$server->setReturnResponse(true);
...
$response = $server->handle();
...
]]></programlisting>

            <para>
                ある処理のために、最後のレスポンスを<methodname>getLastResponse()</methodname>メソッドで取得することもできます:
            </para>

            <programlisting language="php"><![CDATA[
...
$server = new Zend_Soap_Server(...);
...
$server->handle();
$response = $server->getLastResponse();
...
]]></programlisting>
        </sect3>
    </sect2>
</sect1>