view release on metacpan or  search on metacpan

lib/Catalyst/Plugin/Server/XMLRPC/Tutorial.pod  view on Meta::CPAN

=head2 Dispatching XMLRPC Server

This is the easiest configuration, that uses your catalyst app as
B<just> an XMLRPC server. This means that the XMLRPC server will
just be used to dispatch to library code somewhere else.

=head3 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 C<sub dispatcher>, which will be shown in the 
server startup as follows:

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

B<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') {}

=head3 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;
    }

=head2 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.

=head3 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
C<goto_regex> method;