JavaScript RPC Client

This RPC client implemented in JavaScript enables synchronously and asynchronously calls to XML-RPC and JSON-RPC servers. Asynchronous calls may also be made to supporting JSON-RPC servers (such as the associated PHP implementation) that are hosted cross-site domains without violating the same-origin policy; requests made in such a way should avoid passing parameters containing large data values since they must be passed as the query string in an HTTP GET request. This client implements the 7 August 2006 working draft of JSON-RPC 1.1, but also works with JSON-RPC 1.0 servers as long as they do not fail because of the passed "version" property; furthermore, this client supports JSON-RPC 1.0 class hinting for Date objects and is also able to decode and encode date strings as ISO8601, delimited timestamps (@1234567@), and ASP.NET JSON dates (\/Date(1234567)\/). Client Instantiation and Configuration

The JavaScript RPC client is implemented as a service proxy class, inspired by the implementation in jsolait. The class may be instantiated as follows:

var service = new rpc.ServiceProxy("/app/service", {/*options*/});

Once instantiated, all of the indicated service's methods are accessible as methods of the ServiceProxy object itself. For example, using the "service" object above, if the service's methods are "greetTheWorld" and "math.add" you may execute them by calling the functions "service.greetTheWorld" and "service.math.add" respectively, passing parameters as described further below. The possible configuration options for instantiating a ServiceProxy are listed below, each with its type and default value:

The following is an example of instantiating the ServiceProxy class for a cross-site service since doing so requires the most configuration. Cross-site services may only be accessed asynchronously, their response data may not be sanitized, and introspection is not possible so you must provide the methods yourself. In order to obtain the method response, the JSON-RPC server must be provided the name of a callback function which will be generated in the JavaScript (json-in-script) response. The HTTP GET parameter for passing the callback function is currently non-standardized and so varies from server to server. A service proxy must be created with the option 'callbackParamName' in order to specify the callback function name parameter; the default is 'JSON-response-callback', as used by associatedserver implementation. Note the data here returned by Google is not a JSON-RPC Procedure Return object so it is automatically wrapped within one; in this case, of course, no errors may be returned by the service:

var gcalService = new rpc.ServiceProxy("http://www.google.com/calendar/feeds/myemail%40gmail.com/public", {
                        asynchronous: true,  //default value, but if otherwise error raised
                        protocol: "JSON-RPC",//default value, but if otherwise error raised
                        sanitize: false,     //explicit false required, otherwise error raised
                        methods: ['full']    //explicit list required, otherwise error raised
                        callbackParamName: 'callback'
}); //(note how this specific service is used below)

Making Synchronous Calls

Service introspection is always done with a synchronous call so that the code after the ServiceProxy instantiation may call the service's methods right away. Synchronous calls are not possible for cross-site services. A synchronous service may be created as follows:

var service = new rpc.ServiceProxy("/app/service", {asynchronous:false});

Or synchronous mode may be enabled by executing:

rpc.setAsynchronous(service, bIsAsync)

Synchronous calls are the simplest and easiest to use. The parameters supplied to the service proxy's method are simply the parameters which the service's method accepts. Furthermore, the result of the service's method is returned from the service proxy's method:

try {
   var sum = service.math.add(1,1);
   alert("The sum is: " + sum);
}
catch(e){
   alert("Unable to add numbers because: " + e);
}

However, while synchronous calls are simpler and easier than asynchronous calls, they have the disadvantage of freezing the page until the server responds. This may frustrate the user if the server takes longer than a couple hundred milliseconds to respond since the page is non-responsive during that time. In order to avoid freezing up the browser and to create true Ajax interfaces, asynchronous calls must be used.

Making Asynchronous Calls

When creating a new service proxy, the default configuration is for methods to be called asynchronously. Making asynchronous calls is more involved since callback handlers must be provided if the state of the method's result is desired. When in asynchronous mode, there are two options for how a service proxy's method may be called. The first (and most readible) option is to pass a single object with the following properties (all of which are optional), and the second option is to pass four separate parameters in the following order:

If the service returns with an error or the "onSuccess" and "onComplete" callbacks raise an error, and if the "onException" callback is not provided, then the error is thrown in the browser. Of course theparameter names and execution logic for these callback functions is modeled after Prototype.

Here is an example of making an asynchronous call:

service.math.add({params:[1,1],
                  onSuccess:function(sum){
                     alert("The sum is: " + sum);
                  },
                  onException:function(errorObj){
                     alert("Unable to add numbers because: " + errorObj);
                  },
                  onComplete:function(responseObj){
                     //any 'final' logic
                  }
});

And as referenced above, here is how to access data from the Google Calendar service:

gcalService.full({
     params:{
         alt:'json-in-script' //required for this to work
         'start-min':new Date() //automatically converted to ISO8601
         /*other Google Calendar parameters*/
     },
     onSuccess:function(json){
         json.feed.entry.each(function(entry){
             //do something
         });
     }
});