Catalyst-Plugin-Server

 view release on metacpan or  search on metacpan

README  view on Meta::CPAN

            $c->stash->{xmlrpc} = 'Pong';
        }

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

    * Split XMLRPC methodNames by STRING to find out Controller.
    * Single entrypoint for XMLRPC calls, like http://host.tld/rpc
    * DispatchTypes (attributes) which work much the same as Catalyst attrs
    * XMLRPC Parameter handling transparent to Catalyst parameter handling

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

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

      methodName: hello.world

README  view on Meta::CPAN

Server Accessors
    The following accessors are always available, whether you're in a xmlrpc
    specific request or not

    $c->server->xmlrpc->list_methods
        Returns a HASHREF containing the available xmlrpc methods in
        Catalyst as a key, and the "Catalyst::Action" object as a value.

CATALYST REQUEST
    To make things transparent, we try to put XMLRPC params into the Request
    object of Catalyst. But first we will explain something about the XMLRPC
    specifications.

    A full draft of these specifications can be found on:
    "http://www.xmlrpc.com/spec"

    In short, a xmlrpc-request consists of a methodName, like a subroutine
    name, and a list of parameters. This list of parameters may contain
    strings (STRING), arrays (LIST) and structs (HASH). Off course, these
    can be nested.

README  view on Meta::CPAN

        you can fetch this list within your dispatched-to-subroutine:

          sub echo : XMLRPC {
              my ($self, $c, @args) = @_;
              $c->log->debug($arg[0]);              # Prints first XMLRPC parameter
                                                    # to debug log
          }

    $c->req->parameters
        Because XMLRPC parameters are a LIST, we can't just fill
        $c->req->paremeters. To keep things transparent, we made an extra
        config option what tells the XMLRPC server we can assume the
        following conditions on all XMLRPC requests: - There is only one
        XMLRPC parameter - This XMLRPC parameter is a struct (HASH)

        We will put this STRUCT as key-value pairs into $c->req->parameters.

    $c->req->params
        Alias of $c->req->parameters

    $c->req->param

README  view on Meta::CPAN

TODO
    Make error messages configurable/filterable
        Right now, whatever ends up on $c->error gets returned to the
        client. It would be nice to have a way to filter/massage these
        messages before they are sent back to the client.

    Make stash filterable before returning
        Just like the error messages, it would be nice to be able to filter
        the stash before returning so you can filter out keys you don't want
        to return to the client, or just return a certain list of keys. This
        all to make transparent use of XMLRPC and web easier.

SEE ALSO
    Catalyst::Plugin::Server::XMLRPC::Tutorial, Catalyst::Manual,
    Catalyst::Request, Catalyst::Response, RPC::XML, "bin/rpc_client"

ACKNOWLEDGEMENTS
    For the original implementation of this module:

    Marcus Ramberg, "mramberg@cpan.org" Christian Hansen Yoshinori Sano

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

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<.>:

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

=item $c->server->xmlrpc->list_methods

Returns a HASHREF containing the available xmlrpc methods in Catalyst as
a key, and the C<Catalyst::Action> object as a value.

=back

=head1 CATALYST REQUEST

To make things transparent, we try to put XMLRPC params into the Request
object of Catalyst. But first we will explain something about the XMLRPC
specifications.

A full draft of these specifications can be found on:
C<http://www.xmlrpc.com/spec>

In short, a xmlrpc-request consists of a methodName, like a subroutine
name, and a list of parameters. This list of parameters may contain strings
(STRING), arrays (LIST) and structs (HASH). Off course, these can be nested.

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

  sub echo : XMLRPC {
      my ($self, $c, @args) = @_;
      $c->log->debug($arg[0]);              # Prints first XMLRPC parameter
                                            # to debug log
  }

=item $c->req->parameters

Because XMLRPC parameters are a LIST, we can't B<just> fill
$c->req->paremeters. To keep things transparent, we made an extra config
option what tells the XMLRPC server we can assume the following conditions
on all XMLRPC requests:
- There is only one XMLRPC parameter
- This XMLRPC parameter is a struct (HASH)

We will put this STRUCT as key-value pairs into $c->req->parameters.

=item $c->req->params

Alias of $c->req->parameters

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

Right now, whatever ends up on $c->error gets returned to the client.
It would be nice to have a way to filter/massage these messages before
they are sent back to the client.

=item Make stash filterable before returning

Just like the error messages, it would be nice to be able to filter the
stash before returning so you can filter out keys you don't want to 
return to the client, or just return a certain list of keys. 
This all to make transparent use of XMLRPC and web easier.

=back

=head1 SEE ALSO

L<Catalyst::Plugin::Server::XMLRPC::Tutorial>, L<Catalyst::Manual>, 
L<Catalyst::Request>, L<Catalyst::Response>,  L<RPC::XML>, 
C<bin/rpc_client>

=head1 ACKNOWLEDGEMENTS

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

    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/;