view release on metacpan or  search on metacpan

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

    use Catalyst qw/Server Server::XMLRPC/;

    package MyApp::Controller::Example;
    use base 'Catalyst::Controller';

    sub echo : XMLRPC {                     # available as: example.echo
        my ( $self, $c, @args ) = @_;
        $c->stash->{xmlrpc} = join ', ', @args;
    }

    sub ping : XMLRPCPath('/ping') {        # available as: ping
        my ( $self, $c ) = @_;
        $c->stash->{xmlrpc} = 'Pong';
    }

    sub world : XMLRPCRegex(/hello/) {      # available as: *hello*
        my ($self, $c) = @_;
        $c->stash->{xmlrpc} = 'World';
    }

    sub echo : XMLRPCLocal {                # available as: example.echo
        my ( $self, $c, @args ) = @_;
        $c->stash->{xmlrpc} = join ', ', @args;
    }

    sub ping : XMLRPCGlobal {               # available as: ping
        my ( $self, $c ) = @_;
        $c->stash->{xmlrpc} = 'Pong';
    }

=head1 DESCRIPTION

XMLRPC Plugin for Catalyst which we tried to make compatible with the
way Catalyst works with URLS. Main features are:

=over 4

=item * Split XMLRPC methodNames by STRING to find out Controller.

=item * Single entrypoint for XMLRPC calls, like http://host.tld/rpc

=item * DispatchTypes (attributes) which work much the same as Catalyst attrs

=item * XMLRPC Parameter handling transparent to Catalyst parameter handling

=back

=head1 HOW IT WORKS

The default behaviour will handle XMLRPC Requests sent to C</rpc> by creating
an OBJECT containing XMLRPC specific parameters in C<< $c->req->xmlrpc >>.

Directly after, it will find out the Path of the Action to dispatch to, by
splitting methodName by C<.>:

  methodName: hello.world
  path      : /hello/world

From this point, it will dispatch to '/hello/world' when it exists,
like Catalyst Urls would do. What means: you will be able to set Regexes,
Paths etc on subroutines to define the endpoint.

We discuss these custom XMLRPC attributes below.

When the request is dispatched, we will return $c->stash->{xmlrpc} to the
xmlrpc client, or, when it is not available, it will return $c->stash to
the client. There is also a way of defining $c->stash keys to be send back
to the client.

=head1 ATTRIBUTES

You can mark any method in your Catalyst application as being
available remotely by using one of the following attributes,
which can be added to any existing attributes, except Private.
Remember that one of the mentioned attributes below are automatically
also Privates...

=over 4

=item XMLRPC

Make this method accessible via XMLRPC, the same way as Local does
when using catalyst by URL.

The following example will be accessible by method C<< hello.world >>:

  package Catalyst::Controller::Hello
  sub world : XMLRPC {}

=item XMLRPCLocal

Identical version of attribute C<XMLRPC>

=item XMLRPCGlobal

Make this method accessible via XMLRPC, the same way as GLOBAL does
when using catalyst by URL.

The following example will be accessible by method C<< ping >>:

  package Catalyst::Controller::Hello
  sub ping : XMLRPCGlobal {}

=item XMLRPCPath('/say/hello')

Make this method accessible via XMLRPC, the same way as Path does
when using catalyst by URL.

The following example will be accessible by method C<< say.hello >>:

  package Catalyst::Controller::Hello
  sub hello : XMLRPCPath('/say/hello') {}

=item XMLRPCRegex('foo')

Make this method accessible via XMLRPC, the same way as Regex does
when using catalyst by URL.

The following example will be accessible by example methods:
C<< a.foo.method >>
C<< wedoofoohere >>