Documentation

6.1 Using XRPC from JavaScript

WARNING: XRPC still makes use of the old compiler backend and does not use the optimizing algebraic query compiler. Therefore, its query performance can sometimes be inferior to other queries handled by MonetDB/XQuery. Also, as the old compiler backend is gradually phased out, it gets to be less well-maintained and tested in general. Use with caution. We hope to port XRPC to the algebra backend soon.

XRPC allows to make SOAP calls to a MonetDB/XQuery server. With XRPC you can invoke predefined XQuery Functions. The XQuery function must be defined in an XQuery Module file that should be accessible by the server via an URL.

Because XRPC makes use of such predefined modules, MonetDB/XQuery can pre-process the module and perform query optimization beforehand. This makes XRPC a highly efficient API, allowing in simple queries for response times of for less than 10 milliseconds.

By default when MonetDB/XQuery starts, its HTTP server is started on port 50001. It serves out the directory is in share/xrpc/. This HTTP server interprets POST requests that have a local URI starting with /xrpc as XRPC requests. Inside the POST request body is a SOAP request, and the returned answer is a SOAP message again. This API creates a valid SOAP request, sends it, and calls a callback function when the response comes in.

6.1.1 API

In the file share/xrpc/admin/xrpcwebclient.js you find a JavaScript library that works with both FireFox and Internet Explorer.

For safety reasons, Internet Explorer and FireFox usually only allow SOAP requests to be sent from Javascript to the same host as the web-server!!. This restriction also affects this JavaScript XRPC API.

The main function is XRPC(), it takes the URL of a MonetDB/XQuery server.

function XRPC(posturl,    /* Your XRPC server. Usually: "http://yourhost:yourport/xrpc" */
              module,     /* (logical) module namespace URI (NB: do not use the user defined prefix of the module!). Must match XQuery module definition! */
              moduleurl,  /* module (physical) at-hint URL. Module file must be here! */
              method,     /* method name (matches function name in module) */
              arity,      /* arity of the method, i.e. number of parameters. */
              call,       /* one or more XRPC_CALL() parameter specs (concatenated strings) */
              callback);  /* a JavaScript callback function that should be called when the response message is received*/

What you get back is the full SOAP result message described in TODO. You can process it in Javascript as you like.

The function parameters is a string that can be constructed using the following helper functions:

function XRPC_CALL(parameters);
function XRPC_SEQ(sequence);
function XRPC_ATOM(type, value);
function XRPC_ELEMENT(value);

Each set of parameters is enclosed in an XRPC_CALL. It is in fact possible to pass multiple such XRPC_CALLS. This means the function will be invoked multiple times and you will get back multiple result sequences (one for each call).

For each parameter in a function call, you specify a sequences, i.e. an XRPC_SEQ. Inside a sequence, you find zero or more XRPC_ATOMs and/or XRPC_ELEMENTs. For atomic types, the type is assumed to be from the xs namespace, e.g. passing 'integer' gives you an xs:integer.

6.1.2 Example

You must include the file share/xrpc/admin/xrpcwebclient.js in your HTML as follows:

<html>
    <head>
        <script type="text/javascript" src="xrpcwebclient.js">
            var clnt = new XRPCWebClient();
        </script>
    </head>

    ..

Then you fire off from Javascript an XRPC call, e.g. calling the add(100,200) function defined in an XQuery Module.

XRPC('http://localhost:50001',
     'xrpc-test-function',
     'http://www.monetdb.nl/XQuery/files/xrpc-mod.xq",
     'add',
     '2',
     XRPC_CALL(XRPC_SEQ(XRPC_ATOM('integer', '100') + XRPC_ATOM('integer', '200'))), 
     exampleCallback);

exampleCallback(result) {
    alert(result);
}

The MonetDB/XQuery administrative GUI (http://localhost:5001/admin/) is fully programmed using Javascript and XRPC. You can study its code in share/xrpc/admin/admin.js.