|
|
@@ -1,5 +1,5 @@
|
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
|
-<!-- EN-Revision: 17409 -->
|
|
|
+<!-- EN-Revision: 20763 -->
|
|
|
<!-- Reviewed: no -->
|
|
|
<sect1 id="zend.xmlrpc.server">
|
|
|
<title>Zend_XmlRpc_Server</title>
|
|
|
@@ -57,6 +57,55 @@ 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.expose">
|
|
|
+ <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>
|
|
|
|
|
|
@@ -130,11 +179,13 @@ function myFunc($val1, $val2, $val3)
|
|
|
{}
|
|
|
]]></programlisting>
|
|
|
|
|
|
- <para>
|
|
|
- Attention toutefois, une signature multiple peut prêter à confusion au regard des
|
|
|
- personnes utilisant votre service. En général une fonction ne devrait posséder qu'une
|
|
|
- seule signature.
|
|
|
- </para>
|
|
|
+ <note>
|
|
|
+ <para>
|
|
|
+ Attention toutefois, une signature multiple peut prêter à confusion au regard des
|
|
|
+ personnes utilisant votre service. En général une fonction ne devrait posséder qu'une
|
|
|
+ seule signature.
|
|
|
+ </para>
|
|
|
+ </note>
|
|
|
</sect2>
|
|
|
|
|
|
<sect2 id="zend.xmlrpc.server.namespaces">
|
|
|
@@ -309,7 +360,7 @@ echo $server->handle();
|
|
|
serveur XML-RPC.
|
|
|
</para>
|
|
|
|
|
|
- <sect3 id="zend.xmlrpc.server.use.case1">
|
|
|
+ <example id="zend.xmlrpc.server.use.attach-function">
|
|
|
<title>Utilisation basique</title>
|
|
|
|
|
|
<para>L'exemple ci dessous attache une fonction au service XML-RPC.</para>
|
|
|
@@ -330,9 +381,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>Attacher une classe</title>
|
|
|
|
|
|
<para>
|
|
|
@@ -345,9 +396,107 @@ $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>
|
|
|
|
|
|
- <sect3 id="zend.xmlrpc.server.use.case3">
|
|
|
+ <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>
|
|
|
+
|
|
|
+ <example id="zend.xmlrpc.server.use.attach-several-classes-namespaces">
|
|
|
<title>Attacher plusieurs classes grâce aux espaces de noms</title>
|
|
|
|
|
|
<para>
|
|
|
@@ -369,9 +518,9 @@ $server->setClass('Services_Pick', 'pick');
|
|
|
// méthodes appelées sous la forme pick.*
|
|
|
echo $server->handle();
|
|
|
]]></programlisting>
|
|
|
- </sect3>
|
|
|
+ </example>
|
|
|
|
|
|
- <sect3 id="zend.xmlrpc.server.use.case4">
|
|
|
+ <example id="zend.xmlrpc.server.use.exceptions-faults">
|
|
|
<title>Spécifier les exceptions à utiliser en cas d'erreurs dans les réponses
|
|
|
XML-RPC</title>
|
|
|
|
|
|
@@ -398,11 +547,21 @@ $server->setClass('Services_Pick', 'pick');
|
|
|
// méthodes appelées sous la forme pick.*
|
|
|
echo $server->handle();
|
|
|
]]></programlisting>
|
|
|
- </sect3>
|
|
|
+ </example>
|
|
|
|
|
|
- <sect3 id="zend.xmlrpc.server.use.case5">
|
|
|
+ <example id="zend.xmlrpc.server.use.custom-request-object">
|
|
|
<title>Utiliser un objet de requête personnalisé</title>
|
|
|
|
|
|
+ <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>
|
|
|
L'exemple suivant montre comment utiliser un objet de requête
|
|
|
personnalisé.
|
|
|
@@ -431,9 +590,9 @@ $request = new Services_Request();
|
|
|
|
|
|
echo $server->handle($request);
|
|
|
]]></programlisting>
|
|
|
- </sect3>
|
|
|
+ </example>
|
|
|
|
|
|
- <sect3 id="zend.xmlrpc.server.use.case6">
|
|
|
+ <example id="zend.xmlrpc.server.use.custom-response-object">
|
|
|
<title>Utiliser un objet de réponse personnalisé</title>
|
|
|
|
|
|
<para>
|
|
|
@@ -468,9 +627,13 @@ $server->setResponseClass('Services_Response');
|
|
|
|
|
|
echo $server->handle($request);
|
|
|
]]></programlisting>
|
|
|
- </sect3>
|
|
|
+ </example>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2 id="zend.xmlrpc.server.performance">
|
|
|
+ <title>Optimisation des performances</title>
|
|
|
|
|
|
- <sect3 id="zend.xmlrpc.server.use.case7">
|
|
|
+ <example id="zend.xmlrpc.server.performance.caching">
|
|
|
<title>Cache entre les requêtes</title>
|
|
|
|
|
|
<para>
|
|
|
@@ -515,6 +678,66 @@ $server->setResponseClass('Services_Response');
|
|
|
|
|
|
echo $server->handle($request);
|
|
|
]]></programlisting>
|
|
|
- </sect3>
|
|
|
+ </example>
|
|
|
+
|
|
|
+ <note>
|
|
|
+ <para>
|
|
|
+ The server cache file should be located outside the document root.
|
|
|
+ </para>
|
|
|
+ </note>
|
|
|
+
|
|
|
+ <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[
|
|
|
+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>
|
|
|
+ </example>
|
|
|
+
|
|
|
+ <note>
|
|
|
+ <title>Benchmark your application</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ 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.
|
|
|
+ </para>
|
|
|
+ </note>
|
|
|
+
|
|
|
+ <note>
|
|
|
+ <title>Benchmark your client</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ 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>.
|
|
|
+ </para>
|
|
|
+ </note>
|
|
|
</sect2>
|
|
|
</sect1>
|
mikaelkael