Covering all recent additionals in the Zend_XmlRpc component in the documentation, adding sections about performance optimization and the recommended structure of webservice endpoints

git-svn-id: http://framework.zend.com/svn/framework/standard/trunk@19604 44c647ce-9c0f-0410-b52a-842ac1e357ba

documentation/manual/en/module_specs/Zend_XmlRpc_Client.xml

@@ -381,9 +381,9 @@ $result = $client->call('foo.bar', array(array()));
             <programlisting language="php"><![CDATA[
 $client = new Zend_XmlRpc_Client('http://framework.zend.com/xmlrpc');
 
-$server = $client->getProxy();           // Proxy the default namespace
+$service = $client->getProxy();           // Proxy the default namespace
 
-$hello = $server->test->sayHello(1, 2);  // test.Hello(1, 2) returns "hello"
+$hello = $service->test->sayHello(1, 2);  // test.Hello(1, 2) returns "hello"
 ]]></programlisting>
         </example>
 
@@ -561,8 +561,8 @@ $request->setParams(array('foo', 'bar'));
 
 $client->doRequest($request);
 
-// $server->getLastRequest() returns instanceof Zend_XmlRpc_Request
-// $server->getLastResponse() returns instanceof Zend_XmlRpc_Response
+// $client->getLastRequest() returns instanceof Zend_XmlRpc_Request
+// $client->getLastResponse() returns instanceof Zend_XmlRpc_Response
 ]]></programlisting>
         </example>
 

documentation/manual/en/module_specs/Zend_XmlRpc_Server.xml

@@ -62,6 +62,57 @@ echo $server->handle();
         </para>
     </sect2>
 
+    <sect2 id="zend.xmlrpc.server.anatomy">
+        <title>Anatomy of a webservice</title>
+
+        <sect3 id="zend.xmlrpc.server.anatomy.general">
+
+            <title>General considerations</title>
+
+            <para>
+                For maximum performance it is recommended to use a simple
+                bootstrap file for the server component. Using
+                <classname>Zend_XmlRpc_Server</classname> inside a
+                <link linkend="zend.controller"><classname>Zend_Controller</classname></link>
+                is strongly discouraged to avoid the overhead.
+            </para>
+
+            <para>
+                Services change over time and while webservices are generally
+                less change intense as code-native <acronym>APIs</acronym>, it
+                is recommended to version your service. Do so to lay grounds to
+                provide compatibility for clients using older versions of your
+                service and manage your service lifecycle including deprecation
+                timeframes.To do so just include a version number into your
+                <acronym>URI</acronym>. It is also recommended to include the
+                remote protocol name in the <acronym>URI</acronym> to allow easy
+                integration of upcoming remoting technologies.
+                http://myservice.ws/<emphasis>1.0/XMLRPC/</emphasis>.
+            </para>
+        </sect3>
+
+        <sect3 id="zend.xmlrpc.server.anatomy.general">
+
+            <title>What to expose?</title>
+
+            <para>
+                Most of the time it is not sensible to expose business objects
+                directly. Business objects are usually small and under heavy
+                change, because change is cheap in this layer of your
+                application. Once deployed and adopted, web services are hard to
+                change. Another concern is <acronym>I/O</acronym> and latency:
+                the best webservice calls are those not happening. Therefore
+                service calls need to be more coarse-grained than usual business
+                logic is. Often an additional layer in front of your business
+                objects makes sense. This layer is sometimes referred to as
+                <ulink url="http://martinfowler.com/eaaCatalog/remoteFacade.html">Remote Facade.</ulink>.
+                Such a service layer adds a coarse grained interface on top of
+                your business logic and groups verbose operations into smaller
+                ones.
+            </para>
+        </sect3>
+    </sect2>
+
     <sect2 id="zend.xmlrpc.server.conventions">
         <title>Conventions</title>
         <para>
@@ -142,11 +193,11 @@ function myFunc($val1, $val2, $val3)
 }
 ]]></programlisting>
 
-        <para>
-            One note, however: allowing multiple signatures can lead to
-            confusion for developers using the services; generally speaking, an
-            <acronym>XML-RPC</acronym> method should only have a single signature.
-        </para>
+        <note>
+            Allowing multiple signatures can lead to confusion for developers
+            using the services; to keep things simple, a <acronym>XML-RPC</acronym>
+            service method should only have a single signature.
+        </note>
     </sect2>
 
     <sect2 id="zend.xmlrpc.server.namespaces">
