<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 15743 -->
<sect1 id="zend.soap.server">
    <title>Zend_Soap_Server</title>

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

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

    <para>
        Zend_Soap_Serverコンポーネントが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>や、
        その他のXML生成ツールを使って、
        手動で構成されます。
    </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ファイルのURI
                            <footnote>
                                <para>
                                    あとで<code>setWsdl($wsdl)</code>メソッドを使って
                                    設定されるかもしれません。
                                </para>
                            </footnote>
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            <code>$options</code> - SOAPサーバオブジェクトを作成するためのオプション
                            <footnote>
                                <para>
                                    オプションは後で<code>setOptions($options)</code>を使って
                                    設定されるかもしれません。
                                </para>
                            </footnote>
                        </para>
                        <para>
                            WSDLモードでは下記のオプションが許されています:
                            <itemizedlist>
                                <listitem>
                                    <para>
                                        'soap_version' ('soapVersion') - 使用するSOAPバージョン (SOAP_1_1 または SOAP_1_2)
                                    </para>
                                </listitem>
                                <listitem>
                                    <para>
                                        'actor' - サーバのためのアクターURI。
                                    </para>
                                </listitem>
                                <listitem>
                                    <para>
                                        'classmap' ('classMap') <!-- TODO -->some
                                        WSDL型をPHPクラスにマップするために使われます。
                                    </para>
                                    <para>
                                        このオプションは、キーとしてWSDL型、値としてPHPクラス名をもつ配列でなければなりません。
                                    </para>
                                </listitem>
                                <listitem>
                                    <para>
                                        'encoding' - 内部文字エンコーディング。 (対外的なエンコーディングとしてUTF-8が常に使われます)
                                    </para>
                                </listitem>
                                <listitem>
                                    <para>
                                        'wsdl' <code>setWsdl($wsdlValue)</code>呼び出しと同じです。
                                    </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>) は、
                SOAPサーバオブジェクトを作成するためのオプション配列です
                <footnote>
                    <para>
                        オプションは後で<code>setOptions($options)</code>メソッドを使って
                        設定されるかもしれません。
                    </para>
                </footnote>
            </para>
            <para>
                非WSDLモードでは下記のオプションが許されています:
                <itemizedlist>
                    <listitem>
                        <para>
                            'soap_version' ('soapVersion') - 使用するSOAPバージョン (SOAP_1_1 または SOAP_1_2)
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            'actor' - サーバのためのアクターURI。
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            'classmap' ('classMap') <!-- TODO -->some
                            WSDL型をPHPクラスにマップするために使われます。
                        </para>
                        <para>
                            このオプションは、キーとしてWSDL型、値としてPHPクラス名をもつ配列でなければなりません。
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            'encoding' - 内部文字エンコーディング。 (対外的なエンコーディングとしてUTF-8が常に使われます)
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            'uri' (必須) - SOAPサーバのためのURIネームスペース
                        </para>
                    </listitem>
                </itemizedlist>
            </para>
        </sect3>
    </sect2>

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

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

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

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

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

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

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

            <para>
                <classname>Zend_Soap_Server::handle()</classname>メソッドは、
                標準的な入力ストリーム ('php://input') からリクエストを取得します。
                それは、<code>handle()</code>メソッドにオプションのパラメータを供給することによって、
                または、<code>setRequest()</code>メソッドを用いてリクエストを設定することによって
                上書きされるかもしれません:
                <programlisting language="php"><![CDATA[
...
$server = new Zend_Soap_Server(...);
...
// オプションの $request パラメータを使ってリクエストを設定
$server->handle($request);
...
// setRequest() メソッドを使ってリクエストを設定
$server->setRequest();
$server->handle();
]]></programlisting>
            </para>

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

            <para>
                最後に処理されたリクエストは<code>getLastRequest()</code>メソッドを使ってXML文字列として取得されます:
                <programlisting language="php"><![CDATA[
...
$server = new Zend_Soap_Server(...);
...
$server->handle();
$request = $server->getLastRequest();
]]></programlisting>

            </para>
        </sect3>

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

            <para>
                <classname>Zend_Soap_Server::handle()</classname>メソッドは、出力ストリームに生成されたレスポンスを自動的に送ります。
                それは<code>setReturnResponse()</code>にパラメータとして
                <constant>TRUE</constant>または<constant>FALSE</constant>を与えてブロックできます。
                <footnote>
                    <para>
                        戻るレスポンスフラグの現在の状態は
                        <code>setReturnResponse()</code> methodによりリクエストされます。
                    </para>
                </footnote>
                生成されたレスポンスはこの場合、<code>handle()</code>メソッドにより戻されます。
                <programlisting language="php"><![CDATA[
...
$server = new Zend_Soap_Server(...);
...
// 標準出力に送る代わりに、
//handle() メソッドの返り値としてレスポンスを取得
$server->setReturnResponse(true);
...
$response = $server->handle();
...
]]></programlisting>
            </para>

            <para>
                ある処理のために、最後のレスポンスを<code>getLastResponse()</code>メソッドで取得することもできます:
                <programlisting language="php"><![CDATA[
...
$server = new Zend_Soap_Server(...);
...
$server->handle();
$response = $server->getLastResponse();
...
]]></programlisting>
            </para>
        </sect3>
    </sect2>
</sect1>
