JSON RPC JavaScript client library

The JSON RPC client library provides a simple and easy way for WEB 2.0 applications to interact with the server. A WEB 2.0 application can call any of the methods provided by a JSON RPC service as soon as the RPC client is created.

The Barracuda Embedded Web Server can provide an unlimited number of JSON RPC services. A JSON RPC service can be installed at any URL location in the server.

Authorization is provided by the general Barracuda authentication and authorization logic. It is therefore common to provide a number of JSON RPC services in the server as the authorization is based on URL's and not on the RPC methods the client calls.

A JSON RPC service typically consists of one or several objects. Each object in turn consists of one or several methods. This is equivalent to an object oriented design where one typically calls a method in an object.

An instance of the JSON RPC client is using introspection to automatically create a copy of the methods provided by the JSON service in the Barracuda server. The client can simply call the method as if it is a standard JavaScript method.

As an example, assume we have a math JSON service at location "/math" in the server.The math service provides a math object and methods such as add, subtract, etc..

var rpc;
try {
   rpc = new JRpc("/math");
}
catch(e) {
   alert("Cannot connect to RPC service");
}
try {
   var result = rpc.math.add(10,10);
   alert(result);
}
catch(e) {
   alert("Call failed: " + e.toString());
}

In the above example, we connect a rpc client to the "/math" service in the server. We then call the math.add method in the server.

You can pass any number of arguments and any type of object when calling a method in the server. It is the server method's responsibility to validate your arguments and the data sent to the server. A method in the server can be designed to allow a variable number of arguments and/or types of arguments.

As an example, let us assume the add method allows any number of arguments, but that the argument must be a number type.

Asynchronous server calls

The client can call methods in the server using blocking calls as above or provide a callback object the RPC client can call when the response is returned from the server. The RPC client uses asynchronous server calls, if the first argument provided is an object with an onResponse method.

Using asynchronous server calls:

var respObj = {
   onResponse:function(success, response){
      if(success) alert("Result="+response);
      else alert("Call failed: " + response.toString());
   }
};


var rpc;
try {
   rpc = new JRpc("/math");
}
catch(e) {
   alert("Cannot connect to RPC service");
}
rpc.math.add(respObj, 10,10);

The benefit of using asynchronous calls is that the client does not block and become unresponsive while the remote call is in progress. The client JavaScript code can continue with other tasks while the call is in progress. The RPC client calls the onResponse method asynchronously as soon as the server has sent the response message.

The onResponse method receives two arguments. The first argument is a Boolean that is either true or false. The value true means that the call was successful. The second argument is either the response message if the call was successful, or an exception object if the call failed.

JRpc

JRpc(url[,action])

The JRpc constructor.

• url: the URL to the RPC service in the server.
• action: This is an optional argument, which controls how the client JRpc object can use introspection to automatically populate the client side with the RPC methods returned by method system.describe in the server.
  • Default -- i.e. no argument: Blocks the caller until system.describe returns and the client has built a copy of the server methods.
  • Object with an onResponse function: Do asynchronous introspection - i.e. do not block the caller. The onResponse is called when the introspection has completed. oneResponse(status[,error]), where status = true/false and error is only set if status=false.
  • false: Do not call system.describe -- i.e. do not perform introspection. Methods can be manually added by calling the internal method rpc.$addMethod(string), where string is "interface.method".

The exception object

The exception object is an object from the EventHandler. The object contains a toString method you can use during development. The toString method gives detailed information about what went wrong.

The exception object can contain the following attributes:

status

This attribute is set if the error was caused by a non 200 HTTP response code. The most common response code is 403 forbidden, i.e. -- the user is not authorized to call methods in the RPC server.

if(e.status)
{
   alert("HTTP response code error="+e.status);
}

code

This attribute is set if the RPC server or the RPC method throws an exception. The code can be zero so you must test with JavaScript undefined. The HTTP status is always 200 for errors thrown by the server service. Thus, the 'status' attribute is undefined if 'code' is set.

if(e.code != undefined)
{
   alert("RPC service error: code="+e,code+", message="e.message);
}

The 'code' attribute is from the JSON RPC specification, the Error Object. The specification is a draft and the error codes are not specified. You should therefore use the 'message' attribute if 'code' is not undefined.

message

The 'message' attribute provides a textual representation of the error. The message may be from the server, the RPC server service, or from an exception within the client RPC stack.

errno

A unique error number created by the EventHandler or the RPC client.

Loading and starting a JSON RPC client

The JSON RPC client library is in the JRpc.js JavaScript file. You must load this into your HTML page before you can setup a connection. The JRpc.js requires the following components.

Examples

Synchronous (blocking) example

<html>
<head>

<script src="/rtl/eh/eh.js"></script> 
<script src="/rtl/json/json.js"></script> 
<script src="/rtl/json/JRpc.js"></script> 

<script>
onload=function()
{
   var rpc;
   try {
      rpc = new JRpc("/math/");
      alert("10+10="+rpc.math.add(10,10));
   }
   catch(e) {
      alert("Cannot connect to RPC service");
   }
};
</script>

</head>
</html>

Asynchronous (non-blocking) example

<html>
<head>

<script src="/rtl/eh/eh.js"></script> 
<script src="/rtl/json/json.js"></script> 
<script src="/rtl/json/JRpc.js"></script> 

<script>
onload=function()
{
   var rpc = new JRpc("/math/", function(isOk, err) {
      if(isOk) {
         rpc.math.add(function(isOk, response) {
            if(isOk) alert("10+10="+response);
            else alert(response); // Response is now the error msg.
         },
         10,10);
      }
      else alert(err);
   });
};
</script>

</head>
</html>