@@ -317,7 +368,7 @@ echo $server->handle();
             options available to developers. Usage examples will each build
             on the previous example provided.
         </para>
-        <sect3 id="zend.xmlrpc.server.use.case1">
+        <example id="zend.xmlrpc.server.use.attach-function">
             <title>Basic Usage</title>
 
             <para>
@@ -341,9 +392,9 @@ $server = new Zend_XmlRpc_Server();
 $server->addFunction('md5Value');
 echo $server->handle();
 ]]></programlisting>
-        </sect3>
+        </example>
 
-        <sect3 id="zend.xmlrpc.server.use.case2">
+        <example id="zend.xmlrpc.server.use.attach-class">
             <title>Attaching a class</title>
 
             <para>
@@ -358,9 +409,103 @@ $server = new Zend_XmlRpc_Server();
 $server->setClass('Services_Comb');
 echo $server->handle();
 ]]></programlisting>
-        </sect3>
+        </example>
+
+        <example id="zend.xmlrpc.server.use.attach-class-with-arguments">
+            <title>Attaching a class with arguments</title>
+
+            <para>
+                The following example illustrates how to attach a class' public
+                methods and passing arguments to its methods. This can be used to specify certain
+                defaults when registering service classes.
+            </para>
+            <programlisting language="php"><![CDATA[
+class Services_PricingService
+{
+    /**
+     * Calculate current price of product with $productId
+     *
+     * @param ProductRepository $productRepository
+     * @param PurchaseRepository $purchaseRepository
+     * @param integer $productId
+     */
+    public function calculate(ProductRepository $productRepository,
+                              PurchaseRepository $purchaseRepository,
+                              $productId)
+    {
+        ...
+    }
+}
+
+$server = new Zend_XmlRpc_Server();
+$server->setClass('Services_PricingService', 'pricing', new ProductRepository(), new PurchaseRepository());
+]]></programlisting>
+
+            <para>
+                The arguments passed at <methodname>setClass()</methodname> at server construction time are
+                injected into the method call <command>pricing.calculate()</command> on remote invokation.
+                In the example above, only the argument <code>$purchaseId</code> is expected from the client.
+            </para>
+        </example>
+
+        <example id="zend.xmlrpc.server.use.attach-class-with-arguments-constructor">
+            <title>Passing arguments only to constructor</title>
+
+            <para>
+                <classname>Zend_XmlRpc_Server</classname> allows to restrict argument passing to
+                constructors only. This can be used for constructor dependency injection.
+                To limit injection to constructors, call <methodname>sendArgumentsToAllMethods</methodname>
+                and pass <code>false</code> as an argument. This disables the default behavior of all arguments
+                being injected into the remote method. In the example below the instance of
+                <classname>ProductRepository</classname> and <classname>PurchaseRepository</classname> is only
+                injected into the constructor of <classname>Services_PricingService2</classname>.
+            </para>
+
+            <programlisting language="php"><![CDATA[
+class Services_PricingService2
+{
+    /**
+     * @param ProductRepository $productRepository
+     * @param PurchaseRepository $purchaseRepository
+     */
+    public function __construct(ProductRepository $productRepository,
+                                PurchaseRepository $purchaseRepository)
+    {
+        ...
+    }
+
+    /**
+     * Calculate current price of product with $productId
+     *
+     * @param integer $productId
+     * @return double
+     */
+    public function calculate($productId)
+    {
+        ...
+    }
+}
+
+$server = new Zend_XmlRpc_Server();
+$server->sendArgumentsToAllMethods(false);
+$server->setClass('Services_PricingService2', 'pricing', new ProductRepository(), new PurchaseRepository());
+
+
+]]></programlisting>
+        </example>
+
+        <example id="zend.xmlrpc.server.use.attach-instance">
+            <title>Attaching a class instance</title>
+
+            <para>
+                <methodname>setClass()</methodname> allows to register a previously instantiated
+                object at the server. Just pass an instance instead of the class name. Obviously
+                passing arguments to the constructor is not possible with pre-instantiated
+                objects.
+            </para>
+        </example>
 
-        <sect3 id="zend.xmlrpc.server.use.case3">
+        <example id="zend.xmlrpc.server.use.attach-several-classes-namespaces">
             <title>Attaching several classes using namespaces</title>
 
             <para>
@@ -379,9 +524,9 @@ $server->setClass('Services_Brush', 'brush'); // methods called as brush.*
 $server->setClass('Services_Pick', 'pick');   // methods called as pick.*
 echo $server->handle();
 ]]></programlisting>
