JSON RPC Manual Translate

                 JSON-RPC-Java Manual 翻译

              最近在学习JSON，并对相应重要资料进行翻译，有些部分由于理解得不透彻，也就导致了翻译上的不准确，还希望大家看后多多指出问题    

 

JSON-RPC-Java Manual

This manual covers the architecture and implementation details of JSON-RPC-Java and contains a reference guide to the various components and interfaces. Please start with the tutorial if want to get started quickly.

Table of Contents

·                Architecture

o                             JSONRPCBridge

o                             Global bridge

o                             JSONRPCServlet

·                Type Mapping

o                             Class Hinting

·                JavaScript client

o                             Synchronous calls

o                             Asynchronous calls

o                             Exceptions

·                References

o                             Opaque References

o                             Callable References

·                Local Argument Resolvers

·                Custom Serializers

Architecture

JSON-RPC-Java consists of two main user visible components, the JSONRPCBridge and the JSONRPCServlet.

JSONRPCBridge

The JSONRPCBridge is a per session object that holds references to objects that are exported to a specific client. It is passed JSON-RPC requests from the transport (JSONRPCServlet) and it then performs the unmarshalling of JSON objects to Java objects, performs the method invocation and then marshalls the method's Java object result back to JSON. Serializer objects perform the actual type conversion between Java and JavaScript objects.

JSONRPCBridge 是每一个持有传输到特定客户端对象引用的session对象. 它从运输站(JSONRPCServlet)传递JSON-RPC请求，然后将JSON对象umarshalling为Java对象，然后执行方法调用(performs the method invocation) 然后将Java 对象方法结果marshalls回JSON， 串化器(Serializer)对象将执行Java和JavaScript对象之间的类型转换。

The JSONRPCBridge must be placed in a HttpSession object registered under the attribute "JSONRPCBridge" to allow the JSONRPCServlet to locate the bridge to make calls on the exported objects.

          JSONRPCBridge必须以”JSONRPCBridge”的属性名注册入一个HttpSession对象中，目的是允许JSONRPCServlet找到对应的birdge并调用输出的对象

The bridge is implemented as session specific for a number of reasons:

·                to improve the security of the application

·                export object methods to specific users

·                hold references to objects returned to a specific client

bridge被特定的session实现有如下原因：

l        提供程序安全机制

l        为特定的user传输object方法

l        当对象返回给特定用户后hold该对象的引用

To export all instance methods of an object to a client:

bridge.registerObject("myObject", myObject);

将一个对象的所有实例方法传递给客户端:

bridge.registerObject("myObject", myObject);

 

To export all static methods of a class to a client:

将一个类的所有静态方法传输给客户端：

bridge.registerClass("MyClass", com.example.MyClass.class);

If registerObject and registerClass are called multiple times with the same key, then the object is replaced with the new one

如果registerObject 和 registerClass方法被相同的key(这里我理解为相同的属性名)调用(理解为注册更好)多次，那么该注册的对象将会被新的对象替换。

Global bridge

There is a global bridge singleton object that allows exporting objects to all HTTP clients. This can be used for registering factory classes although care must be taken with authentication and security issues as these objects will be accessible to all clients. It can be fetched with JSONRPCBridge.getGlobalBridge().

To export all instance methods of an object to all clients:

   Global bridge 是一个单例允许向所有的HTTP客户端传输对象。虽然（使用）它必须注意这些可以被客户端调用的对象的认证和安全问题，但它仍可以被用作注册工厂类. 该单例可以通过JSONRPCBridge.getGlobalBridge()获得。

   Tip: it care must be taken with authentication and security issues

   必须注意认证和安全的问题

   Be taken with: （被）注意，（被）关注

JSONRPCBridge.getGlobalBridge().registerObject("myObject", myObject);

To export all static methods of a class to all clients:

将类的所有静态传输给客户端

JSONRPCBridge.getGlobalBridge().registerClass("MyClass", com.example.MyClass.class);

JSONRPCServlet

