The Server Process hosts a JavaScript runtime (currently a Mozilla Rhino implementation) capable of loading scripts and exercising HUGIN and script objects. This can be remotely controlled from the user web application running in the browser.
Using the remote procedure call feature, we can move the parts of the user code that performs many HUGIN API function calls from running in the browser to run locally in the Server Process. Thus mitigating the HTTP communication overhead induced by having to perform many HUGIN API calls from browser script code.
The remote procedure call feature is experimental and must be explicitly enabled on the server, see the options section on the About page.
All HUGIN objects (Domains and Nodes etc.) that at some point have visited the scope of the remote script object will be garbage collected when the remote script object itself is deleted or garbage collected.
The only supported types are the basic JavaScript primitives (numbers, strings, arrays, and object literals) and HUGIN objects (Domains, Nodes, etc.). At each function invocation, the arguments and result communicated between browser-side and server-side JavaScript runtimes, except for HUGIN objects, will be copies of the corresponding primitive JavaScript data structures.
The web application running in the browser-side JavaScript runtime can communicate with the script object living in the server-side JavaScript runtime. This communication is done using a proxy object (a RemoteObject) in the browser-side runtime which has a number of stubs that mirror the methods exposed by the server-side remote object. The stubs on the RemoteObject are dynamically discovered and exposed. So if the server-side remote object provides a method ‘.giveMeFive()’, then the browser-side RemoteObject will be augmented with a similar method stub ‘.giveMeFive()’. Thus if we invoke ‘.giveMeFive()’ on the RemoteObject then in turn the server-side ‘.giveMeFive()’ is invoked, and results are transparently communicated back as the return value for the RemoteObject ‘.giveMeFuve()’ stub.
In this example we have two script files, one which will be evaluated in the server-side JavaScript runtime and another evaluated in the browser-side JavaScript runtime.
//file: serverSideScript.js function MyObject(constructorArg) { this.giveMeFive = function() { return 5; }; this.giveMeConstructorArg = function() { return constructorArg; }; } //file: browserSideScript.js //... var hapi; // a HAPI instance var rpc = new HuginRPC(hapi); //create the RemoteObject proxy object var remoteObject = rpc.getNewRemoteScriptObject("/path/to/serverSideScript.js", "MyObject", "an argument string"); //the serverSideScript.js script is loaded server-side, and 'new MyObject("an argument string")' is called
We can now invoke a method on a remote script object using the RemoteObject proxy object just as if it was a plain object in the browser-side JavaScript runtime.
//file: browserSideScript.js //... alert(remoteObject.giveMeFive()); //prints '5' alert(remoteObject.giveMeConstructorArg()); //prints 'an argument string'
Methods on the remote script object can also be invoked asynchronously, this means that invoking the stub returns immediately and a callback function is used to handle the result when the remote script object function returns.
//file: browserSideScript.js //... //this is our callback function function alertCallback(result) { var remoteFunctionReturned = result.invocationResult(); alert(remoteFunctionReturned); } //dispatch the function calls remoteObject.Async(alertCallback).giveMeFive(); remoteObject.Async(alertCallback).giveMeConstructorArg();
JavaScript RPC Runtime | The Server Process hosts a JavaScript runtime (currently a Mozilla Rhino implementation) capable of loading scripts and exercising HUGIN and script objects. |
HuginRPC | The HuginRPC is the main entry point for spawning remote script objects in the Server Process. |
Functions | |
HuginRPC | Initialize a new HuginRPC instance. |
getNewRemoteScriptObject | Remotely load a JavaScript file, invoke a JavaScript object constructor, and return a RemoteObject reference to the remotely constructed object. |
RemoteObject | A RemoteObject is a reference to a specific script object living in the Server Process. |
Functions | |
deleteObject | Deletes this RemoteObject (as well as all HUGIN objects in the RemoteObjects scope). |
reflectMethodStubs | Inspects the set of functions attached to the server-side object and automagically creates corresponding method stubs for discovered functions on this RemoteObject. |
Async | Hook for asynchronously invoking a function on the remote script object. |
The HuginRPC is the main entry point for spawning remote script objects in the Server Process.
Functions | |
HuginRPC | Initialize a new HuginRPC instance. |
getNewRemoteScriptObject | Remotely load a JavaScript file, invoke a JavaScript object constructor, and return a RemoteObject reference to the remotely constructed object. |
this.getNewRemoteScriptObject = function getNewRemoteScriptObject( scriptUrl, constructorName //, arg0, arg1, ..., argN )
Remotely load a JavaScript file, invoke a JavaScript object constructor, and return a RemoteObject reference to the remotely constructed object.
The RemoteObject returned is a reference to the remote object constructed by the ‘new’ call.
scriptUrl | path to the script to load. The path can be a URL relative to the current web page location or an absolute URL. |
constructorName | the name of the remote script object constructor. |
arg0, arg1, ..., argN | the arguments passed to the remote script object constructor. |
a RemoteObject object
var rpc; //a HuginRPC instance var remoteObject = rpc.getNewRemoteScriptObject("some/path/to/a/script.js", "MyObject", "");
A RemoteObject is a reference to a specific script object living in the Server Process. The RemoteObject has method stubs facilitating remote procedure calls to the server-side remote scripting object. The exact method stubs are determined at remote object construction time by automatic reflecting the function properties of the remote scripting object, or at some later point using RemoteObject.reflectMethodStubs().
For instructions on how to perform remote procedure calls, refer to the description text found under JavaScript RPC Runtime.
Functions | |
deleteObject | Deletes this RemoteObject (as well as all HUGIN objects in the RemoteObjects scope). |
reflectMethodStubs | Inspects the set of functions attached to the server-side object and automagically creates corresponding method stubs for discovered functions on this RemoteObject. |
Async | Hook for asynchronously invoking a function on the remote script object. |
this.deleteObject = function deleteObject()
Deletes this RemoteObject (as well as all HUGIN objects in the RemoteObjects scope).
void
r.deleteObject();
this.reflectMethodStubs = function reflectMethodStubs()
Inspects the set of functions attached to the server-side object and automagically creates corresponding method stubs for discovered functions on this RemoteObject. Normally one does not need to explicitly invoke this function. But in cases where the remote script object populates additional methods after its constructor has run, this function must be called to discover new methods and create stubs before they can be invoked over RPC.
list of method names discovered
r.reflectMethodStubs();
this.Async = function Async( callback )
Hook for asynchronously invoking a function on the remote script object.
callback | a callback function(result), to be invoked when the remote script object function returns. |
an object containing asynchronous function stubs.
var rpc; //a HuginRPC instance var remoteObject = rpc.getNewRemoteScriptObject("some/path/to/a/script.js", "MyObject", ""); function myCallback(result) { //handle when function call completes try { var computedValue = result.invocationResult(); //do stuff //... } catch (error) { //the remote function may have thrown an error, handle this alert("An error occured: " + e.name + "\n" + e.message); } } remoteObject.Async(myCallback).performComputation();
Initialize a new HuginRPC instance.
function HuginRPC( hapi )
Remotely load a JavaScript file, invoke a JavaScript object constructor, and return a RemoteObject reference to the remotely constructed object.
this.getNewRemoteScriptObject = function getNewRemoteScriptObject( scriptUrl, constructorName //, arg0, arg1, ..., argN )
Deletes this RemoteObject (as well as all HUGIN objects in the RemoteObjects scope).
this.deleteObject = function deleteObject()
Inspects the set of functions attached to the server-side object and automagically creates corresponding method stubs for discovered functions on this RemoteObject.
this.reflectMethodStubs = function reflectMethodStubs()
Hook for asynchronously invoking a function on the remote script object.
this.Async = function Async( callback )