The XML-RPC Binding (binding.xmlrpc) Documentation

The XML-RPC binding for SCA allows SCA components to provide XML-RPC services which can be consumed by other SCA components or non-SCA XML-RPC consumers. The binding also enables SCA components to consume XML-RPC services provided by both SCA and non-SCA XML-RPC servers.

Here is a StockQuoteService which uses the XML-RPC binding.

/**
 * @service
 * @binding.xmlrpc
   */
class StockQuoteService {

    /**
     * @reference
     * @binding.xmlrpc http://localhost/examples/SCA/XmlRpcStockQuote/ExchangeRate.php
     */
    public $exchange_rate;

    /**
     * @param string $ticker (the ticker symbol)
     * @return float (the converted stock quote)
     */
    public function getQuote($ticker)
    {
        $rate     = $this->exchange_rate->getRate('USD');
        $quote   = 1.23;
        return     $rate * $quote;
    }
}

Service Description

The SCA for PHP runtime will automatically generate the interface description required for XML-RPC based on the SCA service annotaitons. Annotations are also used to define complex types using XML schemas, which are handled as Service Data Objects (SDOs).

SCA for PHP supports XML-RPC introspection methods including system.describeMethods.

Exposing Services

SCA components which expose an XML-RPC binding should contain the annotation @binding.xmlrpc. From the previous example;

/**
 * @service
 * @binding.xmlrpc
 */
class StockQuoteService {

     ...

     /**
     * @param string $ticker (the ticker symbol)
     * @return float (the converted stock quote)
     */
    public function getQuote($ticker)
    {
        ...

All public functions defined in an SCA component exposed as an XML-RPC service can be invoked by XML-RPC clients.
Functions exposed by the service use the method name by default.

To expose a different name for the method in the XML-RPC service, the @name annotation can be used. @name can also be used to implement nested namespaces for XML-RPC methods by using the format namespace.methodName in the @name specification. Any valid XML-RPC method name can be specified with @name' for example,

/**
     * @param string $ticker (the ticker symbol)
     * @return float (the converted stock quote)
     * @name stockQuoteFunctions.getQuote
     */
    public function getQuote($ticker)
    {
        ...

Consuming Services From SCA

An SCA component can call XML-RPC service. In our example the $exchange_rate instance variable will be initialized with an XML-RPC proxy to the ExchangeRate component whenever an instance of the StockQuoteService is constructed.

/**
     * @reference
     * @binding.xmlrpc http://localhost/examples/SCA/XmlRpcStockQuote/ExchangeRate.php
     */
    public $exchange_rate;

$exchange_rate can then be used to make calls to the remote XML-RPC service.

$rate     = $this->exchange_rate->getRate('USD');

Consuming Service From PHP

Plain old PHP can make use of the proxies provided by SCA, for example,

<?php
$exchange_rate = SCA::getService('http://localhost/examples/SCA/XmlRpcStockQuote/ExchangeRate.php', 'XmlRpc');
<?>

This simply provides the location of XML-RPC service to be called (in this case and SCA service) and the type of binding to use. Methods on services can then be called on the returned proxy, just as they can in a component.

<?php
$rate   = $exchange_rate->getRate($currency);
?>

XML-RPC services provided by SCA components exposing an XML-RPC binding can also be consumed by non-SCA scripts directly using standard XML-RPC requests without using a proxy. XML-RPC requests should use HTTP-POST with the PHP class as the target URI and /RPC2 as PATH_INFO. Apart from the public methods supported by the SCA component, introspection methods supported by the XML-RPC extension for PHP can also be invoked.

Deployment

Deploying an XML-RPC service is as simple as placing a PHP component under the document root of a web server.

Pre-requisites

If you want to use SCA to consume or produce XML-RPC services then you need PHP 5.1.0 or above, built with the XML-RPC extension for PHP, using --with-xmlrpc. The XML-RPC extension is not enabled by default.