This servlet, the transport part of JSON-RPC-Java, handles JSON-RPC requests over HTTP and dispatches them to a JSONRPCBridge instance registered in the HttpSession.

   JSONRPCServlet,是JSON-RPC-Java传送器(transport)的一部分，通过HTTP处理JSON-RPC请求并分派这些请求到一个已在HttpSession中注册的JSONRPCBridge实例上。

An instance of the JSONRPCBridge object is automatically placed in the HttpSession object registered under the attribute "JSONRPCBridge" by the JSONRPCServlet.

   一个JSONRPCBridge对象实例将会自动布置在 由JSONRPCServlet通过属性名“JSONPRCBridge”注册的 HttpSession对象中。

The following would be used in your web.xml to export the servlet under the URI "/JSON-RPC" (this is the standard location):

       如下的web.xml的片段目的是通过URI“/JSON-RPC”输出servlet(这是标准的定位).

<servlet>

 <servlet-name>com.metaparadigm.jsonrpc.JSONRPCServlet</servlet-name>

 <servlet-class>com.metaparadigm.jsonrpc.JSONRPCServlet</servlet-class>

</servlet>

<servlet-mapping>

 <servlet-name>com.metaparadigm.jsonrpc.JSONRPCServlet</servlet-name>

 <url-pattern>/JSON-RPC</url-pattern>

</servlet-mapping>

Please note: due to relative mapping of URIs in your web container. You may need to set the URL in your client to: "/<web-app-name>/JSON-RPC".

请注意：因为URI的mapping是容器相关的。所以你需要在客户端将URL设定为“/<web-app-name>/JSON-RPC”.

Type mapping

类型映射

To allow JSON-RPC-Java to transparently unmarshall complex nested objects and with that, the usage of Java's container classes, JSON-RPC needs a mechanism to preserve type information.

要允许JSON-RPC-Java能够unmarshall复杂的、嵌套的对象和使用Java容器中的类，JSON-PRC必须提供一种机制去保护类型信息。

This comes from the combination of the JavaScript's typeless nature and the method that Java container classes gain their generics (through the usage of a single base class 'Object', rather than using parameterized types such as C++ templates. Note: Java 5.0 however supports these parameterized collection types but support is not yet included in JSON-RPC-Java for this).<

这个问题是由于 如何去结合 JavaScript的typeless性质 和 Java（容器）类去获得他们属性的办法(tip:这里的method翻译为办法更容易理解) 而产生的 (只是简单的通过使用一个基于“Object”的类，而不是使用参数化的类型比如C++中的模板。Note:Java5.0虽然支持参数化类型的collection，但是JSON-RPC-Java不支持这种方式)

In the case of unmarshalling a JavaScript object into a Java method argument with a generic container interface (such as List, Map, Set, or their concrete counterparts), the need for additional type information is apparent. We have no type information on either side to work out the mapping from the contained type of JavaScript array to the contained type of the Java container class.

当需要unmarshalling一个Javascript对象到一个拥有接口(如List, Map, Set,或者他们的一些具体的实现部分)的Java方法中的情况下的时候，显然需要额外的类型信息。在两端（客户端、服务器端）我们都没有类型信息去设计出这种Javascript数组到Java数组之间的映射方式。

With normal array method arguments i.e. a Java method argument of class Foo[], we know the items in the JavaScript array must (or should) be all be class Foo.

普通的数组情况，比如Java的Foo[]，（那么）我们知道（对应）所有该JavaScript数组中的元素必须全部是Foo类(的对象)。

With a Java method argument of class ArrayList, we only have Object as the contained type and no type information with a regular JavaScript object.

当Java方法可以声明返回类型为ArrayList，而JavaScript中我们只有作为类型的Object对象且没有详细的类型信息。

This leads to the method that JSON-RPC-Java maintains it's transparent mapping - 'class hinting'.

这个产生了JSON-RPC-Java提供的’class-hinting’ mapping方法。

Class Hinting

