The JSON-RPC Binding (binding.jsonrpc) Documentation

The JSON-RPC binding allows SCA Services to be called using the JSONRPC protocol and allows SCA components to call JSON-RPC services.

For example, here is a email service that both exposes and consumes a JSON-RPC service.

/**
 * Service for sending emails
 *
 * @service
 * @binding.jsonrpc
 *
 */
class EmailService {

    /**
     * @reference
     * @binding.jsonrpc http://localhost:80/ContactService.smd
     */
     public $contact_service;

    /**
     * Send a simple text email
     *
     * @param string $to The "to" email address
     * @param string $from The "from" email address
     * @param string $subject The subject of the email
     * @param string $message The email message
     * @return boolean
     */
    public function send($to, $from, $subject, $message) {
        $to_address = $this->contact_service->retrieve($to);
        $from_address = $this->contact_service->retrieve($from);
        return send($to_address, $from_address, $subject, $message);
    }
}

Service Method Description

The JSON-RPC specifications define a mechanism for describing a remote service interface called Service Method Description (SMD). The PHP SCA JSON-RPC binding generates the SMD automatically on request for all of the public methods of a service.

Assuming that our email service (EmailService.php) has been place in the htdoc directory of a web server running on out local machine, sending a GET request to

http://localhost:80/EmailService.php?smd

Will return

{
    "SMDVersion"  : ".1",
    "serviceType" : "JSON-RPC",
    "serviceURL"  : "http://localhost/EmailService.php",
    "methods"     : [
                        {
                            "name"       : "send",
                            "parameters" : [
                                               {
                                                   "name":"to",
                                                   "type":"string
                                               },
                                               {
                                                   "name":"from",
                                                   "type":"string
                                               },
                                               {
                                                   "name":"subject",
                                                   "type":"string
                                               },
                                               {
                                                   "name":"message",
                                                   "type":"string
                                               }
                                           ],
                             "return"    : {
                                               "type" : "boolean"
                                           }
                         }
                     ]
}

The pretty printing has been added manually to make it easier to read. If you try this the SMD will be returned on a single line. The PHP SCA JSON-RPC binding can use this SMD to build a proxy for talking to JSON-RPC services.

If you use SDOs to pass complex types in and out of service functions you will notice that the generated SMD has some extra type information that describes the structure of the SDOs in question. This type information is not a specified feature of SMDs but we added it to experiment with whether it would add valuable. If can be safely ignored if you don't require it.

Exposing Services

An SCA service is easily exposed as a JSON-RPC service simply by adding a binding.jsonrpc comment to the service doc comment block. From the previous example,

/**
 * Service for sending emails
 *
 * @service
 * @binding.jsonrpc
 *
 */
class EmailService {
    ...

    /**
     * Send a simple text email
     *
     * @param string $to The "to" email address
     * @param string $from The "from" email address
     * @param string $subject The subject of the email
     * @param string $message The email message
     * @return boolean
     */
    public function send($to, $from, $subject, $message) {
       ...

All public functions defined in an SCA component exposed as an JSON-RPC service can be invoked by JSON-RPC clients.

Consuming Services From SCA

An SCA component can call JSON-RPC services. In our example the $contact_service instance variable will be initialized with a JSON-RPC proxy to the ContactService service whenever an instance of the EmainService is constructed.

/**
     * @reference
     * @binding.jsonrpc http://localhost:80/ContactService.smd
     */
     public $contact_service;

$contact_service can be used to make calls to the remote JSON-RPC service.

$to_address = $this->contact_service->retrieve($to);

The smd file can be read from the local files system

/**
     * @reference
     * @binding.jsonrpc ./ContactService.smd
     */
     public $contact_service;

XML can be used to describe complex types passing in and out of a JSON-RPC based service.

/**
     * @reference
     * @binding.jsonrpc ./ContactService.smd
     * @types http://www.example.org/contact contact.xsd
     */
     public $contact_service;

This is stepping byond what is descriped by JSON-RPC and SMDs as currently specified. We have added this to allow for the concise description of complex types using XML schema. The way it is implemented for PHP SCA the JSON-RPC binding will match type names that appear in the SMD file.

{
        "name":"to",
        "type":"Address
    }

Would be matched with type from the contact.xsd file.

<schema xmlns="http://www.w3.org/2001/XMLSchema"
        targetNamespace="http://www.example.org/contact"
        xmlns:tns="http://www.example.org/contact">

    <complexType name="Address">
        <sequence>
            <element name="Name" type="string"/>
            <element name="Domain" type="string" />
        </sequence>
    </complexType>

Consuming Service From PHP and Javascript

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

$email_service = SCA::getService('./EmailService.smd');

As an SMD file is provoided SCA works out that a JSON-RPC proxy is required and uses the contents of the SMD file to configure it. Methods on services can then be called on the returned proxy, just as they can in a component.

$email_service->send("Me", "You", "My message", "The content of my message");

Json is a common protocol for Web2.0/AJAX applications so here is an example of how you could invoke this service from a browser based Javascript application.

request = new XMLHttpRequest ();
    request.onreadystatechange = handleResponse;
    request.open ( "POST", "./EmailService.php", true);
    request.setRequestHeader ( "Content-Type",
                               "application/json-rpc; charset=UTF-8");
    request.send("{"id":1,"method":"send","params":["Me","You","My message", "The content of my message"]}");

In a real application the data for this message would of course come from form fields or similar.

Deployment

The service is deployed by dropping in into the document root (htdocs) of your web server and is then available to http clients that can provide JSON formatted messages.

Pre-requisites

If you want to use SCA to expose JSON-RPC services then you need PHP 5.1.0 or above, built with the JSON-RPC extension for PHP enabled, using --enable-json.

To consume JSON-RPC services curl support must also be anabled using --with-curl.

You can find the specification for the JSON formate here (www.json.org) and for the evolving JSON-RPC specifications here (www.json-rpc.org).

Page Operations

Browse Space