zif.jsonserver 0.6

0.6 (2007/05/25)

更新发布说明。

0.5 (2007/05/25)

对设置的纠正。

0.4 (2007/05/25)

将jsolait纳入发布。

0.3 (2007/05/24)

重新打包以确保包含zope 3的zcml文件。

0.2 (2007/04/18)

修正设置配置文件以包含zif命名空间。

0.1 (2007/04/13)

初始发布。

依赖项

本包与Zope 3版本3.3或更高版本兼容。jsonserver的svn版本努力跟上Zope 3的开发版本，该版本可在svn://svn.zope.org/repos/main/Zope3/trunk找到。

jsolait来自http://jsolait.net，是推荐的客户端JavaScript库。jsolait的安装说明包含在本包的jsolait文件夹中的README.txt文件中。

安装

将此软件包安装到可访问您的zope3实例的位置。实例的lib/python文件夹是一个不错的选择。

etc文件夹中的文件应放入etc/package-includes。

jsolait文件夹中的README.txt文件提供了安装客户端JavaScript库的说明。

用法

类似于xmlrpc的使用。

jsonserver查找内容类型“application/json-rpc”，并将这些请求处理为JSON-RPC。其他HTTP请求不受影响，并可能按预期工作。由于JSON有一个官方的MIME类型，jsonserver也支持“application/json”。“application/json-rpc”可能已弃用。

jsonrpc提供了一个名为‘http://namespaces.zope.org/jsonrpc’的另一个命名空间，用于zcml配置。以下语句

<jsonrpc:view for="" permission="" methods="" class="" />

在zcml中使用，以使jsonrpc方法可见。

您可以创建仅在安装了jsonrpc监听器时才出现的视图

<configure zcml:condition="have jsonrpc">
  <jsonrpc:view
      for="someInterface"
      permission="zope.View"
      methods="blah blecht"
      class=".views.JsonViewClass"
      />
</configure>

要创建视图类，可以像这样从zif.jsonserver.jsonrpc.MethodPublisher继承

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

其中返回值可以是Python简单对象（int、long、float、string等）、列表或由简单对象、列表和/或字典组成的字典。目前不支持复合格式内建（如复数、日期或类）。分解这些，然后发送列表或字典。多个返回值将被打包到一个列表中。

对于网页，您需要在您的页面模板中包含客户端的javascript库

<script type="text/javascript" src="/++resource++jsolait/jsolait.js"></script>

如果已安装在此处，则会引入推荐的jsolait库。以下javascript示例是为jsolait设计的，但任何类似的javascript库都可以使用，或者您可以自己编写。对于这个包，xmlHTTPRequest POST必须设置内容类型为“application/json-rpc”，以便在服务器上调用json-rpc请求。

从您的客户端javascript代码中，导入jsonrpc模块

var jsonrpc = imprt('jsonrpc');

然后，创建一个jsolait连接代理（“.”通常工作得很好）

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);}

然后，对于异步通信，提供一个回调函数

function doThis(resp,err){
if (!err) {do something with resp} else {do something with err}
}

并调用该方法

aServer.myOutput(aparam,doThis);

如果您想要同步通信，请在最后一个参数中不指定函数的名称调用方法。

对于除在浏览器（javascript）之外的其他通信，可以使用minjson.py或其他json实现中的函数来读取和写入JSON对象。

JSON-RPC请求（v1.0）的文本如下

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

其中

• jsonid是一个字符串或数字，可以用来标识这个特定的请求

• remotemethod是在服务器上要调用的方法

• methodparams是一个方法参数的列表（javascript Array）

JSON-RPC响应的文本如下

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

其中

• jsonid与请求中发送的jsonid相同

• returnedresult是结果的javascript表示或null

• returnederr是错误状态的javascript表示

返回结果或返回错误将是javascript的null值。

实际的实现，例如使用urllib，留给读者作为练习。提示：使用minjson.write(object)和minjson.read(string)方法在传输前后进行转换。

Dojo

由于Dojo提供了jsonserver支持的内容类型，因此JSON-RPC在Dojo中应该可以正常工作。一个初步的包，用于提供每个对象的“”.smd文件，可在dojosupport找到。

Dojo可在http://dojotoolkit.org找到：http://dojotoolkit.org。

简单的JSON/非POST视图

zif.jsonserver还提供了可通过HTTP GET访问的JSON视图。请参阅“JSONViews”：/jsonviews_README.html。

页面模板、表单变量和命名参数

jsonserver 可以与页面模板以及类似的 HTML 片段一起工作。大多数已注册的视图（浏览器：页面或类似）也可以供 json-rpc 客户端访问。使用页面模板的最简单方法就是在 JavaScript 中调用它，就像调用 jsonrpc:view 一样。jsonserver 设置了一个请求变量，JSONRPC_MODE，如果通过 json-rpc 请求模板，它将是 True。如果你需要特定的 json-rpc 行为，这可能很有用。

如果你需要表单数据，jsonserver 有专门的设施来处理。作为 json-rpc 参数传递给客户端的任何对象（字典）的内容，如果（巧妙地）命名为“pythonKwMaRkEr”，将作为 request.form 中的项在请求中可用。如果你使用命名参数调用方法，这些项也将根据需要替换命名参数。

这里提供了一个 pythonkw 模块，用于与客户端的 jsolait 一起使用。以下代码

var pythonkw = imprt("pythonkw");
var kwparams = new pythonkw.PythonKw({'parm1': 'aaa', 'parm2': text_value})
var result = aServer.my_portlet(kwparams);

将执行序列化，这样你就不必输入“pythonKwMaRkEr”。

以下是通过 jsonrpc:view 方法使用页面模板的示例（ViewPageTemplateFile 在 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)

在上面的示例中，parm1 可以为模板提供 options/parm1 和 request/form/parm1。如果提供在请求中，parm2 可能为模板提供 request/form/parm2。

调试

要获取请求、响应和错误的详细输出，请将 etc/zope.conf 中实例的事件日志级别设置为 DEBUG。例如：

<eventlog>
 level DEBUG
  <logfile>
    path $LOGDIR/z3.log
  </logfile>
  <logfile>
    path STDOUT
  </logfile>
</eventlog>

你可以用 tcpwatch 获取几乎相同的结果，只不过 tcpwatch 会获取完整的请求和响应。

兼容性

大多数兼容性问题应该与客户端实现有关。

jsonserver 将接受任何有效的 JSON-RPC 请求，只要它是带有内容类型“application/json-rpc”或“application/json”的 POST 请求。输出响应将具有内容类型“application/x-javascript”，以便浏览器客户端知道响应将在 JavaScript 中解释。

jsolait 应该可以在任何启用了 JavaScript 和具有 functioning xmlHTTPRequest POST 实现的当前浏览器上运行。这包括大多数 gecko 浏览器（Firefox、Mozilla 和 Netscape 6.1+）、khtml 浏览器（Safari 和 konqueror）、较新的 IEs 和 Opera 8.1+。如果它可以处理 Google 地图，它很可能可以处理 jsolait。

Unicode 支持

我认为 jsonserver 现在正确支持 unicode（也许？）。如果你有一个依赖于 unicode 的项目，请告诉我是否有任何意外的情况。