In the case of regular Java Beans an extra field javaClass is added that maps the typeless JavaScript object back to the Java class. The is used on the Java side during unmarshalling to ease the transparent mapping of the object back to it's Java Class when it is sent back to the server (although JSON-RPC-Java can in some cases map the objects without the additional type information if the mapping is unambiguous i.e. if the object is not inside of a generic container class, then the method class signature can be used).

在Java Beans的前提下，一个额外的javaClass域被添加用于将无参化的JavaScript对象映射回Java class(呵呵，这样就可以利用反射还原为对应的Java对象了)，这个机制主要是用在Java端，这样就很容易的将无参化的JavaScript对象在传回server端的时候映射为对应的Java Class类（虽然JSON-RPC-Java在某些时候比如映射关系清晰的情况下，可以在没有额外的参数信息的前提下进行对象的映射。如果对象不存在于一个容器class中(这里应该指的是Java容器中自带的类)，那么就可以用到类签名的方法）

For Java container classes such as the List, we can't map them to a JavaScript native array as we would have nowhere to store the type hint. So Java container classes have a special type mapping from Java to JavaScript described here:

对于Java容器类比如List，我们不能将它映射为JavaScript自身的数组，因为我们没有地方存储类型信息(type hint)。所以对于Java的容器类与JavaScript有一种特殊的类型映射方法:

Bean

Java beans (objects conforming to get getProperty, setProperty, etc. syntax) map directly to a JavaScript Object with the additional of the string member javaClass containing the Java class name. The property names have the get or set prefix removed and the first letter lowercased. eg.

Java beans(符合getProperty和setProperty等的规范)映射为JavaScript对象的时候需要一个额外的JavaClass名称的字符参数。（随后的）属性名都是将get或者set去掉然后将首字母小写后得到的。

{

 "javaClass": "com.example.MyBean",

 "someStringProperty": "foo",

 "someBooleanProperty": true,

 "someIntegerProperty": 10

}

List

List (ArrayList, LinkedList, Vector) maps to a JavaScript object with a string member javaClass containing the Java class name and a native JavaScript array member list containing the data. eg.

List（ArrayList, LinkedList, Vector）映射为JavaScript对象，需要一个对应Java class的javaClass字符串作为参数并且还包含一个JavaScript数组，里面包含了所有的数据。

{

 "javaClass": "java.util.ArrayList",

 "list": [0, 1, 2, 3, 4]

}

Map

Map (HashMap, TreeMap, LinkedHaspMap) maps to a JavaScript object with a string member javaClass containing the Java class name and a nativeJavaScript object containing the key value pairs. eg.

{

 "javaClass": "java.util.HashMap",

 "map": {"foo key": "foo value"}

}

The Java string representation of the key object is used as the native JavaScript object type only supports strings as keys.

Set

Set (HashSet, TreeSet, LinkedHashSet) maps to a JavaScript object with a string member javaClass containing the Java class name and a native JavaScript object containing the set item string values as keys and set objects as values. eg.

{

 "javaClass": "java.util.HashSet",

 "set": {"foo key": "foo key"}

}

The Java string representation of the key object is used as the native JavaScript object type only supports strings as keys.

由Java string 表示的key对象被用做Javascript对象类型的时候只支持将stings作为key.

JavaScript Client

The JavaScript client JSONRpcClient constructs a transparent proxy providing method access to all methods on the JSON-RPC server.

It is constructued like this:

       JavaScript客户端 JSONRpcClient构造了一个透明代理，提供了对所有server端的方法进行调用的方法

var jsonrpc = new JSONRpcClient("/webapp/JSON-RPC/")

HTTP authentication can also be used

   HTTP权限验证方式：

var jsonrpc = new JSONRpcClient("/webapp/JSON-RPC/", user, pass)

The consutrctor of the JSONRpcClient object queries the server using the internal method system.listMethods which returns an array with the list of object methods available on the server. Proxy delegating functions are then added to the new JSONRpcClient object with each of the method names on the server.

JSONRpcClient对象的构造器用内部的方法system.listMethods去查找并返回一个server端可用的对象方法的列表。然后Proxy代理方法将会用这些方法名加入到这个新的JSONRpcClient对象中

