10 Services - Remote procedure calls - 《web2py Reference Manual, 6th Edition (pre-release)》

Remote procedure calls

Remote procedure calls

web2py provides a mechanism to turn any function into a web service. The mechanism described here differs from the mechanism described before because:

The function may take arguments
The function may be defined in a model or a module instead of controller
You may want to specify in detail which RPC method should be supported
It enforces a more strict URL naming convention
It is smarter than the previous methods because it works for a fixed set of protocols. For the same reason it is not as easily extensible.

To use this feature:

First, you must import and initiate a service object.

from gluon.tools import Service
service = Service()

This is already done in the “db.py” model file in the scaffolding application.

Second, you must expose the service handler in the controller:

def call():
    session.forget()
    return service()

This is already done in the “default.py” controller of the scaffolding application. Remove session.forget() if you plan to use session cookies with the services.

Third, you must decorate those functions you want to expose as a service. Here is a list of currently supported decorators:

@service.run
@service.xml
@service.json
@service.rss
@service.csv
@service.xmlrpc
@service.jsonrpc
@service.jsonrpc2
@service.amfrpc3('domain')
@service.soap('FunctionName', returns={'result': type}, args={'param1': type,})

As an example, consider the following decorated function:

@service.run
def concat(a, b):
    return a + b

This function can be defined in a model or in the controller where the call action is defined. This function can now be called remotely in two ways:

http://127.0.0.1:8000/app/default/call/run/concat?a=hello&b=world
http://127.0.0.1:8000/app/default/call/run/concat/hello/world

In both cases the http request returns:

helloworld

If the @service.xml decorator is used, the function can be called via:

http://127.0.0.1:8000/app/default/call/xml/concat?a=hello&b=world
http://127.0.0.1:8000/app/default/call/xml/concat/hello/world

and the output is returned as XML:

<document>
   <result>helloworld</result>
</document>

It can serialize the output of the function even if this is a DAL Rows object. In this case, in fact, it will call as_list() automatically.

If the @service.json decorator is used, the function can be called via:

http://127.0.0.1:8000/app/default/call/json/concat?a=hello&b=world
http://127.0.0.1:8000/app/default/call/json/concat/hello/world

and the output returned as JSON.

If the @service.csv decorator is used, the service handler requires, as the return value, an iterable object of iterable objects, such as a list of lists. Here is an example:

@service.csv
def table1(a, b):
    return [[a, b], [1, 2]]

This service can be called by visiting one of the following URLs:

http://127.0.0.1:8000/app/default/call/csv/table1?a=hello&b=world
http://127.0.0.1:8000/app/default/call/csv/table1/hello/world

and it returns:

hello,world
1,2

The @service.rss decorator expects a return value in the same format as the “generic.rss” view discussed in the previous section.

Multiple decorators are allowed for each function.

So far, everything discussed in this section is simply an alternative to the method described in the previous section. The real power of the service object comes with XMLRPC, JSONRPC and AMFRPC, as discussed below.

XMLRPC

Consider the following code, for example, in the “default.py” controller:

@service.xmlrpc
def add(a, b):
    return a + b
@service.xmlrpc
def div(a, b):
    return a / b

Now in a python shell you can do

>>> from xmlrpclib import ServerProxy
>>> server = ServerProxy(
       'http://127.0.0.1:8000/app/default/call/xmlrpc')
>>> print server.add(3, 4)
7
>>> print server.add('hello', 'world')
'helloworld'
>>> print server.div(12, 4)
3
>>> print server.div(1, 0)
ZeroDivisionError: integer division or modulo by zero

The Python xmlrpclib module provides a client for the XMLRPC protocol. web2py acts as the server.

The client connects to the server via ServerProxy and can remotely call decorated functions in the server. The data (a, b) is passed to the function(s), not via GET/POST variables, but properly encoded in the request body using the XMLPRC protocol, and thus it carries with itself type information (int or string or other). The same is true for the return value(s). Moreover, any exception raised on the server propagates back to the client.

ServerProxy signature

a_server = ServerProxy(location, transport=None, encoding=None, verbose=False, version=None)

The important arguments are:

location is the remote URL for the server. There are examples below.
verbose=True activates useful diagnostics
version sets the jsonrpc version. It is ignored by jsonrpc. Set this to version='2.0' to support jsonrpc2. Because it is ignored by jsonrpc, setting it gains support for both versions. It is not supported by XMLRPC.

XMLRPC Libraries

