NAME

Setting up your server

Please consult the Catalyst::Tutorial on how to set up your basic application, in which you can use this plugin.

Configuring your server

Next, you can configure the application to do your bidding. First of all, every XMLRPC server needs to have an entrypoint. That is the url that every client needs to post to, in order to post methods to your server.

IMPORTANT: Newer versions of Catalyst add a forward to a default view when no response body has been defined yet, which interferes with this plugin. To fix this, look for the following line in your Root controller:

sub end : ActionClass('RenderView') {}

And simply comment it out:

#sub end : ActionClass('RenderView') {}

Handling incoming method calls

A user could now post to your XMLRPC server as follows, with the bundled rpc_client script in this distribution

$ rpc_client -u http://your.host.tld/rpc -m foo

Your dispatcher now has to deal with the incoming request. The data returned, is whatever is present on the stash.

The below, contrived, example simply returns the method name that was called.

Application XMLRPC Server

This uses your catalyst application as an XMLRPC server, dispatching method calls to your catalyst app, rather than external code. This also allows you to use the XMLRPC plugin transparently, meaning you can post to the same method in your class both via the web, and via XMLRPC.

A user could now post to your XMLRPC server as follows, with the bundled rpc_client script in this distribution, to get to the goto_regex method;

$ rpc_client -u http://your.host.tld/rpc -m foo.bar

Arguments

Any XMLRPC call will have arguments available to it, if the client provided them.

To use our dispatcher exaple again:

package MyApp;
use Catalyst qw/Server Server::XMLRPC/;
sub dispatcher : XMLRPCRegex('.') {
my($self, $c, @args) = @_;
### the XMLRPC arguments, as a list
### same as the ones provides in @args
$aref = $c->req->xmlrpc->args;
### if the arguments provided were a list with 1 single item
### and that item was a hashref, they are added as ->params,
### just like in regular catalyst
$href = $c->req->xmlrpc->params
...
}

Return values

By default, this plugin returns all values that are on the stash. If you wish to have XMLRPC specific return values, put them in $c->stash->{xmlrpc} and that will be the only thing returned to the client.

The rpc_client uses 2 configurable parts: the /rpc appended to the http hostname, which is called the entry point of the server. /rpc is the default (you can configure this to anything you want). The XMLRPC server will only listen to requests that are posted to the entry point.

The second part is the method the client posts to. To reach the method Echo in your package, the client will have to use the method demo.echo; demo as that is the name of your package, and the echo bit as it is the name of your method.

The fictive rpc_client program then just prints out what was returned to it.

More code examples

Browse through the test directory of this distribution, to see some examples of all of the above usage. The relevant modules can be found under t/lib of this distribution.