Synchronous calls

       同步调用

A synchronous call can be made on one of the server methods by calling the associated object method on the JSONRpcClient object. eg. to call the method echo on the object exported with the name test, we would use:

一个同步调用的方法可以由JSONPpcClient对象调用关联的对象方法创建。比如，在对象上调用输出名为test的echo方法：

jsonrpc.test.echo("hello");

Asynchronous calls

Asynchronous calls are simply made by inserting a JavaScript callback function as the first argument.

异步调用简单通过增加JavaScript回调方法并将其作为第一个参数而创建。

jsonrpc.test.echo(cb, "hello");

Anonymous functions can also be used:

   匿名方法同样可以由如下方式调用：

jsonrpc.test.echo(function (msg) { print(msg); }, "hello");

The callback function is passed two arguments:

   回调方法提供了两个参数:

function cb(result, exception) {

 if(exception) { alert(exception.message); }

 // do stuff here ...

}

The second argument to callback functions is required to capture exception information. You must be aware of the following when using async callback functions:

 第二个参数是回调函数中用于捕获异常信息的。当执行异步方法调用的时候，必须注意如下信息

·                result == null && exception != null when an exception occured.

·                result != null && exception == null when the call completed successfully.

Exceptions

The JSONRpcClient constructor proxy methods can throw an exception of type JSONRpcClient.Exception (ie. e.constructor == JSONRpcClient.Exception). The JSONRpcClient.Exception object is derived from the JavaScript Error object and thus inherits its general properties such as message.

JSONRpcClient构造代理方法可以抛出JSONRpcClient.Exception异常（比如e.constructor==JSONRpcClient.Exception）.JSONRpcClient.Exception是从JavaScript Error对象继承下来并继承了它的所有的普通的属性比如message.

Two types of exceptions are thrown from proxy methods on the JSONRpcClient object:

两中类型的异常由JSONRpcClient对象的代理方法抛出

·                Client exceptions - exceptions that occured during the remote communication with the JSON-RPC server.

·                Java native exceptions - exceptions throw by the remote code.

·                Client exceptions- 当于服务器端的JSON-RPC进行访问的时候抛出的异常

·                Java native exception- 由远程代码抛出

Client Exceptions

Thrown if a communication error occurs, a method cannot be found. It has the following properties:

如果访问时候出错抛出该异常，比如一个方法不能找到等。它具备如下的一些属性：

·                e.name == "JSONRpcClientException"

·                e.code an integer error code containing either an HTTP status code or one of the following codes:

o                             JSONRpcClient.Exception.CODE_ERR_PARSE = 590

o                             JSONRpcClient.Exception.CODE_ERR_NOMETHOD = 591

o                             JSONRpcClient.Exception.CODE_ERR_UNMARSHALL = 592

o                             JSONRpcClient.Exception.CODE_ERR_MARSHALL = 593

·                e.message a string containing descriptive text of the exception.

Java native exceptions

Thrown if the remote Java method raises an exception. It has the following properties:

远端Java方法抛出异常时抛出。

·                e.name == "<class name of remote exception>"

·                e.code == JSONRpcClient.Exception.CODE_REMOTE_EXCEPTION

·                e.message a string containing descriptive text of the exception.

·                e.javaStack a string containing the Java stack trace.

References

JSON-RPC-Java has some basic ORB (Object Request Broker) functionality with the ability to pass objects by reference and keep these references in the user's session.

 JSON-RPC-Java拥有一些基本的ORB功能，具有通过引用传递对象并将这些引用保留在用户的session中

Two types of references are handled: opaque references and callable references.

两种引用：opaque 引用和 callable引用

Opaque References

Objects of classes registered as References will be returned as opaque reference objects to JavaScript instead of passed by value which is the default behaviors. When these opaque reference objects are passed to successive Java method calls will then be reassociated back to the original Java object (great for security sensitive objects).

 

被注册为引用的类对象将会以opaque引用对象返回到JavaScript而不是由默认的值传递方式。当这些opaque引用对象被Java方法调用的时候将会被转换回当初的Java对象(非常有助于sensitive objects的安全性)

