##############################################################################
#
# Copyright (c) 2005 Balazs Ree <ree@ree.hu>
# 		and Jim Washington jwashin@vt.edu and Contributors
# All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE.
#
##############################################################################
jsonserver

Based on:

- jsonserver for zope3 by Jim Washington jwashin@vt.edu and Contributors
- ZPublisher/xmlrpc.py 

JSON is javascript object notation. JSON-RPC performs the same service
as XML-RPC, except the format is javascript script objects instead of
XML, and the content-type is 'application/json-rpc' instead of 'text/xml'.

====================
jsonserver for zope2
====================

This project overrides some base zope2 code to provide the additional
functionality of listening and responding properly to requests of type
"application/json-rpc".

This works with zope2.8 or higher, or zope2.7 with Five installed.

Dependencies:
-------------

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.

jsolait is licensed by the LGPL.

Installation:
-------------

Install this package to the Products path of the zope instance.

A README.txt file in the jsolait folder has instructions for installing
a client javascript library.

Usage:
------

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.

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 it installed here.

Otherwise if you know of a better method for publishing these scripts
from the application root, please let me know.

In client side javascript, make a jsolait connection proxy::

    addr="address to server object providing jsonrpc view class"
    try{var aServer = new jsonrpc.ServiceProxy(addr, ["myOutput"]);
        }catch(e){reportException(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.

You can also pass keyword parameters to a python method, python script
or page template. In this case the last parameter should be the
desired keywords object wrapped into the PythonKw class::

	/* import the module */
	var pythonkw = importModule("pythonkw");

	/* pass the keywords */
	aServer.my_method(new pythonkw.PythonKw({'parm1': 'aaa', 'parm2': 'bbb'}));

	/* ... or */
	aServer.my_method(arg1, arg2, ..., argn, new pythonkw.PythonKw({'parm1': 'aaa', 'parm2': 'bbb'}));
	
	/* ... or in async */
	aServer.my_method(arg1, arg2, ..., argn, new pythonkw.PythonKw({'parm1': 'aaa', 'parm2': 'bbb'}), asyncCallBackFunc);
	
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 looks like::

	{'id':jsonid,''method':remotemethod,'params':methodparams}

where:

    o jsonid is a string or number that may identify this specific request

    o remotemethod is the method to call on the server

    o methodparams is a list(javascript Array) of parameters to the method

The text of a JSON-RPC response looks like::

	{'id':jsonid,''result':returnedresult,'error':returnederr}

where:

    o jsonid is the same jsonid as sent in the request

    o returnedresult is a javascript representation of the result or null

    o returnederr is a javascript representation of an error state

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.

Compatibility:
--------------

jsolait should work on any current browser with enabled javascript and
a functioning xmlHTTPRequest POST implementation.  This includes most
Mozilla (gecko) browsers like Firefox, konqueror (khtml) browsers, like
Safari, and IE 6.0+.

Opera 8.0 also works now but because
their xmlHTTPRequest implementation does not support setting request
headers, we must recognize requests by magic instead of the mime type.

Five extensions
---------------

The "json" namespace (http://namespaces.zope.org/json) defines the
**page** and **pages** directives. **json:page** is identical to
**browser:page** in the usage, but the page or method declared
is allowed to be called up in a json request, but will be
invisible for normal requests.

**browser:page** and **browser:pages** declarations will be
available to both normal and json requests.

**json:page** declarations will be callable from code and
their macros will be visible from other templates.

TODO:
-----

gzip?