jsRPC Introduction

jsRPC consists of Javascript classes that enable easy interaction with XML-RPC based webservices. These classes allow webdevelopers to access webservices just like he or she would access native Javascript functions.

The following pages describe the library in more detail:

• Reference of functions in the library
• Reference of XMLRPC to Javascript mappings
• Have a look at the download page.
• There's also a page with real, live examples

This example assumes only a rough understanding of XML-RPC. The mechanisms provided by XML-RPC are explained in more detail elsewhere.

Let's start with a "hello world" example. We'll pretend the very useful "hello world" webservice is located at /webservice.cgi on your server. It provides XML-RPC a service with the methodname hello and the function returns the much loved expected "hello, world" string. The Javascript code to use the webservice would look as follows:

retValue = helloWorld.hello() // returns "hello, world"

That's it! The variable retValue will contain the string returned by the webservice. That's a whole lot easier than having to deal with the following XML being passed around:

<!-- Request -->
<?xml version="1.0"?>
<methodCall>
    <methodName>hello</methodName>
</methodCall>

<!-- Response -->

<?xml version="1.0" ?>
<methodResponse>
    <params>
        <param><value><string>hello, world</string></value></param>
    </params>
</methodResponse>.

Next we'll assume /webservice.cgi script also provides a function called hello2, a far more advanced webservice that takes a string (probably containing your name) as a parameter and returns an XML-RPC struct containing the members helloworld, the archetypical "hello, $name", length, an integer value containing the length of the string that was passed in as a parameter, and finally date an XML-RPC dateTime.iso8601 type that returns the current date. Below is the necessary code:

retValue = helloWorld.hello() // returns "helloworld"
retValue2 = helloWorld.hello2("your name here")
helloWorldString = retValue2.helloworld // "hello, your name here"
helloWorldLength = retValue2.length // 14
helloWorldDate = retValue2.date // the current date

So where did this helloWorld object come from all of the sudden, and who taught it to speak XML-RPC?

There are two things you need to do before transparently using XML-RPC in Javascript. First, you need to include the library providing the XMLRPC functionality:

<script src="all_scripts.js" type="text/javascript"></script>

Second, you'll need to create a stub object for the webservice you need to access. Don't worry, it's only one line of code:

helloWorld = XmlRpc.getObject("webservice.cgi")

The parameter passed to XmlRpc.getObject is the URL of the webservice. The function automatically creates a stub object with Javascript functions for every XML-RPC method provided by the webservice. jsRPC determines what methods are available at the url using the system.listMethods introspection extension to the XML-RPC standard. In case your webservice doesn't provide introspection capabilities, you need to find out the methodnames through other means and pass them in an array as a second parameter, like this:

helloWorld = XmlRpc.getObject("webservice.cgi", ["hello", "hello2"])

All marshaling between Javascript and XML-RPC data types is handled transparently. See the reference for more information about how datatypes are mapped to one another.

"Don't you know what AJAX is, idiot? I want to everything to be asynchronous?"

Nothing would be easier. If you'd like your calls to the webservice methods to be asynchronous, all you have to do is to add a callback function after the last parameter when calling the method. Everything else is the same, but the webservice call returns immediately. When the answer is received from the webservice, it gets converted to Javascript as before and is passed to the callback function:

f = function (x) {
    // do something spectacular here
    // and become richer than Google.
    alert (x.helloworld)
    alert (x.length)
    alert (x.date)
}

retValue2 = helloWorld.hello2("your name here", f)

alert ("You'll see this before you see the response from the server")

That's right, no if (req.readyState == 4) or if (req.status == 200) or any other of that tedium.

Comment on this page: