JSON is javascript object notation. JSON-RPC performs the same service as XML-RPC, except the transport is javascript objects instead of XML.
This project provides the additional functionality of listening and responding properly to requests of type "application/json-rpc".
This package will work with Zope 3 version 3.3 or greater. The svn version of jsonserver tries hard to keep up with Zope 3's development version available at svn://svn.zope.org/repos/main/Zope3/trunk.
jsolait from http://jsolait.net is the recommended client-side javascript library. Installation of jsolait is covered in the README.txt file in this package's jsolait folder.
Install this package in a location accessible to your zope3 instance. The lib/python folder of the instance is a good choice.
The files in the etc folder should go into etc/package-includes.
A README.txt file in the jsolait folder has instructions for installing a client javascript library.
Similar to xmlrpc usage.
jsonserver looks for content-type "application/json-rpc", and handles those requests as JSON-RPC. Other http requests are not affected and will presumably work as expected. Now that there is an official mime-type for JSON, jsonserver also supports "application/json". "application/json-rpc" may be considered deprecated.
jsonrpc provides another namespace,
http://namespaces.zope.org/jsonrpc for zcml configuration.
Statements like
<jsonrpc:view for="" permission="" methods="" class="" />
are used in zcml to make jsonrpc methods viewable.
You may create views that appear only if a jsonrpc listener is installed:
<configure zcml:condition="have jsonrpc">
<jsonrpc:view
for="someInterface"
permission="zope.View"
methods="blah blecht"
class=".views.JsonViewClass"
/>
</configure>
To make a view class, subclass zif.jsonserver.jsonrpc.MethodPublisher like this:
from zif.jsonserver import MethodPublisher
class MyClass(MethodPublisher):
def myOutput(self):
blah = 'something cool'
return blah
def myOutput1(self,param1):
blecht = self.context.something(param1)
return blecht
where the return value can be a python simple object (int, long, float, string, etc.) or list or dictionary composed of simple objects, lists, and/or dictionaries. Composite built-ins like complex numbers, dates, or classes are not currently supported. Decompose those, and send a list or dictionary instead. Multiple returned values will be marshalled into a list.
For web pages, you will need to include a javascript library for the client side in your page template:
<script type="text/javascript" src="/++resource++jsolait/jsolait.js"></script>
will bring in the recommended jsolait library, if it is installed here. The following javascript examples are for jsolait, but any similar javascript library may be used, or you can write your own. The xmlHTTPRequest POST must set a content-type of "application/json-rpc" for this package to invoke json-rpc requests on the server.
From your client javascript code, import the jsonrpc module:
var jsonrpc = imprt('jsonrpc');
Then, make a jsolait connection proxy ("." often works fine for addr):
addr="address to server object providing jsonrpc view class";
//for better error handling, see http://jsolait.net/wiki/documentation
try{var aServer = new jsonrpc.ServiceProxy(addr, ["myOutput"]);
}catch(e){alert(e);}
then, for async communication, provide a callback function:
function doThis(resp,err){
if (!err) {do something with resp} else {do something with err}
}
and call the method:
aServer.myOutput(aparam,doThis);
If you want sync communication, call the method without the name of a function as the last parameter.
For communication other than in a web browser (javascript), minjson.py or other json implementations have functions for reading and writing JSON objects.
The text of a JSON-RPC request (v1.0) looks like:
{"id":jsonid,"method":remotemethod,"params":methodparams}
where
The text of a JSON-RPC response looks like:
{"id":jsonid,"result":returnedresult,"error":returnederr}
where
Either returnedresult or returnederr will be the javascript null value.
Actual implementation using e.g., urllib is left as an exercise for the reader. Hint: Use the minjson.write(object) and minjson.read(string) methods for conversion before and after transport.
JSON-RPC in Dojo should work out-of-the-box with jsonserver, since it provides a content-type supported by jsonserver. A preliminary package that serves a per-object ".smd" file is available at dojosupport.
Dojo is available at http://dojotoolkit.org .
JSON Views accessible to HTTP GET are also provided with zif.jsonserver. See JSONViews .
jsonserver will work with page templates and similar snippets of HTML. Most registered views (browser:page or similar) are also accessible to json-rpc clients. The simplest way to use a page template is to call it in javascript just as you would call a jsonrpc:view. jsonserver sets a request variable, JSONRPC_MODE, which will be True if a template is requested through json-rpc. This may be useful if you need json-rpc-specific behavior.
If you need form data, jsonserver has a special facility for this. The contents of any client object (dict) passed as a parameter to json-rpc that is (cleverly) named "pythonKwMaRkEr" will be available in the request as items in request.form. If you call methods with named parameters, those items also will replace the named parameters as appropriate.
A pythonkw module is provided here for use with jsolait on the client side. Code like
var pythonkw = imprt("pythonkw");
var kwparams = new pythonkw.PythonKw({'parm1': 'aaa', 'parm2': text_value})
var result = aServer.my_portlet(kwparams);
will do the marshalling so you do not have to type "pythonKwMaRkEr".
Here is an example of using a page template through a jsonrpc:view method ( ViewPageTemplateFile is in zope.app.pagetemplate)
def my_portlet(self,parm1='bbb',parm2=None):
date = datetime.now()
rand = random.randint(0,2000)
portlet = ViewPageTemplateFile("my_portlet.pt")
return portlet(self,date=date,random=rand,parm1=parm1)
In the above example, parm1 is available to the template as options/parm1 and as request/form/parm1. parm2 may be available to the template as request/form/parm2 if provided in the request.
To get verbose output of requests, responses, and errors, set level DEBUG for your event log in etc/zope.conf for your instance. e.g.,
<eventlog>
level DEBUG
<logfile>
path $LOGDIR/z3.log
</logfile>
<logfile>
path STDOUT
</logfile>
</eventlog>
You can get pretty much the same results with tcpwatch, except you get the entire request and response with tcpwatch.
Most compatibility issues should be about client implementations.
jsonserver will accept any valid JSON-RPC request that is a POST with content-type "application/json-rpc" or "application/json". Output responses will be of content-type "application/x-javascript" so that browser clients can know that the response will be interpreted in javascript.
jsolait should work on any current browser with enabled javascript and a functioning xmlHTTPRequest POST implementation. This includes most gecko browsers (Firefox, Mozilla, and Netscape 6.1+), khtml browsers (Safari and konqueror), recent IEs, and Opera 8.1+. If it will do Google maps, it probably will do jsolait.
jsonserver supports unicode properly now, I think, (maybe?). If you have a project that depends on unicode, let me know if this does anything unexpected.