There are XMLRPC libraries for many programming languages (including C, C++, Java, C#, Ruby, and Perl), and they can interoperate with each other. This is one the best methods to create applications that talk to each other independent of the programming language.

The XMLRPC client can also be implemented inside a web2py action, so that one action can talk to another web2py application (even within the same installation) using XMLRPC. Beware of session deadlocks in this case. If an action calls via XMLRPC a function in the same app, the caller must release the session lock before the call:

session.forget(response)

JSONRPC

In this section we are going to use the same code example as for XMLRPC but we will expose the service using JSONRPC instead:

@service.jsonrpc
@service.jsonrpc2
def add(a, b):
    return a + b
def call():
    return service()

JSONRPC is very similar to XMLRPC but uses JSON instead of XML as data serialization protocol.

Accessing JSONRPC services from web2py

Of course we can call the service from any program in any language but here we will do it in Python. web2py ships with a module “gluon/contrib/simplejsonrpc.py” created by Mariano Reingart. Here is an example of how to use to call the above service:

>>> from gluon.contrib.simplejsonrpc import ServerProxy
>>> URL = "http://127.0.0.1:8000/app/default/call/jsonrpc"
>>> service = ServerProxy(URL, verbose=True)
>>> print service.add(1, 2)

Use “http://127.0.0.1:8000/app/default/call/jsonrpc2“ for jsonrpc2, and create the service object like this:

service = ServerProxy(URL, verbose=True, version='2.0')

JSONRPC and Pyjamas

As an example of application here, we discuss the usage of JSON Remote Procedure Calls with Pyjamas. Pyjamas is a Python port of the Google Web Toolkit (originally written in Java). Pyjamas allows writing a client application in Python. Pyjamas translates this code into JavaScript. web2py serves the JavaScript and communicates with it via AJAX requests originating from the client and triggered by user actions.

Here we describe how to make Pyjamas work with web2py. It does not require any additional libraries other than web2py and Pyjamas.

We are going to build a simple “todo” application with a Pyjamas client (all JavaScript) that talks to the server exclusively via JSONRPC.

First, create a new application called “todo”.

Second, in “models/db.py”, enter the following code:

db=DAL('sqlite://storage.sqlite')
db.define_table('todo', Field('task'))
service = Service()

(Note: Service class is from gluon.tools).

Third, in “controllers/default.py”, enter the following code:

def index():
    redirect(URL('todoApp'))
@service.jsonrpc
def getTasks():
    todos = db(db.todo).select()
    return [(todo.task, todo.id) for todo in todos]
@service.jsonrpc
def addTask(taskFromJson):
    db.todo.insert(task=taskFromJson)
    return getTasks()
@service.jsonrpc
def deleteTask (idFromJson):
    del db.todo[idFromJson]
    return getTasks()
def call():
    session.forget()
    return service()
def todoApp():
    return dict()

The purpose of each function should be obvious.

Fourth, in “views/default/todoApp.html”, enter the following code:

<html>
  <head>
    <meta name="pygwt:module"
     content="{{=URL('static', 'output/TodoApp')}}" />
    <title>
      simple todo application
    </title>
  </head>
  <body bgcolor="white">
    <h1>
      simple todo application
    </h1>
    <i>
      type a new task to insert in db,
      click on existing task to delete it
    </i>
    <script language="javascript"
     src="{{=URL('static', 'output/pygwt.js')}}">
    </script>
  </body>
</html>

This view just executes the Pyjamas code in “static/output/todoapp” - code that we have not yet created.

Fifth, in “static/TodoApp.py” (notice it is TodoApp, not todoApp!), enter the following client code:

from pyjamas.ui.RootPanel import RootPanel
from pyjamas.ui.Label import Label
from pyjamas.ui.VerticalPanel import VerticalPanel
from pyjamas.ui.TextBox import TextBox
import pyjamas.ui.KeyboardListener
from pyjamas.ui.ListBox import ListBox
from pyjamas.ui.HTML import HTML
from pyjamas.JSONService import JSONProxy
class TodoApp:
    def onModuleLoad(self):
        self.remote = DataService()
        panel = VerticalPanel()
        self.todoTextBox = TextBox()
        self.todoTextBox.addKeyboardListener(self)
        self.todoList = ListBox()
        self.todoList.setVisibleItemCount(7)
        self.todoList.setWidth("200px")
        self.todoList.addClickListener(self)
        self.Status = Label("")
        panel.add(Label("Add New Todo:"))
        panel.add(self.todoTextBox)
        panel.add(Label("Click to Remove:"))
        panel.add(self.todoList)
        panel.add(self.Status)
        self.remote.getTasks(self)
        RootPanel().add(panel)
    def onKeyUp(self, sender, keyCode, modifiers):
        pass
    def onKeyDown(self, sender, keyCode, modifiers):
        pass
    def onKeyPress(self, sender, keyCode, modifiers):
        """
        This function handles the onKeyPress event, and will add the
        item in the text box to the list when the user presses the
        enter key. In the future, this method will also handle the
        auto complete feature.
        """
        if keyCode == KeyboardListener.KEY_ENTER and            sender == self.todoTextBox:
            id = self.remote.addTask(sender.getText(), self)
            sender.setText("")
            if id<0:
                RootPanel().add(HTML("Server Error or Invalid Response"))
    def onClick(self, sender):
        id = self.remote.deleteTask(
                sender.getValue(sender.getSelectedIndex()), self)
        if id<0:
            RootPanel().add(
                HTML("Server Error or Invalid Response"))
    def onRemoteResponse(self, response, request_info):
        self.todoList.clear()
        for task in response:
            self.todoList.addItem(task[0])
            self.todoList.setValue(self.todoList.getItemCount()-1, task[1])
    def onRemoteError(self, code, message, request_info):
        self.Status.setText("Server Error or Invalid Response: "                             + "ERROR " + code + " - " + message)
class DataService(JSONProxy):
    def __init__(self):
        JSONProxy.__init__(self, "../../default/call/jsonrpc",
                           ["getTasks", "addTask", "deleteTask"])
if __name__ == '__main__':
    app = TodoApp()
    app.onModuleLoad()

Sixth, run Pyjamas before serving the application:

cd /path/to/todo/static/
python /python/pyjamas-0.5p1/bin/pyjsbuild TodoApp.py

This will translate the Python code into JavaScript so that it can be executed in the browser.

To access this application, visit the URL:

http://127.0.0.1:8000/todo/default/todoApp

This subsection was created by Chris Prinos with help from Luke Kenneth Casson Leighton (creators of Pyjamas), updated by Alexei Vinidiktov. It has been tested with Pyjamas 0.5p1. The example was inspired by this Django page in ref.[blogspot1].

AMFRPC

AMFRPC is the Remote Procedure Call protocol used by Flash clients to communicate with a server. web2py supports AMFRPC, but it requires that you run web2py from source and that you preinstall the PyAMF library. This can be installed from the Linux or Windows shell by typing:

easy_install pyamf

(please consult the PyAMF documentation for more details).

In this subsection we assume that you are already familiar with ActionScript programming.

We will create a simple service that takes two numerical values, adds them together, and returns the sum. We will call our web2py application “pyamf_test”, and we will call the service addNumbers.

First, using Adobe Flash (any version starting from MX 2004), create the Flash client application by starting with a new Flash FLA file. In the first frame of the file, add these lines:

import mx.remoting.Service;
import mx.rpc.RelayResponder;
import mx.rpc.FaultEvent;
import mx.rpc.ResultEvent;
import mx.remoting.PendingCall;
var val1 = 23;
var val2 = 86;
service = new Service(
    "http://127.0.0.1:8000/pyamf_test/default/call/amfrpc3",
    null, "mydomain", null, null);
var pc:PendingCall = service.addNumbers(val1, val2);
pc.responder = new RelayResponder(this, "onResult", "onFault");
function onResult(re:ResultEvent):Void {
    trace("Result : " + re.result);
    txt_result.text = re.result;
}
function onFault(fault:FaultEvent):Void {
    trace("Fault: " + fault.fault.faultstring);
}
stop();

This code allows the Flash client to connect to a service that corresponds to a function called “addNumbers” in the file “/pyamf_test/default/gateway”. You must also import ActionScript version 2 MX remoting classes to enable Remoting in Flash. Add the path to these classes to the classpath settings in the Adobe Flash IDE, or just place the “mx” folder next to the newly created file.

Notice the arguments of the Service constructor. The first argument is the URL corresponding to the service that we want will create. The third argument is the domain of the service. We choose to call this domain “mydomain”.

Second, create a dynamic text field called “txt_result” and place it on the stage.

Third, you need to set up a web2py gateway that can communicate with the Flash client defined above.

Proceed by creating a new web2py app called pyamf_test that will host the new service and the AMF gateway for the flash client. Edit the “default.py” controller and make sure it contains

@service.amfrpc3('mydomain')
def addNumbers(val1, val2):
    return val1 + val2
def call(): return service()

Fourth, compile and export/publish the SWF flash client as pyamf_test.swf, place the “pyamf_test.amf”, “pyamf_test.html”, “AC_RunActiveContent.js”, and “crossdomain.xml” files in the “static” folder of the newly created appliance that is hosting the gateway, “pyamf_test”.

You can now test the client by visiting:

http://127.0.0.1:8000/pyamf_test/static/pyamf_test.html

The gateway is called in the background when the client connects to addNumbers.

If you are using AMF0 instead of AMF3 you can also use the decorator:

@service.amfrpc

instead of:

@service.amfrpc3('mydomain')

In this case you also need to change the service URL to:

http://127.0.0.1:8000/pyamf_test/default/call/amfrpc

SOAP

web2py includes a SOAP client and server created by Mariano Reingart. It can be used very much like XML-RPC:

Consider the following code, for example, in the “default.py” controller:

@service.soap('MyAdd', returns={'result':int}, args={'a':int, 'b':int, })
def add(a, b):
    return a + b

Now in a python shell you can do:

>>> from gluon.contrib.pysimplesoap.client import SoapClient
>>> client = SoapClient(wsdl="http://localhost:8000/app/default/call/soap?WSDL")
>>> print client.MyAdd(a=1, b=2)
{'result': 3}

To get proper encoding when returning a text values, specify string as u’proper utf8 text’.

You can obtain the WSDL for the service at

http://127.0.0.1:8000/app/default/call/soap?WSDL

And you can obtain documentation for any of the exposed methods:

http://127.0.0.1:8000/app/default/call/soap