INDEX

RPC Basics

Spaceify's implementation of the JSON-RPC 2.0 protocol supports single, batch and notification requests. The RPC functionality is inherited in the instances of the Service class.

Requests and request parameters

If the request is a single request the method parameter is a string and params is an array of parameters.

someService.callRpc("setTemperature", [21, "C"], ...

If the request is a batch request the methods parameter is an array of method strings and params is an array of parameter arrays.

someService.callRpc(["setTemperature", "setPressure"], [ [21, "C"], [2] ], ...

If the request does not have parameters params is an empty array.

someService.callRpc("getTemperature", [], ...

The parameters must be in the order they are defined in the function body of the exposed method.

someService.callRpc("setTemperature", [21, "C"], ...

function setTemperature(degrees, scale)
  {
  }

Request types

The RPC request responds from the remote end if the request is a single or batch request. Notifications never response to calls. To get the response context and callback function must be provided. If they are not, the RPC class assumes the call is a notification. The context is the context where the callback function is defined.

Request

someService.callRpc("getTemperature", [], this, gotTemperature);

Notification

someService.callRpc("setLightColor", [0, 255, 128]);

Exposed methods

The RPC class must have access to the exposed methods in their context. The methods are regular JavaScript functions. However, the function body must be in a predefined format. The body contains first the methods own arguments and after them follows additional mandatory arguments.

The mandatory arguments are connection object (see the Connection object) and callback function. The connection object contains unique information about the connection through which the request arrived. The callback function must be called by the method after it has finished processing the request. The callback must be made by using the Error-first callback style.

someService.exposeRpcMethod("setTemperature", this, setTemperature)
function setTemperature(value, scale, connObj, callback)
  {
  this.temperature = value;
  this.scale = scale;
  
  // Do some processing...
  
  callback(null, true);
  }

By using the callback, applications can do processing that requires e.g. asynchronous waiting or calling other RPC methods on other services. The response is send only after the callback is called.

someService.exposeRpcMethod("getTemperature", this, getTemperature)
function getTemperature(connObj, callback)
  {
  thermoMeterDriverService.callRpc("getTemperature", [], this, function(err, result)
    {
    callback(err, result);
    });
  }

If there is no need for asynchronous processing the method can be exposed without callback. In this case, rather than waiting for the callback the request returns to caller as soon as the method is finished. The callbackless methods are exposed using Service classes exposeRpcMethodSync method. The "sync" refers here to the notion that the exposed method contains only synchronous processing.

someService.exposeRpcMethodSync("openValve", this, openValve)
function openValve(valve, connObj)
  {
  var pressure = getPressure();

  openValve(valve);

  return pressure;
  }
Close
copyright © Spaceify.org 2014