NAME

SYNOPSIS

    package MyApp;
    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';
    }

DESCRIPTION

• 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

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

  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.

ATTRIBUTES

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 "hello.world":

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

XMLRPCLocal

Identical version of attribute "XMLRPC"

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 "ping":

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

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 "say.hello":

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

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: "a.foo.method" "wedoofoohere" "foo.getaround"

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

ACCESSORS

You can query this object as follows:

$c->req->xmlrpc->is_xmlrpc_request

Boolean indicating whether the current request has been initiated via XMLRPC

$c->req->xmlrpc->config

Returns a "Catalyst::Plugin::Server::XMLRPC::Config" object. See the "CONFIGURATION" below on how to use and configure it.

$c->req->xmlrpc->body

The body of the original XMLRPC call

$c->req->xmlrpc->method

The name of the original method called via XMLRPC

$c->req->xmlrpc->args

A list of parameters supplied by the XMLRPC call

$c->req->xmlrpc->result_as_string

The XML body that will be sent back to the XMLRPC client

$c->req->xmlrpc->error

Allows you to set xmlrpc fault code and message

Example:

  $c->req->xmlrpc->error( [ 401 => 'Unauthorized' ] )
    

To return status code 401 with message "Unauthorized"

The default is to return error code 500 on error.

Server Accessors

$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

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.

$c->req->arguments

We will put the list of arguments into $c->req->arguments, thisway 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

Alias of $c->req->parameters

INTERNAL XMLRPC FUNCTIONS

system.listMethods

returns a list of available RPC methods.

DEFINING RETURN VALUES

CONFIGURATION

    Your::App->config( xmlrpc => { key => value } );

You can look up any of the config parameters this package uses at runtime by calling:

    $c->server->xmlrpc->config->KEY

path

This specifies the entry point for your xmlrpc server; all requests are dispatched from there. This is the url any XMLRCP client should post to. You can change this to any "Regex" wish.

The default is: "qr!^(/?)rpc(/|$)!i", which matches on a top-level path begining with "rpc" preceeded or followed by an optional "/", like this:

    http://your-host.tld/rpc
    

prefix

This specifies the prefix of the forward url.

For example, with a prefix of "rpc", and a method "foo", the forward path would be come "/rpc/foo".

The default is '' (empty).

separator

This is a STRING used to split your method on, allowing you to use a hierarchy in your method calls.

For example, with a separator of "." the method call "demo.echo" would be forwarded to "/demo/echo". To make "demo_echo" forward to the same path, you would change the separator to "_",

The default is ".", splitting methods on a single "."

convert_params

Make the arguments in "$c->req->xmlrpc->params" available as "$c->req->params".

Defaults to true.

show_errors

Make system errors in "$c->error" public to the rpc-caller in a XML-RPC faultString. When show_errors is false, and your catalyst app generates a fault, it will return an XML-RPC fault containing error number 500 and error string: "Internal Server Error".

Defaults to false.

xml_encoding

Change the xml encoding send over to the client. So you could change the default encoding to "UTF-8" for instance.

Defaults to "us-ascii" which is the default of "RPC::XML".

allow_nil

Allow undefined values to be encoded as a "nil" element of an empty string.

Defaults to false which is the default of "RPC::XML".

DIAGNOSTICS

Invalid XMLRPC request: No such method

There is no corresponding method in your application that can be forwarded to.

Invalid XMLRPC request %s

There was an error parsing the XMLRPC request

Invalid XMLRPC request: Unknown error

An unexpected error occurred

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

ACKNOWLEDGEMENTS

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

AUTHORS

Actually maintained by Jose Luis Martinez Torres JLMARTIN (jlmartinez@capside.com)

THANKS

BUG REPORTS

LICENSE