Configuring your server

By default, this is "http://your.host.tld/rpc"

The full configuration options are described in Catalyst::Plugin::Server::XMLRPC.

Dispatching XMLRPC Server

Seting up the server

You could set this up as follows:

    package MyApp;
    use Catalyst    qw/Server Server::XMLRPC/;

    sub dispatcher : XMLRPCRegex('.') {
        ...
    }

Now, every xmlrpc call that gets posted to your application, will be handled by the "sub dispatcher", which will be shown in the server startup as follows:

    [catalyst] [debug] Loaded XMLRPCRegex actions:
    .---------------------------+----------------------------------.
    | XMLRPCRegex               | Private                          |
    +---------------------------+----------------------------------+
    | .                         | /dispatcher                      |
    '---------------------------+----------------------------------'

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.

    sub dispatcher : XMLRPCRegex('.') {
        my ($self, $c, @args) = @_;
        $c->stash->{ method } = $c->request->xmlrpc->method;
    }

Application XMLRPC Server

Setting up the server

You could set this up as follows:

    package MyApp;
    use Catalyst    qw/Server Server::XMLRPC/;

    package MyApp::Controller::RPC;

    ### available as rpc.path
    sub goto_path : XMLRPCPath('/rpc/path') {
        my ($self, $c, @args) = @_;
        ...
    }
    
    ### available as any method containing 'foo'
    sub goto_regex : XMLRPCRegex('foo') {
        my ($self, $c, @args) = @_;
        ...
    }
    
    ### available as rpc.goto_local
    sub goto_local : XMLRPCLocal {
        my ($self, $c, @args) = @_;
        ...
    }
    
    ### avaiable as goto_global
    sub goto_global : XMLRPCGlobal {
        my ($self, $c, @args) = @_;
        ...
    }

This gives you several method calls, available as rpc calls, as also shown by the catalyst server startup messages:

    [catalyst] [debug] Loaded XMLRPCPath Method actions:
    .---------------------------+---------------------------------------.
    | XMLRPCPath Method         | Private                               |
    +---------------------------+---------------------------------------+
    | goto_global               | /rpc/goto_global                      |
    | rpc.goto_local            | /rpc/goto_local                       |
    | rpc.path                  | /rpc/goto_path                        |
    '---------------------------+---------------------------------------'
    
    [catalyst] [debug] Loaded XMLRPCRegex actions:
    .---------------------------+---------------------------------------.
    | XMLRPCRegex               | Private                               |
    +---------------------------+---------------------------------------+
    | foo                       | /rpc/goto_regex                       |
    '---------------------------+---------------------------------------'

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

Standard remote call

    package MyApp::Controller::Demo;

    sub echo : XMLRPC {
        my ($self, $c) = @_
        @args = @{ $c->req->xmlrpc->args };

        $c->stash->{xmlrpc} = \@args;
    }

    ### meanwhile, in an rpc client far away
    $ rpc_client -u http://your-host.tld/rpc -m demo.echo test
    Output: test

Let's break it down line by line;

    package MyApp::Controller::Demo;

This is the package you are currently working in. The XMLRPC server will dispatch, by default, to something under your "MyApp::Controller" namespace.

    sub echo : XMLRPC {

You now have a method that's available via XMLRPC, thanks to the "XMLRPC" attribute.

        @args = @{ $c->req->xmlrpc->args };

        $c->stash->{xmlrpc} = \@args;

First, we will retrieve our arguments from the XMLRPC::Server object.

We then set $c->stash->{xmlrpc} to @args, in good echo server tradition.

    ### meanwhile, in an rpc client far away
    $ rpc_client -u http://your-host.tld/rpc -m demo.echo test
    -----------------Output-----------
    $VAR1 = 'test';

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