Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Catalyst::Plugin::ServUserXContributed PerlCatalyst::Plugin::Server::XMLRPC(3)

NAME
       Catalyst::Plugin::Server::XMLRPC	-- Catalyst XMLRPC Server Plugin

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
       XMLRPC Plugin for Catalyst which	we tried to make compatible with the
       way Catalyst works with URLS. Main features are:

       o   Split XMLRPC	methodNames by STRING to find out Controller.

       o   Single entrypoint for XMLRPC	calls, like http://host.tld/rpc

       o   DispatchTypes (attributes) which work much the same as Catalyst
	   attrs

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

       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
       Once you've used	the plugin, you'll have	an $c->request->xmlrpc
       accessor	which will return an "Catalyst::Plugin::Server::XMLRPC"
       object.

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

       $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
       The following system functions are available to the public.,

       system.listMethods
	   returns a list of available RPC methods.

DEFINING RETURN	VALUES
       The XML-RPC response must contain a single parameter, which may contain
       an array	(LIST),	struct (HASH) or a string (STRING). To define the
       return values in	your subroutine, you can alter $c->stash in three
       different ways.

   Defining $c->stash->{xmlrpc}
       When defining $c->stash->{xmlrpc}, the XMLRPC server will return	these
       values to the client.

   When	there is no $c->stash->{xmlrpc}
       When there is no	"$c->stash->{xmlrpc}" set, it will return the complete
       "$c->stash"

CONFIGURATION
       The XMLRPC Plugin accepts the following configuration options, which
       can be set in the standard Catalyst way (See "perldoc Catalyst" for
       details):

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

AUTHORS
       Original	Authors: Jos Boumans (kane@cpan.org) and Michiel Ootjers
       (michiel@cpan.org)

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

THANKS
       Tomas Doran (BOBTFISH) for helping out with the debugging

BUG REPORTS
       Please submit all bugs regarding	"Catalyst::Plugin::Server" to
       "bug-catalyst-plugin-server@rt.cpan.org"

LICENSE
       This library is free software, you can redistribute it and/or modify it
       under the same terms as Perl itself.

perl v5.32.0			  2020-08-2Catalyst::Plugin::Server::XMLRPC(3)

NAME | SYNOPSIS | DESCRIPTION | HOW IT WORKS | ATTRIBUTES | ACCESSORS | Server Accessors | CATALYST REQUEST | INTERNAL XMLRPC FUNCTIONS | DEFINING RETURN VALUES | CONFIGURATION | DIAGNOSTICS | TODO | SEE ALSO | ACKNOWLEDGEMENTS | AUTHORS | THANKS | BUG REPORTS | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Catalyst::Plugin::Server::XMLRPC&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help