JSON-RPC Client

The JSON-RPC JavaScript client library provides a simple and easy way for Rich Internet Applications (RIA) to interact with the server. A RIA 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 typically based on URL's and not on the RPC methods the client calls.

A JSON-RPC service is typically structured around one or more objects, each containing one or more methods. This design parallels object-oriented programming principles, where methods within an object are invoked to perform actions.

The JSON-RPC client utilizes introspection to automatically replicate the server-side JSON service methods, allowing these methods to be called directly as standard JavaScript functions.

Note: Check out the JSON-RPC over SMQ Example for implementing Remote Procedure Calls leveraging the SMQ pub/sub protocol. This library facilitates ultra-fast communication via WebSockets, offering an efficient and speedy data exchange for your applications.

Blocking Server Calls

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.

alert(rpc.math.add(10,10,10,10)); // Displays 40

alert(rpc.math.add([10,10,10,10])); //Throws InvalidType exception

Asynchronous Server Calls

The client can call methods in the server using blocking calls as above or using asynchronous calls. 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 a callback function asynchronously as soon as the server has sent the response message.

The callback can be a function or an object with a onResponse method. The RPC client switches to asynchronous mode, if the first argument provided is an "object with an onResponse method" or a function.

The callback approach is for programmers used to functional programming, JavaScript closures, and anonymous functions. The response object approach is more similar to how events are typically used in compiled languages such as Java and C++.

Anonymous Function Example

A closure outlives the scope of the function that creates it thus state variables can easily be made accessible to the callback.

var myStateVariable="Any data used by callback";
rpc.math.add(function(isOk, response) {
    if(isOk) alert("10+10="+response);
    else alert(response); // Response is now the error msg.
  },
  10,
  10);

The callback function 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.

Response Object Example

The response object can be used as an alternative approach to storing state variables In a closure.

var respObj = {
   myStateVariable:"Any data used by callback",
   onResponse:function(success, response){
      if(success) alert("10+10="+response);
      else alert("Call failed: " + response.toString());
   }
};
rpc.math.add(respObj,
             10,
             10);

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.

Arguments:

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 contains a toString method. 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 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.

/rtl/json/jrpc.js	The JSON-RPC client.
/rtl/json/json.js	The JSON encoder and decoder used by the JSON-RPC client.

Examples

Synchronous (blocking) example

<html>
<head>

<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/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>