A class can be registered as an opaque reference on the JSONRPCBridge as follows:

一个类可以通过JSONRPCBridge注册成为opaque引用：

bridge.registerReference(com.metaparadigm.test.Foo.class)

A reference in JSON format looks like this:

JSON中的引用格式：

{ "javaClass":"com.metaparadigm.test.Foo",

 "objectID":5535614,

 "JSONRPCType":"Reference" }

References could should be used for privileged objects that contain information that needs to be kept secure or complex types that are not required in the Javascript client but need to be passed as a reference in methods of exported objects.

引用应该被用在具有特权的对象上，比如该对象包含了某些维持安全和复杂的类型的信息，而这些信息在Javascript端不需要，但是这些信息需要作为引用被输出对象所传递。

Callable References

Objects of classes registered as Callable References will return dynamic proxies to allow invocation on the particular object instance in the server-side Java. There are extensions to the JSON-RPC protocol in the provided JSON-RPC JavaScript client for dynamic proxy creation support.

被注册为Callable引用的类对象将会返回动态代理，允许调用服务器端的某个特定的对象实例。JSON-RPC协议的扩展为JSON-RPC JavaScript端动态代理的生成 提供了支持。

 A class can be registered as a callable reference on the JSONRPCBridge as follows:

bridge.registerCallableReference(com.metaparadigm.test.Bar)

A callable reference in JSON format looks list this:

{ "javaClass":"com.metaparadigm.test.Bar",

 "objectID":4827452,

 "JSONRPCType":"CallableReference" }

CallableReferences can be registered for classes that for instance are returned from factory classes as a convenient way to avoid having to manually export these objects returned from these factory methods.

CallableReferences为注册为该引用的对象提供了从工厂类中返回的简单的方法，避免了通过人工的方式调用工厂方法返回这些对象。

Note: A limitation exists in the JSON-RPC client where only the top most object returned from a method can be made into a proxy.

Note: JSON-RPC client的一个局限性，只有方法返回的最顶层的对象可以被作为代理。

Local Argument Resolvers

LocalArgResolvers are classes that can resolve an argument from the exported method signatures on the server-side. The exported signature of methods that contain a class registered as a LocalArgResolver have that class removed. It does not need to be provided in call in the JSON-RPC client.

LocalArgResolvers是这样一种类，他可以识别一个从服务器端输出方法的签名。包含了一个注册为LocalArgResolver的类的输出方法签名将会把该类移除。因为在调用JSON-RPC客户端的时候不需要提供它。

The LocalArgResolver provides a mechanism to get access to the HttpServletRequest or HttpSession object associated with a request/method invocation. There are 3 LocalArgResolvers that are enabled by default:

LocalArgResolver提供了调用HttpServletRequest和HttpSession的一种机制。这里有三种默认的LocalArgResolver：

·                JSONRPCBridgeServletArgResolver

·                HttpSessionArgResolver

·                HttpServletRequestArgResolver

Additional LocalArgResolvers can be created by implementing the LocalArgResolver interface and calling JSONRPCBridge.registerLocalArgResolver()

额外的LocalArgResolvers可以通过实现LocalArgResolver接口和调用JSONRPCBridge.registerLocalArgResolver()方发创建

An example method that has JSONRPCBridge in the method signature:

   一个方法签名中包含JSONRPCBridge的示例子：

public void setDebug(JSONRPCBridge bridge, boolean flag)

{

    bridge.setDebug(flag);

}

This can be called from JavaScript like this:

jsonserver.test.setDebug(true);

The JSONRPCBridge object associated with the users session will be resolved on the server-side and passed in to the remote method. Likewise you can add HttpSession or HttpServletRequest to your methods and have them filled in automatically.

关联用户session的JSONRPBridge对象将会在服务器端被调用并且并远程方法所传递。同样的，你可以添加HttpSession或者是HttpServletRequest到你的方法中然后他们将自动被赋值。

Custom Serializers