1NAME
2    Catalyst::Plugin::Server::XMLRPC -- Catalyst XMLRPC Server Plugin
3
4SYNOPSIS
5        package MyApp;
6        use Catalyst qw/Server Server::XMLRPC/;
7
8        package MyApp::Controller::Example;
9        use base 'Catalyst::Controller';
10
11        sub echo : XMLRPC {                     # available as: example.echo
12            my ( $self, $c, @args ) = @_;
13            $c->stash->{xmlrpc} = join ', ', @args;
14        }
15
16        sub ping : XMLRPCPath('/ping') {        # available as: ping
17            my ( $self, $c ) = @_;
18            $c->stash->{xmlrpc} = 'Pong';
19        }
20
21        sub world : XMLRPCRegex(/hello/) {      # available as: *hello*
22            my ($self, $c) = @_;
23            $c->stash->{xmlrpc} = 'World';
24        }
25
26        sub echo : XMLRPCLocal {                # available as: example.echo
27            my ( $self, $c, @args ) = @_;
28            $c->stash->{xmlrpc} = join ', ', @args;
29        }
30
31        sub ping : XMLRPCGlobal {               # available as: ping
32            my ( $self, $c ) = @_;
33            $c->stash->{xmlrpc} = 'Pong';
34        }
35
36DESCRIPTION
37    XMLRPC Plugin for Catalyst which we tried to make compatible with the
38    way Catalyst works with URLS. Main features are:
39
40    * Split XMLRPC methodNames by STRING to find out Controller.
41    * Single entrypoint for XMLRPC calls, like http://host.tld/rpc
42    * DispatchTypes (attributes) which work much the same as Catalyst attrs
43    * XMLRPC Parameter handling transparent to Catalyst parameter handling
44
45HOW IT WORKS
46    The default behaviour will handle XMLRPC Requests sent to "/rpc" by
47    creating an OBJECT containing XMLRPC specific parameters in
48    "$c->req->xmlrpc".
49
50    Directly after, it will find out the Path of the Action to dispatch to,
51    by splitting methodName by ".":
52
53      methodName: hello.world
54      path      : /hello/world
55
56    From this point, it will dispatch to '/hello/world' when it exists, like
57    Catalyst Urls would do. What means: you will be able to set Regexes,
58    Paths etc on subroutines to define the endpoint.
59
60    We discuss these custom XMLRPC attributes below.
61
62    When the request is dispatched, we will return $c->stash->{xmlrpc} to
63    the xmlrpc client, or, when it is not available, it will return
64    $c->stash to the client. There is also a way of defining $c->stash keys
65    to be send back to the client.
66
67ATTRIBUTES
68    You can mark any method in your Catalyst application as being available
69    remotely by using one of the following attributes, which can be added to
70    any existing attributes, except Private. Remember that one of the
71    mentioned attributes below are automatically also Privates...
72
73    XMLRPC
74        Make this method accessible via XMLRPC, the same way as Local does
75        when using catalyst by URL.
76
77        The following example will be accessible by method "hello.world":
78
79          package Catalyst::Controller::Hello
80          sub world : XMLRPC {}
81
82    XMLRPCLocal
83        Identical version of attribute "XMLRPC"
84
85    XMLRPCGlobal
86        Make this method accessible via XMLRPC, the same way as GLOBAL does
87        when using catalyst by URL.
88
89        The following example will be accessible by method "ping":
90
91          package Catalyst::Controller::Hello
92          sub ping : XMLRPCGlobal {}
93
94    XMLRPCPath('/say/hello')
95        Make this method accessible via XMLRPC, the same way as Path does
96        when using catalyst by URL.
97
98        The following example will be accessible by method "say.hello":
99
100          package Catalyst::Controller::Hello
101          sub hello : XMLRPCPath('/say/hello') {}
102
103    XMLRPCRegex('foo')
104        Make this method accessible via XMLRPC, the same way as Regex does
105        when using catalyst by URL.
106
107        The following example will be accessible by example methods:
108        "a.foo.method" "wedoofoohere" "foo.getaround"
109
110          package Catalyst::Controller::Hello
111          sub hello : XMLRPCPath('foo') {}
112
113ACCESSORS
114    Once you've used the plugin, you'll have an $c->request->xmlrpc accessor
115    which will return an "Catalyst::Plugin::Server::XMLRPC" object.
116
117    You can query this object as follows:
118
119    $c->req->xmlrpc->is_xmlrpc_request
120        Boolean indicating whether the current request has been initiated
121        via XMLRPC
122
123    $c->req->xmlrpc->config
124        Returns a "Catalyst::Plugin::Server::XMLRPC::Config" object. See the
125        "CONFIGURATION" below on how to use and configure it.
126
127    $c->req->xmlrpc->body
128        The body of the original XMLRPC call
129
130    $c->req->xmlrpc->method
131        The name of the original method called via XMLRPC
132
133    $c->req->xmlrpc->args
134        A list of parameters supplied by the XMLRPC call
135
136    $c->req->xmlrpc->result_as_string
137        The XML body that will be sent back to the XMLRPC client
138
139    $c->req->xmlrpc->error
140        Allows you to set xmlrpc fault code and message
141
142Server Accessors
143    The following accessors are always available, whether you're in a xmlrpc
144    specific request or not
145
146    $c->server->xmlrpc->list_methods
147        Returns a HASHREF containing the available xmlrpc methods in
148        Catalyst as a key, and the "Catalyst::Action" object as a value.
149
150CATALYST REQUEST
151    To make things transparent, we try to put XMLRPC params into the Request
152    object of Catalyst. But first we will explain something about the XMLRPC
153    specifications.
154
155    A full draft of these specifications can be found on:
156    "http://www.xmlrpc.com/spec"
157
158    In short, a xmlrpc-request consists of a methodName, like a subroutine
159    name, and a list of parameters. This list of parameters may contain
160    strings (STRING), arrays (LIST) and structs (HASH). Off course, these
161    can be nested.
162
163    $c->req->arguments
164        We will put the list of arguments into $c->req->arguments, thisway
165        you can fetch this list within your dispatched-to-subroutine:
166
167          sub echo : XMLRPC {
168              my ($self, $c, @args) = @_;
169              $c->log->debug($arg[0]);              # Prints first XMLRPC parameter
170                                                    # to debug log
171          }
172
173    $c->req->parameters
174        Because XMLRPC parameters are a LIST, we can't just fill
175        $c->req->paremeters. To keep things transparent, we made an extra
176        config option what tells the XMLRPC server we can assume the
177        following conditions on all XMLRPC requests: - There is only one
178        XMLRPC parameter - This XMLRPC parameter is a struct (HASH)
179
180        We will put this STRUCT as key-value pairs into $c->req->parameters.
181
182    $c->req->params
183        Alias of $c->req->parameters
184
185    $c->req->param
186        Alias of $c->req->parameters
187
188INTERNAL XMLRPC FUNCTIONS
189    The following system functions are available to the public.,
190
191    system.listMethods
192        returns a list of available RPC methods.
193
194DEFINING RETURN VALUES
195    The XML-RPC response must contain a single parameter, which may contain
196    an array (LIST), struct (HASH) or a string (STRING). To define the
197    return values in your subroutine, you can alter $c->stash in three
198    different ways.
199
200  Defining $c->stash->{xmlrpc}
201    When defining $c->stash->{xmlrpc}, the XMLRPC server will return these
202    values to the client.
203
204  When there is no $c->stash->{xmlrpc}
205    When there is no "$c->stash->{xmlrpc}" set, it will return the complete
206    "$c->stash"
207
208CONFIGURATION
209    The XMLRPC Plugin accepts the following configuration options, which can
210    be set in the standard Catalyst way (See "perldoc Catalyst" for
211    details):
212
213        Your::App->config( xmlrpc => { key => value } );
214
215    You can look up any of the config parameters this package uses at
216    runtime by calling:
217
218        $c->server->xmlrpc->config->KEY
219
220    path
221        This specifies the entry point for your xmlrpc server; all requests
222        are dispatched from there. This is the url any XMLRCP client should
223        post to. You can change this to any "Regex" wish.
224
225        The default is: "qr!^(/?)rpc(/|$)!i", which matches on a top-level
226        path begining with "rpc" preceeded or followed by an optional "/",
227        like this:
228
229            http://your-host.tld/rpc
230
231    prefix
232        This specifies the prefix of the forward url.
233
234        For example, with a prefix of "rpc", and a method "foo", the forward
235        path would be come "/rpc/foo".
236
237        The default is '' (empty).
238
239    separator
240        This is a STRING used to split your method on, allowing you to use a
241        hierarchy in your method calls.
242
243        For example, with a separator of "." the method call "demo.echo"
244        would be forwarded to "/demo/echo". To make "demo_echo" forward to
245        the same path, you would change the separator to "_",
246
247        The default is ".", splitting methods on a single "."
248
249    convert_params
250        Make the arguments in "$c->req->xmlrpc->params" available as
251        "$c->req->params".
252
253        Defaults to true.
254
255    show_errors
256        Make system errors in "$c->error" public to the rpc-caller in a
257        XML-RPC faultString. When show_errors is false, and your catalyst
258        app generates a fault, it will return an XML-RPC fault containing
259        error number 500 and error string: "Internal Server Error".
260
261        Defaults to false.
262
263    xml_encoding
264        Change the xml encoding send over to the client. So you could change
265        the default encoding to "UTF-8" for instance.
266
267        Defaults to "us-ascii" which is the default of "RPC::XML".
268
269DIAGNOSTICS
270    Invalid XMLRPC request: No such method
271        There is no corresponding method in your application that can be
272        forwarded to.
273
274    Invalid XMLRPC request %s
275        There was an error parsing the XMLRPC request
276
277    Invalid XMLRPC request: Unknown error
278        An unexpected error occurred
279
280TODO
281    Make error messages configurable/filterable
282        Right now, whatever ends up on $c->error gets returned to the
283        client. It would be nice to have a way to filter/massage these
284        messages before they are sent back to the client.
285
286    Make stash filterable before returning
287        Just like the error messages, it would be nice to be able to filter
288        the stash before returning so you can filter out keys you don't want
289        to return to the client, or just return a certain list of keys. This
290        all to make transparent use of XMLRPC and web easier.
291
292SEE ALSO
293    Catalyst::Plugin::Server::XMLRPC::Tutorial, Catalyst::Manual,
294    Catalyst::Request, Catalyst::Response, RPC::XML, "bin/rpc_client"
295
296ACKNOWLEDGEMENTS
297    For the original implementation of this module:
298
299    Marcus Ramberg, "mramberg@cpan.org" Christian Hansen Yoshinori Sano
300
301AUTHORS
302    Jos Boumans (kane@cpan.org)
303
304    Michiel Ootjers (michiel@cpan.org)
305
306BUG REPORTS
307    Please submit all bugs regarding "Catalyst::Plugin::Server" to
308    "bug-catalyst-plugin-server@rt.cpan.org"
309
310LICENSE
311    This library is free software, you can redistribute it and/or modify it
312    under the same terms as Perl itself.
313
314