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