-        </sect3>
+        </example>
 
-        <sect3 id="zend.xmlrpc.server.use.case4">
+        <example id="zend.xmlrpc.server.use.exceptions-faults">
             <title>Specifying exceptions to use as valid fault responses</title>
 
             <para>
@@ -404,10 +549,21 @@ $server->setClass('Services_Brush', 'brush'); // methods called as brush.*
 $server->setClass('Services_Pick', 'pick');   // methods called as pick.*
 echo $server->handle();
 ]]></programlisting>
-        </sect3>
+        </example>
+
+        <title>Utilizing custom request and response objects</title>
 
-        <sect3 id="zend.xmlrpc.server.use.case5">
-            <title>Utilizing a custom request object</title>
+        <example id="zend.xmlrpc.server.use.custom-request-object">
+
+            <para>
+                Some use cases require to utilize a custom request object.
+                For example, <acronym>XML/RPC</acronym> is not bound to
+                <acronym>HTTP</acronym> as a transfer protocol. It is possible to use
+                other transfer protocols like <acronym>SSH</acronym> or telnet to send
+                the request and response data over the wire. Another use case is
+                authentication and authorization. In case of a different transfer
+                protocol, one need to change the implementation to read request data.
+            </para>
 
             <para>
                 The example below instantiates a custom request object and
@@ -434,11 +590,9 @@ $request = new Services_Request();
 
 echo $server->handle($request);
 ]]></programlisting>
-        </sect3>
-
-        <sect3 id="zend.xmlrpc.server.use.case6">
-            <title>Utilizing a custom response object</title>
+        </example>
 
+        <example id="zend.xmlrpc.server.use.custom-response-object">
             <para>
                 The example below illustrates specifying a custom response class
                 for the returned response.
@@ -468,9 +622,14 @@ $server->setResponseClass('Services_Response');
 
 echo $server->handle($request);
 ]]></programlisting>
-        </sect3>
+        </example>
+     </sect2>
+
+     <sect2 id="zend.xmlrpc.server.performance">
+
+         <title>Performance optimization</title>
 
-        <sect3 id="zend.xmlrpc.server.use.case7">
+        <example id="zend.xmlrpc.server.performance.caching">
             <title>Cache server definitions between requests</title>
 
             <para>
@@ -505,7 +664,58 @@ $server->setResponseClass('Services_Response');
 
 echo $server->handle($request);
 ]]></programlisting>
-        </sect3>
+            <note>
+                The server cache file should be located outside the document root.
+            </note>
+        </example>
+
+        <example id="zend.xmlrpc.server.performance.xmlgen">
+
+            <title>Optimizing XML generation</title>
+
+            <para>
+                <classname>Zend_XmlRpc_Server</classname> uses
+                <classname>DOMDocument</classname> of <acronym>PHP</acronym>
+                extension <code>ext/dom</code> to generate it's
+                <acronym>XML</acronym> output. While <code>ext/dom</code> is
+                available on a lot of hosts it is is not exactly the fastest.
+                Benchmarks have shown, that <classname>XMLWriter</classname>
+                from <code>ext/xmlwriter</code> performs better.
+            </para>
+
+            <para>
+                If <code>ext/xmlwriter</code> is available on your host, you can
+                select a the <classname>XMLWriter</classname>-based generator
+                to leaverage the performance differences.
+            </para>
+
+            <programlisting language="php"><![CDATA[
+<?php
+require_once 'Zend/XmlRpc/Server.php';
+require_once 'Zend/XmlRpc/Generator/XMLWriter.php';
+
+Zend_XmlRpc_Value::setGenerator(new Zend_XmlRpc_Generator_XMLWriter());
+
+$server = new Zend_XmlRpc_Server();
+...
+]]></programlisting>
+
+            <note>
+                Performance is determined by a lot of parameters and
+                benchmarks only apply for the specific test case. Differences
+                come from PHP version, installed extensions, webserver and
+                operating system just to name a few. Please make sure to
+                benchmark your application on your own and decide which
+                generator to use based on <emphasis>your</emphasis> numbers.
+            </note>
+
+            <note>
+                This optimization makes sense for the client side too. Just
+                select the alternate <acronym>XML</acronym> generator before
+                doing any work with <classname>Zend_XmlRpc_Client</classname>.
+            </note>
+
+        </example>
     </sect2>
 </sect1>
 <!--