在dojo中使用JSON-RPC
1 JSON-RPC规范
JSON-RPC 是一种轻量级远程过程调用协议，类似JAVA的RMI和.NET中的Remoting。在此协议中，通讯双方的请求对象和响应对象使用JSON编码方式，通过前面的“JSON编码简介”可以简单了解其编码规则。
1.1 请求，响应和通知对象
首先客户端向远程服务器发出远程调用请求，该请求对象具有三个属性的：
method –
远程调用的方法名称的字符串。
params –
方法参数数组。
id –
请求
ID
。可以为任何类型，用于将响应与其应答的请求相匹配。
服务端的响应对象也具有三个属性：
result -
被调用方法返回的结果对象。在调用该方法时发生错误时必须为
null
。
error - error
对象。如果在调用方法时设置，没有发生错误时必须为
null
。
id -
它必须是与响应的请求相同的
ID
。
通知是不需要响应的特殊请求类型。通知对象与请求对象基本相同，唯一的一点区别通知的id必须为 null。
1.2 通讯协议
JSON-RPC没有规定具体的传输协议，可以在普通的TCP/IP socket通讯中使用，也可以使用HTTP协议。
在socket通讯中，序列化的请求和响应对象通过字节流的方式在通讯双方传递。请求和响应可以在任意时间发起，除了通知外，通讯双方必须对所有请求对象进行响应。一个响应只能发送到一个请求方。在关闭连接时，所有通讯双方未响应的请求必须抛出异常。无效的请求或响应必须引起连接关闭。
在带有某些限制的情况下，可以使用HTTP协议进行通讯。通讯双方的会话，包括一个HTTP客户端和一个HTTP服务器，可能跨越多个HTTP请求。客户端可以使用一个HTTP POST请求向对方发送一个或多个序列化的请求、通知或响应对象。服务器端必须对请求对象进行响应，也可以发送自己的通知或请求对象。客户端必须使用另一个HTTP POST对接收到的请求对象进行响应。为了实现服务器端向客户端的主动通讯，客户端可以发送空的HTTP POST以重新建立连接。无效请求将导致连接关闭。在客户端，一个无效的响应将对所有没有应答的请求抛出异常，关闭连接也将对所有没有应答的请求抛出异常。
1.3 会话举例
简单的会话举例如下：
调用服务器echo方法，参数Hello JSON-RPC ，id为1
--> { "method": "echo", "params": ["Hello JSON-RPC"], "id": 1}
服务器响应结果为Hello JSON-RPC，对应id为1，没有错误
<-- { "result": "Hello JSON-RPC", "error": null, "id": 1}
带有通知的通讯会话
...
--> {"method": "postMessage", "params": ["Hello all!"], "id": 99}
<-- {"result": 1, "error": null, "id": 99}
<-- {"method": "handleMessage", "params": ["user1", "we were just talking"], "id": null}
<-- {"method": "handleMessage", "params": ["user3", "sorry, gotta go now, ttyl"], "id": null}
--> {"method": "postMessage", "params": ["I have a question:"], "id": 101}
<-- {"method": "userLeft", "params": ["user3"], "id": null}
<-- {"result": 1, "error": null, "id": 101}
...
2 Dojo对JSON-RPC的支持
2.1
dojo.io.blind
介绍
dojo.io包中提供了对XMLHTTP和一些其他更复杂的传输结构的支持。在dojo.io 包中一般最常使用的是dojo.io.bind()方法。dojo.io.blind()是一个标准的异步的请求API，它包含了各种传输层（transport layers），包括Iframe请求、XMLHTTP、mod_pubsub、LivePage等等。Dojo会根据当前的请求选择最合适的传输方法。下面的代码创建了一个请求（request），这个请求会从指定的URL返回字符串，并且指定了一个处理函数。
dojo.io.bind({
url: " http://foo.bar.com/sampleData.txt " ,
load: function (type, data, evt){ /* do something with the data */ },
mimetype: " text/plain "
});
如果在请求过程中出错了怎么办呢？我们可以再指定一个错误处理函数：
dojo.io.bind({
url: "http://foo.bar.com/sampleData.txt",
load: function(type, data, evt){ /*do something with the data */ },
error: function(type, error){ /*do something with the error*/ },
mimetype: "text/plain"
});
同样也可以只创建一个单独的函数，然后在内部根据返回类型来进行不同的处理：
dojo.io.bind({
url: "http://foo.bar.com/sampleData.txt",
handle: function(type, data, evt){
if(type == "load"){
// do something with the data object
}else if(type == "error"){
// here, "data" is our error object
// respond to the error here
}else{
// other types of events might get passed, handle them here
}
},
mimetype: "text/plain"
});
下面的代码提交一段javascript程序段，然后让服务器运行它，一般我们这么做是为了加速程序运行，注意mimetype：
dojo.io.bind({
url: "http://foo.bar.com/sampleData.js",
load: function(type, evaldObj){ /* do something */ },
mimetype: "text/javascript"
});
如果想确保程序使用XMLHTTP，可以指定传输协议类型：
dojo.io.bind({
url: "http://foo.bar.com/sampleData.js",
load: function(type, evaldObj){ /* do something */ },
mimetype: "text/plain", // get plain text, don't eval()
transport: "XMLHTTPTransport"
});
dojo.io.bind()同样支持来自于表单提交的数据。
dojo.io.bind({
url: "http://foo.bar.com/processForm.cgi",
load: function(type, evaldObj){ /* do something */ },
formNode: document.getElementById("formToSubmit")
});
2.2
RPC
Dojo通过dojo.io.bind提供了简单，强大的方法使用多种多样的I/O functions。但是在开发过程中，程序员会调用很多很多I/O，这同时会给服务器和客户端加重负担。Dojo的RPC功能就是为了减少开发负担，使代码更加精简易用而产生的。Dojo不仅提供了基本的RPC client包，而且还扩展了它，使它支持JSON-RPC服务和YAHOO服务。假定有一个需要调用服务器端程序的小程序，假设要调用add(x,y)和subtract(x,y)。在没有特殊情况的条件下，客户端会这样写：
add = function(x,y) {
request = {x: x, y: y};
dojo.io.bind({
url: "add.php",
load: onAddResults,
mimetype: "text/plain",
content: request
});
}
subtract = function(x,y) {
request = {x: x, y: y};
dojo.io.bind({
url: "subract",
load: onSubtractResults,
mimetype: "text/plain"
content: request
});
}
这不是很难。但是这只是一个非常简单的程序。如果要调用在服务器上30个不同method会怎么样呢？开发人员可能要重复的写几乎一样的代码一遍又一遍，每次都要创建一个请求类（request object)，设定URL，设定变量等等。这不仅容易出错，而且还很枯燥。Dojo的RPC客户端简化了这个过程，首先创建一个服务定义文件testService.smd，SMD(Simple Method Description )是远程调用接口的描述文件，可以视为简化的WSDL文件
{
"serviceType": "JSON-RPC",
"serviceURL": "rpcProcessor.php",
"methods":[
{
"name": "add",
"parameters":[
{"name": "x"},
{"name": "y"}
]
},
{
"name": "subtract",
"parameters":[
{"name": "x"},
{"name": "y"}
]
}
]
}
以上就是对于远程对象接口定义。一旦定义创建完毕，要使用服务器的方法则可以首先根据服务接口定义创建远程对象，然后调用相应的方法：
var myObject = new dojo.rpc.JsonService(testService.smd);
myObject.add(3,5);
服务器端的myObject.add()会返回一个延缓类（deferred object）。延缓类允许开发者根据返回数据的类型附加一个或更多的回叫（callbacks）和错误处理（errbacks）。这里有一个简单的例子：
var myDeferred = myObject.add(3,5);
myDeferred.addCallback(contentCallBack);
或者象最后的例子中，在一条语句中完成：
testClass.contentC().addCallbacks(contentCallBack,contentErrBack);
在dojo中，可以随意添加回叫方法（callback），它们会按照定义的顺序被调用。
以上的例子都是基于dojo.rpc.JsonService的。Dojo中还可以使用dojo.rpc.YahooService，规范和结构都是一样的。这两个类都是继承了dojo.rpc.RpcService。
3 具体的例子
该例子从dojo提供的rpc例子中改进而来，修改了一些错误，增加了返回JSON对象的函数。其服务端包括两个PHP脚本，以及JSON的PHP实现。客户端包括两个SMD定义和一个HTML页面。当然还应当有dojo的脚本以及JSON的javascript实现。
3.1
服务端
实际的服务类，其中myecho为简单的回显函数，contentB返回固定的contentB字符串，contentC返回一段JSON编码的对象，在客户端可以使用JSON进行解码以得到一个响应对象。这就演示了如何通过JSON－RPC传送复杂的对象。add实现了简单的加法。
<?php
class testClass {
function myecho ($somestring) {
return $somestring;
}
function contentB () {
return "Content B";
}
function contentC () {
return '{"user":"firefight", "password":"sorry, I can not tell you"}';
}
function add($x,$y) {
return $x + $y;
}
}
?>
服务中介
负责实例化服务类，接收客户端请求，使用JSON反序列化，然后根据请求内容调用正确的服务类方法。在程序中，如果客户端调用的是triggerRpcError，则返回一个带有错误的响应对象，模拟了服务器处理失败的情况。
<?php
require_once("./JSON.php");
// ensure that we don't try to send "html" down to the client
header("Content-Type: text/plain");
$json = new Services_JSON;
//Get request object
$req = $json->decode($HTTP_RAW_POST_DATA);
include("./testClass.php");
$testObject = new testClass();
//Prepare results
$results = array();
$results['error'] = null;
$method = $req->method;
if ($method != "triggerRpcError") {
$ret = call_user_func_array(array($testObject,$method),$req->params);
$results['result'] = $ret;
} else {
$results['error'] = "Triggered RPC Error test";
}
//Set result id
$results['id'] = $req->id;
$encoded = $json->encode($results);
print $encoded;
?>
3.2
客户端
带有一个testClass接口描述的SMD定义。
{
"SMDVersion":".1",
"objectName":"testClass",
"serviceType":"JSON-RPC",
"serviceURL":"test_JsonRPC.php",
"methods":[
{
"name":"myecho",
"parameters":[
{
"name":"somestring",
"type":"STRING"
}
]
},
{
"name":"contentB"
},
{
"name":"contentC"
},
{
"name":"add",
"parameters":[
{
"name":"x",
"type":"STRING"
},
{
"name":"y",
"type":"STRING"
}
]
},
{
"name":"triggerRpcError"
},
]
}
为了测试连接错误的情况，创建一个带有无效URL地址的SMD文件，其中包括对erroringClass的接口描述，当然对erroringClass的远程调用会在连接时就失败。
{
"SMDVersion":".1",
"objectName":"erroringClass",
"serviceType":"JSON-RPC",
"serviceURL":"badUrlForTesting",
"methods":[
{
"name":"content"
},
]
}
客户页面，提供按钮和结果显示。
<script type="text/javascript">
var djConfig = {isDebug: true,debugContainerId: "dojoDebug" };
//djConfig.debugAtAllCosts = true;
</script>
<script type="text/javascript" src="../dojo/dojo.js"></script>
<script type="text/javascript" src="../common/json.js"></script>
<script type="text/javascript">
dojo.require("dojo.debug.Firebug");
dojo.require("dojo.widget.*");
dojo.require("dojo.widget.Button");
dojo.require("dojo.rpc.JsonService");
dojo.require("dojo.rpc.Deferred");
function contentCallBack(result) {
var handlerNode = document.getElementById("ReturnedContent");
handlerNode.innerHTML = "<p>" + result + "</p>" ;
}
function contentErrBack(obj) {
dojo.debug(obj);
var handlerNode = document.getElementById("ReturnedContent");
handlerNode.innerHTML = "<p> Error! Please refer to debug below! </p>" ;
}
function callBackForContentC(result)
{
var r = JSON.parse(result);
var str = "User: " + r.user + "; Password: " + r.password;
var handlerNode = document.getElementById("ReturnedContent");
handlerNode.innerHTML = "<p>" + str + "</p>" ;
}
var testClass = new dojo.rpc.JsonService("testClass.smd");
var erroringClass=new dojo.rpc.JsonService("erroringClass.smd");
</script>
</head>
<body>
<div id="RPC">
<h2>Push these buttons to execute code in the button.</h2>
<h3>Results will be returned and show in "Returned Content"</h3>
</div>
<br>
<div id="ReturnedContent">
<p>None.</p>
</div>
<br>
<div class="box">
<button dojoType="Button" οnclick='testClass.myecho("blah").addCallbacks(contentCallBack,contentErrBack);'>
Echo blah
</button>
<button dojoType="Button" οnclick='testClass.contentB().addCallbacks(contentCallBack,contentErrBack);'>
ContentB()
</button>
<button dojoType="Button" οnclick='testClass.contentC().addCallbacks(callBackForContentC,contentErrBack);'>
Get Object
</button>
<button dojoType="Button" οnclick='testClass.add(5,6).addCallbacks(contentCallBack,contentErrBack);'>
5+6=?
</button>
<button dojoType="Button" οnclick='testClass.triggerRpcError().addCallbacks(contentCallBack,contentErrBack);'>
Error from server
</button>
<button dojoType="Button" οnclick='erroringClass.content().addCallbacks(contentCallBack,contentErrBack);'>
Error from client
</button>
</div>
<br clear=both>
<div id="dojoDebug">
<h2>Debug Log:</h2>
</div>
</head>
</html>
参考资料：
JSON-RPC Specifications
http://json-rpc.org/wiki/specification
Dojo book 以及burnet的中文翻译
http://www.blogjava.net/burnet/