diff options
| -rw-r--r-- | framework/Web/Services/TRpcService.php | 137 |
1 files changed, 125 insertions, 12 deletions
diff --git a/framework/Web/Services/TRpcService.php b/framework/Web/Services/TRpcService.php index 8c8a6835..a2691af4 100644 --- a/framework/Web/Services/TRpcService.php +++ b/framework/Web/Services/TRpcService.php @@ -13,10 +13,41 @@ /** * TRpcService class * - * Usage: - * <service id="rpc" class="TRpcService"> - * <rpcapi id="myapi" Class="MyApi" /> + * The TRpcService class is a generic class that can be extended and used to implement + * rpc services using different servers and protocols. + * + * A server is a {@link TModule} that must subclass {@link TRpcServer}: its role is + * to be an intermediate, moving data between the service and the provider. The base + * {@link TRpcServer} class should suit the most common needs, but can be sublassed for + * logging and debugging purposes, or to filter and modify the request/response on the fly. + * + * A protocol is a {@link TModule} that must subclass {@link TRpcProtocol}: its role is + * to implement the protocol that exposes the rpc api. Prado already implements two + * protocols: {@link TXmlRpcProtocol} for Xml-Rpc request and {@link TJsonRpcProtocol} for + * JSON-Rpc requests. + * + * A provider is a {@link TModule} that must subclass {@link TRpcApiProvider}: its role is + * to implement the methods that are available through the api. Each defined api must be + * a sublass of the abstract class {@link TRpcApiProvider} and implement its methods. + * + * The flow of requests and reponses is the following: + * Request <-> TRpcService <-> TRpcServer <-> TRpcProtocol <-> TRpcApiProvider <-> Response + * + * To define an rpc service, add the proper application configuration: + * + * <code> + * <service id="rpc" class="System.Web.Services.TRpcService"> + * <rpcapi id="customers" class="Application.Api.CustomersApi" /> + * <modules> + * <!-- register any module needed by the service here --> + * </modules> * </service> + * </code> + * + * An api can be registered adding a proper <rpcapi ..> definition inside the service + * configuration. Each api definition must contain an id property and a class name + * expressed in namespace format. When the service receives a request for that api, + * the specified class will be instanciated in order to satisfy the request. * * @author Robin J. Rogge <rrogge@bigpoint.net> * @version $Id$ @@ -96,6 +127,7 @@ class TRpcService extends TService } /** + * Loads the service configuration * @param TXmlElement $xml configuration */ public function loadConfig(TXmlElement $xml) @@ -148,6 +180,14 @@ class TRpcService extends TService /** * TRpcServer class * + * TRpcServer is a class + * + * TRpcServer is the base class used to creare a server to be used in conjunction with + * {@link TRpcService}. + * The role of TRpcServer is to be an intermediate, moving data between the service and + * the provider. This base class should suit the most common needs, but can be sublassed for + * logging and debugging purposes, or to filter and modify the request/response on the fly. + * * @author Robin J. Rogge <rrogge@bigpoint.net> * @version $Id$ * @package System.Web.Services @@ -170,6 +210,7 @@ class TRpcServer extends TModule } /** + * Registers the method in the protocol handler * @param string $methodName * @param array $methodDetails */ @@ -179,6 +220,7 @@ class TRpcServer extends TModule } /** + * Retrieves the request payload * @return string request payload */ public function getPayload() @@ -187,6 +229,7 @@ class TRpcServer extends TModule } /** + * Passes the request payload to the protocol handler and returns the result * @return string rpc response */ public function processRequest() @@ -226,6 +269,32 @@ class TRpcException extends TException /** * TRpcApiProvider class * + * TRpcApiProvider is an abstract class the can be subclasses in order to implement an + * api for a {@link TRpcService}. A subclass of TRpcApiProvider must implement the + * {@link registerMethods} method in order to declare the available methods, their + * names and the associated callback. + * + * <code> + * public function registerMethods() + * { + * return array( + * 'apiMethodName1' => array('method' => array($this, 'objectMethodName1')), + * 'apiMethodName2' => array('method' => array('ClassName', 'staticMethodName')), + * ); + * } + * </code> + * + * In this example, two api method have been defined. The first refers to an object + * method that must be implemented in the same class, the second to a static method + * implemented in a 'ClassName' class. + * In both cases, the method implementation will receive the request parameters as its + * method parameters. Since the number of received parameters depends on + * external-supplied data, it's adviced to use php's func_get_args() funtion to + * validate them. + * + * Providers must be registered in the service configuration in order to be available, + * as explained in {@link TRpcService}'s documentation. + * * @author Robin J. Rogge <rrogge@bigpoint.net> * @version $Id$ * @package System.Web.Services @@ -238,12 +307,15 @@ abstract class TRpcApiProvider extends TModule */ protected $rpcServer; - // abstracts - + /** + * Must return an array of the available methods + * @abstract + */ abstract public function registerMethods(); - // methods - + /** + * Constructor: informs the rpc server of the registered methods + */ public function __construct(TRpcServer $rpcServer) { $this->rpcServer = $rpcServer; @@ -252,13 +324,18 @@ abstract class TRpcApiProvider extends TModule $this->rpcServer->addRpcMethod($_methodName, $_methodDetails); } + /** + * Processes the request using the server + * @return processed request + */ public function processRequest() { return $this->rpcServer->processRequest(); } - // getter/setter - + /** + * @return rpc server instance + */ public function getRpcServer() { return $this->rpcServer; @@ -268,6 +345,10 @@ abstract class TRpcApiProvider extends TModule /** * TRpcProtocol class * + * TRpcProtocol is the base class used to implement a protocol in a {@link TRpcService}. + * Prado already implements two protocols: {@link TXmlRpcProtocol} for Xml-Rpc request + * and {@link TJsonRpcProtocol} for JSON-Rpc requests. + * * @author Robin J. Rogge <rrogge@bigpoint.net> * @version $Id$ * @package System.Web.Services @@ -276,16 +357,45 @@ abstract class TRpcApiProvider extends TModule abstract class TRpcProtocol { /** - * @var array containis the mapping from RPC method names to the actual handlers + * @var array containing the mapping from RPC method names to the actual handlers */ protected $rpcMethods = array(); // abstracts + /** + * @param string request payload + * Processed the request ans returns the response, if any + * @return processed response + * @abstract + */ abstract public function callMethod($requestPayload); + /** + * @param TRpcException the exception with error details + * Creates a proper response for an error condition + * @return a response representing the error + * @abstract + */ abstract public function createErrorResponse(TRpcException $exception); + /** + * @param response + * Sets the needed headers for the response (eg: content-type, charset) + * @abstract + */ abstract public function createResponseHeaders($response); + /** + * Encodes the response + * @param mixed reponse data + * @return string encoded response + * @abstract + */ abstract public function encode($data); + /** + * Decodes the request payload + * @param string request payload + * @return mixed decoded request + * @abstract + */ abstract public function decode($data); // methods @@ -323,7 +433,9 @@ abstract class TRpcProtocol /** * TJsonRpcProtocol class * - * Implements the JSON RPC protocol + * TJsonRpcProtocol is a class that implements JSON-Rpc protocol in {@link TRpcService}. + * Both version 1.0 and 2.0 of the specification are implemented, and the server will try + * to answer using the same version of the protocol used by the requesting client. * * @author Robin J. Rogge <rrogge@bigpoint.net> * @author Fabio Bas <ctrlaltca@gmail.com> @@ -492,7 +604,8 @@ class TJsonRpcProtocol extends TRpcProtocol /** * TXmlRpcProtocol class * - * Implements the XML RPC protocol + * TXmlRpcProtocol is a class that implements XML-Rpc protocol in {@link TRpcService}. + * It's basically a wrapper to the xmlrpc_server_* family of php methods. * * @author Robin J. Rogge <rrogge@bigpoint.net> * @version $Id$ |