jsxmlRPC :: API Reference :: xmlrpc.js
Class: XmlRpc
This is the central central object of the implementation and most
likely you'll only need to use a single function (getObject
) of this Object.
Class method: XmlRpc.getOject (url, functionNameArr)
This class function returns a proxy object which will provide a Javascript function for every method provided by an XML-RPC webservice.
It tries to find out about the provided methods using the XML-RPC
system.listMethods
Introspection facilities. If the webservice doesn't
provide introspection, it's necessary to manually provide the function
names.
In case the names of the XML-RPC methods contain a dot (.), for example
in order to call methods like system.listMethods
, the dot will be
mapped to an underscore in the name of the Javascript method.
Parameter url
The URL that the webservice is located at.
Parameter functionNameArr
An optional list of method names that corresponds to the XML-RPC methods
provided at url
. If this parameter is not provided, getObject
tries
to determine the function names by calling system.listMethods
at the
url. The returned Object will have functions named after the elements of
this array. Possible dots (.) in XML-RPC method names are mapped to
underscores (_) in Javascript. If your webservice has two functions with
identical names save the underscore (one.method
and one_method
),
you're out of luck, the last method name in the array will be the one
mapped.
To clarify: the function names that are passed to the method are the XML-RPC names (the one's with the dots in them). The functions in the returned object will have an underscore in their name.
Returns
This function returns an instance of XmlRpc
that responds to all
XML-RPC methods provided by the webservice.
The stub functions corresponding to the XML-RPC methods can be called in a synchronized fashion or asynchronously.
In synchronized calls, the function doesn't return until the response from the server is received. This is the normal and expected behavior for a Javascript function.
Asynchronous calls are necessary when implementing AJAX style services. In order to call functions in an asynchronous manner, all that's necessary is to provide a callback function as the last parameter to the function call. The stub function returns immediately, and as soon as an answer arrives from the webservice, the callback function is invoked with the value returned by the webservice.
Usage
The example below constructs a proxy object that connects to the
hypothetical helloWorld
webservice locate at
/webservices/helloWorld.cgi
. The helloWorld
webservice provides the
methods helloWorld
and goodbye
, both of which require a name
parameter and return a string
:
url = "/webservices/helloWorld.cgi"
methNames = ["helloWorld", "goodbye"]
str1 = "tim"
// in case the helloWorld.cgi provides
// introspection, it's not necessary to
// pass in the methNames array.
hw = XmlRpc.getObject(url, methNames)
/* synchronized call */
str2 = hw.helloWorld(str1)
// str2 will contain "hello, tim", which
// is what the webservice returns, as soon
// as the answer arrives.
//asynchronous call
hw.helloWorld(str1, function(x){
alert(x)
})
// this function call returns immediately,
// as soon as the answer returns from the
// webservice, an alert box will pop up.
alert ("you'll see this before you see hello, world")
If you need namespaces separated by dots as method names:
url = "/webservices/helloWorld.cgi"
methNames = ["namespaced.method", "another_method"]
hw = XmlRpc.getObject(url, methNames)
hw.namespaced_method()
hw.another_method()
Constructor
XmlRpc
is invoked by getObject
, but
it can also be invoked manually.
Parameter: url
The URL where the webservice this object is based on is located.
Usage
hw = new XmlRpc("/webservices/helloWorld.cgi")
Instance Method: call (methodName[, parameter...][, callback]] )
This function calls the named method on the webservice with the optionally provided parameters. If a callback function is passed as the last parameter, the webservice is called in an asynchronous manner, the callback function being invoked when the request to the webservice returns. The callback is passed a single parameter that corresponds to to the value returned by the webservice.
Internally, all that getObject
does is add functions to an instance of
XmlRpc
which invoke the method call
with their name as the first
parameter, followed by the parameters to pass to the webservice,
followed by an optional callback function.
Parameter methodName
The name of the webservice method to call.
Parameter parameter
(optional)
A variable number of parameters to pass to the webservice.
Parameter callback
(optional)
If provided, the webservice will be invoked in an asynchronous fashion.
Usage
The following code is functionally identical the code using the generated stub methods above.
url = "/webservices/helloWorld.cgi"
str1 = "tim"
hw = new XmlRpc(url)
/* synchronized call */
str2 = hw.call("helloWorld",str1)
//asynchronous call
hw.call("helloWorld", str1, function(x){
alert(x)
})
Instance Method: onerror (e)
The callback function to invoke when webservice methods are being called in an asynchronous fashion. You see, "normal" well-behaved function calls return when they're done and if anything strange happens before they're done, they'll throw an exception.
But in asynchronous operations, when you're providing a callback function, the Javascript function call returns long before the webservice call is finished and there's no place where potential exceptions can get thrown, let alone caught.
Unless of course, you provided a nice function to handle the error and
assigned it to onerror
. It should go without saying that you shouldn't
invoke this method yourself.
Default
If you don't provide an onerror
function, one of two things can
happen. First, in case you make all your calls synchronized, nothing
happens, because you catch the exception yourself. If you choose to make
asynchronous calls though, and an exception gets thrown, that exception
will be passed to the underlying Request
's default error handler,
which will pass the exception to alert()
, which is annoying.
Usage
...
hw = XmlRpc.getObject(url, methNames)
hw.onerror = function (e) {
//What's more annoying than alert()?
alert(e)
alert(e)
// Two alerts !
}
// only need to assign this once, unless you'd
// prefer different error handlers for each call.
...
hw.helloWorld("your_name_here", function (s) {
// do whatever
// running out of helloWorld examples
})