Usage
object: rpc (Remote Procedure Call)
rpc object exposes trust-safe properties, functions and events to provide reliable two-way messaging (request-response) between multiple endpoints allowing you to build sophisticated asynchronous interactions.
Concepts
- RPC endpoint / server (CALLEE)
- Application using dataBridges server library can expose callback function(s) as a dataBridges rpc function.
- Multiple callback function(s), can be exposed as rpc functions grouped together as an rpc endpoint / server.
- To deploy access-controlled, trust-safe rpc endpoint / server, prefix the rpc server namespace with pvt: or prs:
- Note dataBridges have 2 separate libraries (client lib, server lib). You are reading the server library api document.
- Server lib uses app.key along with secret to get access to rpc endpoint/server including pvt: , prs: access controlled rpc endpoint/server.
- Whereas application using client library (client application) will always need to pass a trust-token to access restricted rpc endpoint/server (prefixed with pvt: prs:) . A trust-token is a JWT document created using a combination of channelname + sessionid + app.secret. Trust token can be created by application having access to app.key's secret.
- you can use your existing access control, authorization and session identification rule-set, process and methods to create a trust-token instructing the dataBridges router to accept the pvt: prs: rpc call() client application.
- Trust-tokens allows you to enable secured, access controlled and compliance driven two-way messaging (request-response) between multiple endpoints allowing you to build sophisticated asynchronous interactions in your existing and new initiative applications.
- RPC clients (CALLER)
- Both dataBridges client and server api's allow you to execute rpc function(s) exposed by rpc endpoint / server.
- Application consuming rpc function(s) is called CALLEE and the rpc endpoint/server application is called CALLER.
- CALLEE application will execute a remote function by passing IN.paramter, and a timeout
- The CALLER application's corresponding function will be invoked with the IN.parameter and it will respond with response() or exception() which will be delivered back to the CALLEE application by dataBridges network completing the request-response communication.
- CALLEE application need not be aware about RPC servers (CALLER) identity and will only interact with RPC server (CALLER) namespace. The dataBridges network will intelligently route and load balance RPC call() to the RPC server application. The dataBridges network will automatically load balance multiple instance of server application exposing the same RPC endpoints.
To expose rpc functions the application needs to register an rpc server and register callback functions to rpc server as rpc functions.
- The steps involved are :
- Initialize rpc endpoint/server using
init()
. - Register all rpc functions using
regfn()
. - Register rpc endpoint/server with dataBridges network using
register()
Initialize rpc Server
Initialize the server using rpc.init
function of your dataBridges object. This will return an object to which all properties, functions and events are available.
Note : Application can have multiple rpc endpoint/server against a dataBridges object.
//lets create an rpc endpoint/server named missionControl and expose 2 functions called nasa and isro.
using dBridges.remoteprocedure;
try {
Crpcserver missionControl = dbridge.rpc.init('missionControl');
} catch (dBError err) {
Console.WriteLine("{0} , {1} , {2}" , err.source, err.code, err.message);
}
Parameter | Rules | Description |
---|---|---|
string | serverName **OR* pvt:**serverName **OR **prs:**serverName* | Initialize a rpcServer with *server*Name . |
Return Type | Description |
---|---|
object | rpcObject which events, properties and related functions can be bound to. |
Exceptions:
Source | Code | Description |
---|---|---|
DBLIB_RPC_INIT | INVALID_SERVERNAME | Applicable for below conditions 1. serverName is not defined. 2. serverName already exists 3. serverName is blank. 4. serverName validation error, length of serverName greater than 64 5. serverName validation error, serverName fails a-zA-Z0-9\.:_- validation.6. serverName contains : and first token is not pvt,prs . |
Register rpc functions
Application can expose callback function(s) as rpc functions. Application using dataBridges client/server library can remotely execute the rpc functions. Each function needs to be registered with the library as a rpc function, using rpc.regfn()
where you can link the functionName to rpcFunctionName.
- The server application that exposes the rpc function is called a CALLEE.
- The client/server application that executes the rpc function is called a CALLER.
Functions can be defined either inside the property callback function or anywhere in the scope of application. Below code exhibits both ways of exposing the function.
// function is exposed outside the property callback function, but in the scope of application.
function rpcFuncOustide (payload, response) {
try {
response.tracker = true;
response.next('This is Houston');
response.end('message received by Houston');
response.exception('INVALID_PARAM', 'Wrong parameter');
} catch(err) {
console.log(err.source, err.code, err.message);
}
}
missionControl.functions = function () {
// function is exposed inside the property callback function.
function rpcFuncInside (payload, response) {
try {
response.tracker = true;
response.next('This is Hassan');
response.end('message received by Hassan');
response.exception('INVALID_PARAM', 'Wrong parameter');
console.log(response.id);
} catch(err) {
console.log(err.source, err.code, err.message);
}
}
// registering function to be exposed by rpcServer
try {
missionControl.regfn("nasa", rpcFuncOustide);
missionControl.regfn("isro", rpcFuncInside);
} catch(err) {
console.log(err.source, err.code, err.message);
}
}
// unregistering of function exposed by rpcServer
missionControl.unregfn("nasa", rpcFuncOustide);
# function is exposed outside the property callback function, but in the scope of application.
async def rpcFunOutside(inparameter, response):
try:
response.tracker = True
print("iparameter = " , inparameter.inparama)
print("extra info = " , inparameter.sysinfo)
response.next('This is Houston')
response.end('message received by Houston')
response.exception('INVALID_PARAM', 'Wrong parameter')
except dBError as e:
print(e.code, e.source, e.message)
# function is exposed inside the property callback function.
async def rpcFunctionBinder():
# function is exposed inside the property callback function, but in the scope of application.
async def rpcFunInside(inparameter, response):
response.tracker = True
try:
response.tracker = True
print("iparameter = " , inparameter.inparama)
print("extra info = " , inparameter.sysinfo)
response.next('This is Hassan')
response.end('message received by Hassan')
response.exception('INVALID_PARAM', 'Wrong parameter')
except dBError as e:
print(e.code, e.source, e.message)
try:
#// registering function to be exposed by rpcServer
missionControl.regfn("nasa", rpcFunInside)
missionControl.regfn("isro", rpcFunOutside)
except dBError as e:
print(e.code, e.source, e.message)
missionControl.functions = rpcFunctionBinder
# unbinding of function exposed by rpc functions
missionControl.unregfn("rpcFunOutside", ifunctionoutside)
// function is exposed outside the property callback function, but in the scope of application.
using dBridges.responseHandler;
using dBridges.Utils;
async void rpcProcOutside(object inparam, object response)
{
try {
dBParams parameter = inparam as dBridges.Utils.dBParams;
Console.WriteLine("iparameter = {0}" , parameter.inparama);
Console.WriteLine("extra info = {0}" , parameter.sysinfo);
CResponseHandler responsehandler = response as CResponseHandler;
responsehandler.tracker = true;
responsehandler.next('This is Houston');
responsehandler.end('message received by Houston');
responsehandler.exception('INVALID_PARAM', 'Wrong parameter');
} catch (dBError err) {
Console.WriteLine("{0} , {1} , {2}" , err.source, err.code, err.message);
}
}
// function is exposed inside the property callback function.
async void RpcFunctionBinder(object sender)
{
try{
//sender is same as rpcSvrObject
// function is exposed outside the property callback function, but in the scope of application.
Action<object , object> ifunctionoutside = rpcProcOutside;
// registering function to be exposed by rpcServer
missionControl.regfn("nasa", ifunctionoutside);
// registering function to be exposed by rpcServer
Action<object , object> ifunctioninside;
missionControl.regfn("isro", ifunctioninside = (object inparam, object response) =>{
// function is exposed inside the property callback function, but in the scope of application.
try {
dBParams parameter = inparam as dBridges.Utils.dBParams;
Console.WriteLine("iparameter = {0}" , parameter.inparama);
Console.WriteLine("extra info = {0}" , parameter.sysinfo);
CResponseHandler responsehandler = response as CResponseHandler;
responsehandler.tracker = true;
responsehandler.next('This is Houston');
responsehandler.end('message received by Houston');
responsehandler.exception('INVALID_PARAM', 'Wrong parameter');
} catch (dBError err) {
Console.WriteLine("{0} , {1} , {2}" , err.source, err.code, err.message);
}
});
} catch (dBError err) {
Console.WriteLine("{0} , {1} , {2}" , err.source, err.code, err.message);
}
}
Action<object> irpcFunctions = RpcFunctionBinder;
missionControl.functions = irpcFunctions;
// unregistering of function exposed by rpcServer
missionControl.unregfn("rpcProcOutside", ifunctionoutside);
Below are parameters of the callback function which is exposed to rpcServer.
Parameter | Description |
---|---|
payload | (object) Input payload from the caller. |
response | (object) Response object having properties and function to return execution results of the function back to caller. |
payload: (object)
Properties/Function | Description |
---|---|
inparam | (string) Input parameters received to execute the function. |
sessionid | (string) Session id of the member who has requested to execute the function. |
libtype | (string) Library Lang of the member who has requested to execute the function. |
sourceipv4 | (string) IPv4 of the member who has who has requested to execute the function. |
sourceipv6 | (string) IPv6 of the member who has who has requested to execute the function. |
info | (string) System Info of the member who has who has requested to execute the function. |
response: (object)
Properties/Function | Description |
---|---|
tracker | (boolean) This will enable response tracker, and event rpc.response.tracker will be fired if any issue happens in sending back response to caller. Enable this property if your function needs a confirmation of response delivered to the caller. |
id | (string) (readonly) Each rpc function execution is assigned a unique ID by the library. when the response tracker is enabled, the application can bind to an event rpc.response.tracker to get the delivery notification. The event will indicate the delivery notification linked to this ID. Caller application will need to maintain this ID to track the delivery notification. |
next | (function) dataBridges rpc supports multi-part response. Application can use response.next to send multi-part response to the caller. |
end | (function) response.end is to send the final response to the caller. Once end is called, the object is closed and no more response can be sent. |
exception | (function) Two parameter, return errorCode (string) ,errorMessage (string) is sent to caller. This will raise an exception at the caller library. |
Exceptions:
Below exceptions are raised in the rpc.regfn
.
Source | Code | Description |
---|---|---|
DBLIB_RPC_REGFN | INVALID_FUNCTION_NAME | Invalid Function name. |
DBLIB_RPC_REGFN | INVALID_CALLBACK | Callback is not a function or is not defined. |
Below exceptions are raised on response
object inside the registered function.
Source | Code | Description |
---|---|---|
DBNET_RPC_CALL | NETWORK_DISCONNECTED | Connection to dataBridges network is not active. |
DBLIB_RPC_CALL | RESPONSE_OBJECT_CLOSED | Return response object is closed. Thus the function is unable to respond back to the call. |
Register Server
Register rpc endpoint/server with dataBridges network using register()
.
try {
missionControl.register();
} catch (err) {
console.log(err.source, err.code, err.message);
}
// Best practice is to check the channel is online before publishing any message.
if (dbridge.connectionstate.isconnected()) {
try {
missionControl.register();
} catch (err) {
console.log(err.source, err.code, err.message);
}
}
try {
missionControl.register();
} catch (dBError err) {
Console.WriteLine("{0} , {1} , {2}" , err.source, err.code, err.message);
}
// Best practice is to check the channel is online before publishing any message.
if (dbridge.connectionstate.isconnected()) {
try {
missionControl.register();
} catch (dBError err) {
Console.WriteLine("{0} , {1} , {2}" , err.source, err.code, err.message);
}
}
Exceptions:
Source | Code | Description |
---|---|---|
DBLIB_RPC_REGISTER | RPC_INVALID_FUNCTIONS | Applicable for below conditions 1. If "callback function" is not declared for rpc server 2. typeof() variable defined is not a "function". |
DBLIB_RPC_REGISTER | NETWORK_DISCONNECTED | Connection to dataBridges network is not active. |
Unregister Server
rpcServer can be unregistered from dataBridges server library using unregister
function of your rpcServerObject.
resetqueue()
dbridgeObject The dataBridges network maintains in-process rpc function execution status. resetqueue() informs the dataBridges network that all in-process rpc function execution will be dropped by the application and response to be invalidated. Resetqueue() use case is intended to be used by application in its self health status management. Sometime due to the application process flow, the application can identify situation where it would like to ease its load by resettiing the rpc function execution queue by sending resetqueue() message to dataBridges network and than closing all in-process rpc function execution.
Exceptions:
Source | Code | Description |
---|---|---|
DBLIB_RPC_CALL | NETWORK_DISCONNECTED | Connection to dataBridges network is not active. |
System events for rpc server registration.
There are a number of events which are triggered internally by the library, but can also be of use elsewhere. Below are the list of all events triggered by the library.
Below syntax is same for all system events.
// Binding to systemevents on rpcObject
try {
missionControl.bind('eventName', (payload, metadata) => {
console.log(payload, metadata);
});
} catch(err){
console.log(err.source, err.code, err.message);
}
// Binding to systemevents on dbridgeObject
try {
dbridge.rpc.bind('eventName', (payload, metadata) => {
console.log(payload, metadata);
});
} catch(err){
console.log(err.source, err.code, err.message);
}
# Binding to systemevents on rpcObject
async def eventCallback(payload , metadata):
print(payload , metadata)
try:
rpcSvrObject.bind('eventName', eventCallback)
except dBError as e:
print(e.code, e.source, e.message)
# Binding to systemevents on dbridgeObject
try:
dbridge.rpc.bind('eventName', eventCallback)
except dBError as e:
print(e.code, e.source, e.message)
// Binding to systemevents on rpcObject
try {
Action<object , object> ievent;
rpcSvrObject.bind("eventName", ievent = (object inparam, object metadata) =>{
Console.WriteLine("{0} , {1}" , inparam , metadata);
});
} catch (dBError err) {
Console.WriteLine("{0} , {1} , {2}" , err.source, err.code, err.message);
}
// Binding to systemevents on dbridgeObject
try {
Action<object , object> ievent;
dbridge.rpc.bind("eventName", ievent = (object inparam, object metadata) =>{
Console.WriteLine("{0} , {1}" , inparam , metadata);
});
} catch (dBError err) {
Console.WriteLine("{0} , {1} , {2}" , err.source, err.code, err.message);
}
Callback out parameter payload, metadata
details are explained with each event below in this document.
Exceptions:
Source | Code | Description |
---|---|---|
DBLIB_RPC_BIND | INVALID_EVENTNAME | Invalid Event name. Not in default events. |
DBLIB_RPC_BIND | INVALID_CALLBACK | Callback is not a function or is not defined. |
bind_all
and unbind_all
bind_all
and unbind_all
work much like bind
and unbind
, but instead of only firing callbacks on a specific event, they fire callbacks on any event, and provide that event in the metadata to the handler along with the payload.
// Binding to all rpc events on rpcObject
try {
rpcObject.bind_all((payload, metadata) => {
console.log(payload, metadata);
});
} catch(err){
console.log(err.source, err.code, err.message);
}
// Binding to all rpc events on dbridgeObject
try {
dbridge.rpc.bind_all((payload, metadata) => {
console.log(payload, metadata);
});
} catch(err){
console.log(err.source, err.code, err.message);
}
# Binding to rpc events on rpcObject
def eventFunction(payload , metadata):
print(payload , metadata)
try:
rpcObject.bind_all('event', eventFunction)
except dBError as e:
print(e.code, e.source, e.message)
# Binding to rpc events on dbridgeObject
try {
dbridge.rpc.bind_all('event', eventFunction)
except dBError as e:
print(e.code, e.source, e.message)
// Binding to all rpc events on rpcObject
try {
Action<object , object> irpcstatus;
rpcObject.bind_all(irpcstatus = (payload, metadata) => {
Console.WriteLine("{0} , {1} " , payload, metadata);
});
} catch (dBError err) {
Console.WriteLine("{0} , {1} , {2}" , err.source, err.code, err.message);
}
// Binding to all rpc events on dbridgeObject
try {
Action<object , object> irpcstatus;
dbridge.rpc.bind_all(irpcstatus = (payload, metadata) => {
Console.WriteLine("{0} , {1} " , payload, metadata);
});
} catch (dBError err) {
Console.WriteLine("{0} , {1} , {2}" , err.source, err.code, err.message);
}
Callback out parameter payload, metadata
details are explained with each event below in this document.
Exceptions:
Source | Code | Description |
---|---|---|
DBLIB_CONNECT_BIND | INVALID_CALLBACK | If "callback function" is not declared or typeof() variable defined is not a "function". |
unbind_all
works similarly to unbind
.
// Remove just `handler` across the rpc server
rpcObject.unbind_all(handler);
//Remove all handlers for the all event in the subscribed/connected rpc server
rpcObject.unbind_all();
// Remove `handler` across the subscribed/connected rpc servers
dbridge.rpc.unbind_all(handler);
// Remove all handlers for all events across all subscribed/connected rpc servers
dbridge.rpc.unbind_all();
# Remove just `handler` across the rpc server
rpcObject.unbind_all(handler)
# Remove all handlers for the all event in the subscribed/connected rpc server
rpcObject.unbind_all()
# Remove `handler` across the subscribed/connected rpc servers
dbridge.rpc.unbind_all(handler)
# Remove all handlers for all events across all subscribed/connected rpc servers
dbridge.rpc.unbind_all()
// Remove just `handler` across the rpc server
rpcObject.unbind_all(handler);
//Remove all handlers for the all event in the subscribed/connected rpc server
rpcObject.unbind_all();
// Remove `handler` across the subscribed/connected rpc servers
dbridge.rpc.unbind_all(handler);
// Remove all handlers for all events across all subscribed/connected rpc servers
dbridge.rpc.unbind_all();
dbridges:rpc.server.registration.success
Callback parameters
payload:
null
metadata (dict)
:
{
"servername": "serverName" , // (string) serverName to which connection is done.
"eventname": "dbridges:rpc.server.registration.success", // (string) eventName
}
dbridges:rpc.server.registration.fail
Callback parameters
payload: (dberror object)
{
"source": "DBNET_RPC_REGISTER" , // (string) Error source
"code": "ERR_ACCESS_DENIED", // (string) Error code
"message": "" // (string) Error message if applicable.
}
metadata (dict)
:
{
"servername": "serverName" , // (string) serverName to which connection is done.
"eventname": "dbridges:rpc.server.registration.fail",// (string) eventName
}
dbridges:rpc.server.unregistration.success
Callback parameters
payload:
null
metadata (dict)
:
{
"servername": "serverName" , // (string) serverName to which connection is done.
"eventname": "dbridges:rpc.server.unregistration.success", // (string) eventName
}
dbridges:rpc.server.unregistration.fail
Callback parameters
payload: (dberror object)
{
"source": "DBNET_RPC_REGISTER" , // (string) Error source
"code": "ERR_ACCESS_DENIED", // (string) Error code
"message": "" // (string) Error message if applicable.
}
metadata (dict)
:
{
"servername": "serverName" , // (string) serverName to which connection is done.
"eventname": "dbridges:rpc.server.registration.fail",// (string) eventName
}
dbridges:rpc.server.online
Callback parameters
payload:
null
metadata (dict)
:
{
"servername": "serverName" , // (string) serverName to which connection is done.
"eventname": "dbridges:rpc.server.online", // (string) eventName
}
dbridges:rpc.server.offline
Callback parameters
payload:
null
metadata (dict)
:
{
"servername": "serverName" , // (string) serverName to which connection is done.
"eventname": "dbridges:rpc.server.offline",// (string) eventName
}
dbridges:rpc.response.tracker
Only available with rpcObject.
Callback parameters
Return Values | Description |
---|---|
payload | (string) Tracker identifier. which is same as response.id |
metadata | (string) Refer below table |
Error Identifier | Description |
---|---|
RE_18326 | rpc caller is disconnected from dataBridges network and hence cannot process response tracking. |
RE_19219 | rpc caller is disconnected from dataBridges network and hence cannot process response tracking. |
RE_22184 | rpc caller is disconnected from dataBridges network and hence cannot process response tracking. |
RE_22454 | The cf callee is disconnected from dataBridges network |
RE_23101 | The cf callee is disconnected from dataBridges network |
RE_29623 | The cf callee is disconnected from dataBridges network |
RE_29753 | The cf callee is disconnected from dataBridges network |
dbridges:rpc.callee.queue.exceeded
Only available with rpcObject.
Callback parameters
payload: (dberror object)
{
"source": "DBNET_RPC_CALL" , // (string) Error source
"code": "ERR_CALLEE_QUEUE_EXCEEDED", // (string) Error code
"message": "" // (string) Error message if applicable.
}
metadata:
null
dberror:
Source | Code | Description |
---|---|---|
DBLIB_RPC_REGISTER | NETWORK_DISCONNECTED | Connection to dataBridges network is not active. |
DBNET_RPC_REGISTER | ERR_ACCESS_DENIED | dataBridges network reported access violation with access_token function during current operation. |
DBNET_RPC_REGISTER | ERR_FAIL_ERROR | dataBridges network encountered error during current operation. |
DBNET_RPC_CALL | ERR_CALLEE_QUEUE_EXCEEDED | No new rpc calls are being routed by the dataBridges network to the application because the application's current rpc processing queue has already exceeded. Each application connection cannot exceed rpc.queue.maximum. Refer to management console documentation for rpc.queue.maximum details. |
Server Information
isOnline()
rpcObject provides a function to check if the channel is online.
Parameter | Rules | Description |
---|---|---|
string | serverName **OR* pvt:**serverName **OR **prs:**serverName* | *server*Name to which subscription to be done. |
Return Values | Description |
---|---|
boolean | Is the current status of server connection online or offline. |
getServerName()
rpcObject provides a function to get the serverName.
Return Type | Description |
---|---|
string | serverName of connected rpcServer. |
Connect to Server
To use rpc functions, the application has to connect to the rpc endpoint/server. This is done using connect()
function explained below.
connect()
The default method for connecting to a rpc endpoint/server involves invoking the rpc.connect
function of your dataBridges object.
Parameter | Rules | Description |
---|---|---|
string | serverName **OR* pvt:**serverName **OR **prs:**serverName* | *server*Name to which connection to be done. |
Return Type | Description |
---|---|
object | rpcObject which events and related functions can be bound to. |
Exceptions:
Source | Code | Message | Description |
---|---|---|---|
DBLIB_RPC_CONNECT | INVALID_SERVERNAME | Applicable for below conditions 1. serverName is not defined. 2. serverName validation error, length of serverName greater than 64 3. serverName validation error, serverName fails a-zA-Z0-9\.:_- validation.4. serverName contains : and first token is not pvt,prs . | |
DBLIB_RPC_CONNECT | NETWORK_DISCONNECTED | Connection to dataBridges network is not active. | |
DBNET_RPC_CONNECT | ERR_FAIL_ERROR | dataBridges network encountered error during current operation. | |
DBNET_RPC_CONNECT | ERR_ACCESS_DENIED | dataBridges network reported access violation with access_token function during current operation. |
Execute Remote Procedure Call
call()
rpcObject call() function allows you to execute a remote function hosted by RPC endpoint / server using dataBridges library
- passing function parameter as parameter
- while setting an time to live (TTL) for the response
The RPC call() functions supports multi-part response (where the RPC function can send back multiple responses to a single RPC function call) along with exception routine.
rpcSvrClient.call(functionName, parameter, ttlms, (response) => {
console.log('multipart response',response)
}).then((response) => {
console.log('end response', response)
}).catch((err) => {
console.log('exception',err.source, err.code, err.message);
});
//Below example how a application can connect to a RPC endpoint / Server called mathServer and use add, multiply functions.
try {
const myMathServer = dbridge.rpc.connect('mathServer');
} catch (err) {
console.log(err.source, err.code, err.message);
}
let obj = { "num1":44.5, "num2":30};
let inparam = JSON.stringify(obj);
myMathServer.call(add, inparam, ttlms, (response) => {
}).then((response) => {
console.log('response: ', JSON.parse(response));
}).catch((err) => {
console.log('exception',err.source, err.code, err.message);
});
myMathServer.call(multiply, inparam, ttlms, (response) => {
}).then((response) => {
console.log('response: ', JSON.parse(response));
}).catch((err) => {
console.log('exception',err.source, err.code, err.message);
});
def progress(response):
print("multipart: " , response)
def onResult(response):
print("response: ", response)
def onError(error):
print(error.code, error.source, error.message)
try:
p = await rpcClient.call("functionName" , parameter , 10000, progress)
p.then(onResult).catch(onError)
except dBError as e:
print(e.code, e.source, e.message)
# Below example how a application can connect to a RPC endpoint / Server called mathServer and use add, multiply functions.
try:
myMathServer = dbridge.rpc.connect('mathServer');
except dBError as e:
print(e.code, e.source, e.message)
obj = { "num1":44.5, "num2":30};
inparam = json.dumps(obj);
try:
p = await myMathServer.call(add , inparam , 10000, progress)
p.then(onResult).catch(onError)
q = await myMathServer.call(multiply , inparam , 10000, progress)
q.then(onResult).catch(onError)
except dBError as e:
print(e.code, e.source, e.message)
Action<object> iprogress;
IPromise<object> p = rpcClient.call(functionName, parameter, ttlms, iprogress = (response) => {
Console.WriteLine("multipart response {0}",response)
});
p.Then((response) => {
Console.WriteLine("end response {0}", response)
}).Catch((err) => {
Console.WriteLine("exception {0}", err);
});
//Below example how a application can connect to a RPC endpoint / Server called mathServer and use add, multiply functions.
try {
CrpCaller myMathServer = dbridge.rpc.connect('mathServer');
}catch (dBError err) {
Console.WriteLine("{0} , {1} , {2}" , err.source, err.code, err.message);
}
Dictionary<string , int> obj = new Dictionary<string,int32>() { {"num1",44.5} , {"num2",30} };
inparam = new JavaScriptSerializer().Serialize(obj);
Action<object> iprogress;
IPromise<object> p = myMathServer.call(add, inparam, ttlms, iprogress = (response) => {
Console.WriteLine("multipart response {0}",response)
});
p.Then((response) => {
Console.WriteLine("end response {0}", response)
}).Catch((err) => {
Console.WriteLine("exception {0}", err);
});
Action<object> iprogress;
IPromise<object> p = myMathServer.call(multiply, inparam, ttlms, iprogress = (response) => {
Console.WriteLine("multipart response {0}",response)
});
p.Then((response) => {
Console.WriteLine("end response {0}", response)
}).Catch((err) => {
Console.WriteLine("exception {0}", err);
});
Parameter | Expected Value | Description |
---|---|---|
functionName | functionname | (string) Function name as defined in rpc endpoint/ Server . Note - RPC endpoint / server can expose multiple rpc functions. |
parameter | function parameter | (string) if multiple parameters to be passed, This can be done by putting it into array or json and stringify the object. |
ttlms | 1000 | (integer) Time to live in millisecond, timeout value before the call() function throws error timeout. |
Return Values | Description |
---|---|
string | Multipart or final response. in case of error, dberror object is returned. |
Exceptions:
Source | Code | Description |
---|---|---|
DBNET_RPC_CALL | NETWORK_DISCONNECTED | Connection to dataBridges network is not active. |
DBNET_RPC_CALL | RESPONSE_TIMEOUT | Response not received from dataBridges network within defined ttlms . This may be due to dataBridges network or late response from rpcServer |
DBLIB_RPC_CALL | ID_GENERATION_FAILED | Internal Library error. |
DBNET_RPC_CALL | ERR_ACCESS_DENIED | dataBridges network reported access violation during current operation. |
DBRPCCALLEE_RPC_CALL | ERR_error_message | This indicates an exception encountered by the remote RPC function. ERR_error_code will have the details. |
DBNET_RPC_CALL | CLE_NR_10865 | rpc endpoint / server disconnected from dataBridges network. Try again. |
DBNET_RPC_CALL | CLE_NR_30391 | rpc endpoint / server disconnected from dataBridges network. Try again. |
DBNET_RPC_CALL | CLE_QX_41074 | Cannot process the call() because the RPC server (in this case CALLEE) has exceeded outstanding pending rpc call() queue limit. |
DBNET_RPC_CALL | CLE_QX_49467 | Cannot process the call() because the RPC server (in this case CALLEE) has exceeded outstanding pending rpc call() queue limit. |
DBNET_RPC_CALL | CLR_QX_39305 | Cannot process the call() because the RPC server (in this case CALLEE) has exceeded outstanding pending rpc call() queue limit. |
DBNET_RPC_CALL | CLR_QX_39824 | Cannot process the call() because the RPC server (in this case CALLEE) has exceeded outstanding pending rpc call() queue limit. |
DBNET_RPC_CALL | RE_28710 | rpc endpoint / server disconnected from dataBridges network. Try again. |
DBNET_RPC_CALL | AD_48621 | Application does not have access to execute rpc functions. |
System events for rpc call
There are a number of events which are triggered internally by the library, but can also be of use elsewhere. Below are the list of all events triggered by the library.
Below syntax is same for all system events.
// Binding to systemevent on rpcObject
try {
rpcObject.bind('eventName', (payload, metadata) => {
console.log( payload, metadata);
});
} catch(err) {
console.log(err.source, err.code, err.message);
}
// Binding to systemevent on dbridgeObject
try {
dbridge.rpc.bind('eventName', (payload, metadata) => {
console.log( payload, metadata);
});
} catch(err) {
console.log(err.source, err.code, err.message);
}
# Binding to systemevent on rpcObject
async def eventCallback(payload , metadata):
print(payload , metadata)
try:
rpcClient.bind("eventName", eventCallback)
except dBError as e:
print(e.code, e.source, e.message)
# Binding to systemevent on dbridgeObject
try:
dbridge.rpc.bind("eventName", eventCallback)
except dBError as e:
print(e.code, e.source, e.message)
// Binding to systemevent on rpcObject
Action<object,object> iRpcStatus;
try {
rpcSvrClient.bind('eventName', iRpcStatus = (object payload, object metadata) => {
Console.WriteLine("{0} , {1} " , payload, metadata);
});
} catch(dBError err){
Console.WriteLine("{0} , {1}, {2}", err.source, err.code, err.message);
}
// Binding to systemevent on dbridgeObject
try {
dbridge.rpc.bind('eventName', iRpcStatus = (object payload, object metadata) => {
Console.WriteLine("{0} , {1} " , payload, metadata);
});
} catch(dBError err){
Console.WriteLine("{0} , {1}, {2}" , err.source, err.code, err.message);
}
Exceptions:
Source | Code | Description |
---|---|---|
DBLIB_RPC_CALLER | INVALID_EVENTNAME | Invalid Event name. Not in default events. |
DBLIB_RPC_CALLER | INVALID_CALLBACK | Callback is not a function or is not defined. |
bind_all
and unbind_all
bind_all
and unbind_all
work much like bind
and unbind
, but instead of only firing callbacks on a specific event, they fire callbacks on any event, and provide that event in the metadata to the handler along with the payload.
Callback out parameter payload, metadata
details are explained with each event below in this document.
Exceptions:
Source | Code | Description |
---|---|---|
DBLIB_CONNECT_BIND | INVALID_CALLBACK | If "callback function" is not declared or typeof() variable defined is not a "function". |
unbind_all
works similarly to unbind
.
// Remove just `handler` across the rpc server
rpcObject.unbind_all(handler);
//Remove all handlers for the all event in the subscribed/connected rpc server
rpcObject.unbind_all();
// Remove `handler` across the subscribed/connected rpc servers
dbridge.rpc.unbind_all(handler);
// Remove all handlers for all events across all subscribed/connected rpc servers
dbridge.rpc.unbind_all();
# Remove just `handler` across the rpc server
rpcObject.unbind_all(handler)
# Remove all handlers for the all event in the subscribed/connected rpc server
rpcObject.unbind_all()
# Remove `handler` across the subscribed/connected rpc servers
dbridge.rpc.unbind_all(handler)
# Remove all handlers for all events across all subscribed/connected rpc servers
dbridge.rpc.unbind_all()
// Remove just `handler` across the rpc server
rpcObject.unbind_all(handler);
//Remove all handlers for the all event in the subscribed/connected rpc server
rpcObject.unbind_all();
// Remove `handler` across the subscribed/connected rpc servers
dbridge.rpc.unbind_all(handler);
// Remove all handlers for all events across all subscribed/connected rpc servers
dbridge.rpc.unbind_all();
dridges:rpc.server.connect.success
Callback parameters
payload:
null
metadata (dict)
:
{
"servername": "serverName" , // (string) serverName to which connection is done.
"eventname": "dbridges:rpc.server.connect.success", // (string) eventName
}
dbridges:rpc.server.connect.fail
Callback parameters
payload: (dberror object)
{
"source": "DBLIB_RPC_CONNECT" , // (string) Error source
"code": "ACCESS_TOKEN_FAIL", // (string) Error code
"message": "" // (string) Error message if applicable.
}
metadata (dict)
:
{
"servername": "serverName" , // (string) serverName to which connection is done.
"eventname": "dbridges:rpc.server.connect.fail",// (string) eventName
}
dbridges:rpc.server.online
Callback parameters
payload:
null
metadata (dict)
:
{
"servername": "serverName" , // (string) serverName to which connection is done.
"eventname": "dbridges:rpc.server.online", // (string) eventName
}
dbridges:rpc.server.offline
Callback parameters
payload:
null
metadata (dict)
:
{
"servername": "serverName" , // (string) serverName to which connection is done.
"eventname": "dbridges:server.offline",// (string) eventName
}
dberror:
Source | Code | Description |
---|---|---|
DBNET_RPC_CONNECT | ERR_FAIL_ERROR | dataBridges network encountered error during current operation. |
DBNET_RPC_CONNECT | ERR_ACCESS_DENIED | dataBridges network reported access violation during current operation. |