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

FreeBSD Manual Pages

  
 
  

home | help
RPC::XML::Procedure(3)User Contributed Perl DocumentatioRPC::XML::Procedure(3)

NAME
       RPC::XML::Procedure - Object encapsulation of server-side RPC
       procedures

SYNOPSIS
	   require RPC::XML::Procedure;

	   ...
	   $procedure =	RPC::XML::Procedure->new({ name	=> 'system.identity',
						   code	=> sub { ... },
						   signature =>	[ 'string' ] });
	   $method    =	RPC::XML::Method->new('/path/to/status.xpl');
	   $function  =	RPC::XML::Function->new(name =>	'add',
						code =>	sub { ... });

DESCRIPTION
       The RPC::XML::Procedure package is designed primarily for behind-the-
       scenes use by the RPC::XML::Server class	and any	subclasses of it. It
       is documented here in case a project chooses to sub-class it for	their
       purposes	(which would require setting the "method_class"	attribute when
       creating	server objects,	see RPC::XML::Server).

       This package grew out of	the increasing need to abstract	the operations
       that related to the methods a given server instance was providing.
       Previously, methods were	passed around simply as	hash references. It
       was a small step	then to	move them into a package and allow for
       operations directly on the objects themselves. In the spirit of the
       original	hashes,	all the	key data is kept in clear, intuitive hash keys
       (rather than obfuscated as the other classes do). Thus it is important
       to be clear on the interface here before	sub-classing this package.

CLASSES
       This module provides three classes, representing	the three types	of
       procedures that servers can use:

       Methods (RPC::XML::Method)
	   Code	that is	considered a "method" by the server is called as
	   though it were, in fact, a method in	that class. The	first argument
	   in the list is the server object itself, with the arguments to the
	   call	making up the rest of the list.	 The server checks the
	   signature of	the method against the arguments list before the call
	   is made. See	below ("How Procedures Are Called") for	more on	the
	   invocation of code as methods.

       Procedures (RPC::XML::Procedure)
	   Code	that is	considered a "procedure" by the	server is called like
	   a normal (non-method) subroutine call. The server object is not
	   injected into the arguments list. The signature of the procedure is
	   checked again the list of arguments before the call is made,	as
	   with	methods.

       Functions (RPC::XML::Function)
	   Lastly, code	that is	considered a "function"	is the simplest	of the
	   three: it does not have the server object injected into the
	   arguments list, and no check	of signatures is done before the call
	   is made. It is the responsibility of	the function to	properly
	   understand the arguments list, and to return	a value	that the
	   caller will understand.

       There is	(currently) no version that is called like a method but
       ignores signatures like a function.

SUBROUTINES/METHODS
       The following methods are provided by this class:

       new(FILE|HASHREF|LIST)
	   Creates a new object	of the class, and returns a reference to it.
	   The arguments to the	constructor are	variable in nature, depending
	   on the type:

	   FILE	   If there is exactly on argument that	is not a reference, it
		   is assumed to be a filename from which the method is	to be
		   loaded. This	is presumed to be in the XPL format descibed
		   below (see "XPL File	Structure"). If	the file cannot	be
		   opened, or if once opened cannot be parsed, an error	is
		   raised.

	   HASHREF If there is exactly one argument that is a reference, it is
		   assumed to be a hash	with the relevant information on the
		   same	keys as	the object itself uses.	This is	primarily to
		   support backwards-compatibility to code written when
		   methods were	implemented simply as hash references.

	   LIST	   If there is more than one argument in the list, then	the
		   list	is assumed to be a sort	of "ersatz" hash construct, in
		   that	one of the keys	("signature") is allowed to "stack" if
		   it occurs multiple times. Otherwise,	any keys that occur
		   multiple times overwrite the	previous value:

		   name	       The name	of the method, as it will be presented
			       to clients

		   code	       A reference to a	subroutine, or an anonymous
			       subroutine, that	will receive calls for the
			       method

		   signature   Provides	one calling-signature for the method,
			       as either a space-separated string of types or
			       a list-reference

		   help	       The help-text for a method, which is generally
			       used as a part of the introspection interface
			       for a server

		   version     The version number/string for the method

		   hidden      A boolean (true or false) value indicating
			       whether the method should be hidden from
			       introspection and similar listings

		   Note	that all of these correspond to	the values that	can be
		   changed via the accessor methods detailed later.

	   If any error	occurs during object creation, an error	message	is
	   returned in lieu of the object reference.

       clone
	   Create a copy of the	calling	object,	and return the new reference.
	   All elements	are copied over	cleanly, except	for the	code reference
	   stored on the "code"	hash key. The clone will point to the same
	   code	reference as the original. Elements such as "signature"	are
	   copied, so that changes to the clone	will not impact	the original.

       name
	   Returns the name by which the server	is advertising the method.
	   Unlike the next few accessors, this cannot be changed on an object.
	   In order to streamline the management of methods within the server
	   classes, this must persist. However,	the other elements may be used
	   in the creation of a	new object, which may then be added to the
	   server, if the name absolutely must change.

       namespace
	   If the procedure object was created from a file, or if the
	   instantiation included namespace information, this accessor will
	   return the namespace	that the underlying code executes in.
	   Otherwise, it returns an empty string. This cannot be altered (even
	   if the code method is used to replace the code routine).

       code([NEW])
	   Returns or sets the code-reference that will	receive	calls as
	   marshalled by the server. The existing value	is lost, so if it must
	   be preserved, then it should	be retrieved prior to the new value
	   being set.

       signature([NEW])
	   Return a list reference containing the signatures, or set it. Each
	   element of the list is a string of space-separated types (the first
	   of which is the return type the method produces in that calling
	   context). If	this is	being used to set the signature, then an array
	   reference must be passed that contains one or more strings of this
	   nature. Nested list references are not allowed at this level. If
	   the new signatures would cause a conflict (a	case in	which the same
	   set of input	types are specified for	different output types), the
	   old set is silently restored.

       help([NEW])
	   Returns or sets the help-text for the method. As with code, the
	   previous value is lost.

       hidden([NEW])
	   Returns or sets the hidden status of	the method. Setting it loses
	   the previous	value.

       version([NEW])
	   Returns or sets the version string for the method (overwriting as
	   with	the other accessors).

       add_signature(LIST)
	   Add one or more signatures (which may be a list reference or	a
	   string) to the internal tables for this method. Duplicate
	   signatures are ignored. If the new signature	would cause a conflict
	   (a case in which the	same set of input types	are specified for
	   different output types), the	old set	is restored and	an error
	   message is returned.

       delete_signature(LIST)
	   Deletes the signature or signatures (list reference or string) from
	   the internal	tables.	Quietly	ignores	any signature that does	not
	   exist. If the new signature would cause a conflict (a case in which
	   the same set	of input types are specified for different output
	   types), the old set is restored and an error	message	is returned.

       match_signature(SIGNATURE)
	   Check that the passed-in signature is known to the method, and if
	   so returns the type that the	method should be returning as a	result
	   of the call.	Returns	a zero (0) otherwise. This differs from	other
	   signature operations	in that	the passed-in signature	(which may be
	   a list-reference or a string) does not include the return type.
	   This	method is provided so that servers may check a list of
	   arguments against type when marshalling an incoming call. For
	   example, a signature	of 'int	int' would be tested for by calling
	   "$M->match_signature('int')"	and expecting the return value to be
	   "int".

       call(SERVER, PARAMLIST)
	   Execute the code that this object encapsulates, using the list of
	   parameters passed in	PARAMLIST. The SERVER argument should be an
	   object derived from the RPC::XML::Server class. For some types of
	   procedure objects, this becomes the first argument of the parameter
	   list	to simulate a method call as if	it were	on the server object
	   itself. The return value should be a	data object (possibly a
	   RPC::XML::fault), but may not always	be pre-encoded.	Errors trapped
	   in $@ are converted to fault	objects. This method is	generally used
	   in the "dispatch" method of the server class, where the return
	   value is subsequently wrapped within	a RPC::XML::response object.

       reload
	   Instruct the	object to reload itself	from the file it originally
	   was loaded from, assuming that it was loaded	from a file to begin
	   with. Returns an error if the method	was not	originally loaded from
	   a file, or if an error occurs during	the reloading operation.

   Additional Hash Data
       In addition to the attributes managed by	the accessors documented
       earlier,	the following hash keys	are also available for use. These are
       also not	strongly protected, and	the same care should be	taken before
       altering	any of them:

       file
	   When	the method was loaded from a file, this	key contains the path
	   to the file used.

       namespace
	   If the code is loaded from a	file, this hash	key will reflect what
	   namespace the code executes in. If the file specified a namespace,
	   that	is the value you will get (any occurrence of "." in the
	   specified namespace will have been converted	to "::"). If no
	   explicit namespace was provided, the	namespace of the class you
	   called new from will	be used. See "Namespaces".

       mtime
	   When	the method was loaded from a file, this	key contains the
	   modification-time of	the file, as a UNIX-style "time" value.	This
	   is used to check for	changes	to the file the	code was originally
	   read	from.

       called
	   When	the method is being used by one	of the server classes provided
	   in this software suite, this	key is incremented each	time the
	   server object dispatches a request to the method. This can later be
	   checked to provide some indication of how frequently	the method is
	   being invoked.

   XPL File Structure
       This section focuses on the way in which	methods	are expressed in these
       files, referred to here as "XPL files" due to the "*.xpl" filename
       extension (which	stands for "XML	Procedure Layout"). This mini-dialect,
       based on	XML, is	meant to provide a simple means	of specifying method
       definitions separate from the code that comprises the application
       itself. Thus, methods may theoretically be added, removed, debugged or
       even changed entirely without requiring that the	server application
       itself be rebuilt (or, possibly,	without	it even	being restarted).

       The XML-based file structure
	   The XPL Procedure Layout dialect is a very simple application of
	   XML to the problem of expressing the	method in such a way that it
	   could be useful to other packages than this one, or useful in other
	   contexts than this one.

	   The lightweight DTD for the layout can be summarized	as:

	       <!ELEMENT  proceduredef	(name, namespace?, version?, hidden?,
					 signature+, help?, code)>
	       <!ELEMENT  methoddef	(name, namespace?, version?, hidden?,
					 signature+, help?, code)>
	       <!ELEMENT  functiondef	(name, namespace?, version?, hidden?,
					 signature+, help?, code)>
	       <!ELEMENT  name	     (#PCDATA)>
	       <!ELEMENT  namespace  (#PCDATA)>
	       <!ELEMENT  version    (#PCDATA)>
	       <!ELEMENT  hidden     EMPTY>
	       <!ELEMENT  signature  (#PCDATA)>
	       <!ELEMENT  help	     (#PCDATA)>
	       <!ELEMENT  code	     (#PCDATA)>
	       <!ATTLIST  code	     language (#PCDATA)>

	   The containing tag is always	one of "<methoddef>", "<proceduredef>"
	   or "<functiondef>". The tags	that specify name, signatures and the
	   code	itself must always be present. Some optional information may
	   also	be supplied. The "help"	text, or what an introspection API
	   would expect	to use to document the method, is also marked as
	   optional.  Having some degree of documentation for all the methods
	   a server provides is	a good rule of thumb, however.

	   The default methods that this package provides are turned into XPL
	   files by the	make_method tool (see make_method). The	final forms of
	   these may serve as examples of what the file	should look like.

       Information used	only for book-keeping
	   Some	of the information in the XPL file is only for book-keeping:
	   the version stamp of	a method is never involved in the invocation.
	   The server also keeps track of the last-modified time of the	file
	   the method is read from, as well as the full	directory path to that
	   file. The "<hidden />" tag is used to identify those	methods	that
	   should not be exposed to the	outside	world through any sort of
	   introspection/documentation API. They are still available and
	   callable, but the client must possess the interface information in
	   order to do so.

       The information crucial to the method
	   The name, signatures	and code must be present for obvious reasons.
	   The "<name>"	tag tells the server what external name	this procedure
	   is known by.	The "<signature>" tag, which may appear	more than
	   once, provides the definition of the	interface to the function in
	   terms of what types and quantity of arguments it will accept, and
	   for a given set of arguments	what the type of the returned value
	   is. Lastly is the "<code>" tag, without which there is no procedure
	   to remotely call.

       Why the <code> tag allows multiple languages
	   Note	that the "<code>" tag is the only one with an attribute, in
	   this	case "language". This is designed to allow for one XPL file to
	   provide a given method in multiple languages. Why, one might	ask,
	   would there be a need for this?

	   It is the hope behind this package that collections of RPC suites
	   may one day be made available as separate entities from this
	   specific software package.  Given this hope,	it is not unreasonable
	   to suggest that such	a suite	of code	might be implemented in	more
	   than	one language (each of Perl, Python, Ruby and Tcl, for
	   example). Languages which all support the means by which to take
	   new code and	add it to a running process on demand (usually through
	   an ""eval"" keyword or something similar). If the file A.xpl	is
	   provided with implementations in all	four of	the above languages,
	   the name, help text,	signature and even hidden status would likely
	   be identical. So, why not share the non-language-specific elements
	   in the spirit of re-use?

   The "make_method" Utility
       The utility script "make_method"	is provided as a part of this software
       suite. It allows	for the	automatic creation of XPL files	from either
       command-line information	or from	template files.	It has a wide variety
       of features and options,	and is out of the scope	of this	particular
       manual page. The	package	Makefile.PL features an	example	of engineering
       the automatic generation	of XPL files and their delivery	as a part of
       the normal Perl module build process. Using this	tool is	highly
       recommended over	managing XPL files directly. For the full details, see
       make_method.

NAMESPACES
       As default behavior, Perl code that is passed to	"eval" when a XPL file
       is loaded gets put into the same	namespace as the package used to load
       the XPL.	 It is not an issue when you create your own
       RPC::XML::Procedure (or ::Method	or ::Function) objects,	as the code is
       already instantiated into a given namespace.  This can be important if
       your code expects to call routines in other loaded packages, utilize
       package-level globals, etc.

       To give developers control over the namespace in	XPL code, a new
       optional	tag "<namespace>" was added in the 0.65	release. If this tag
       is present in the XPL being read, it defines the	namespace that the
       "<code>"	block is evaluated in.

       The value of the	namespace tag is a string providing the	namespace in
       either the Perl-style of	hierarchy parts	separated by "::", or the
       style used by Java, Perl6, etc.,	in which the parts are separated by
       ".". The	latter form is converted to Perl style for the evaluation of
       the code. If there is no	namespace declaration in a XPL file, the
       namespace of the	class that loads the XPL is used.

DIAGNOSTICS
       Unless otherwise	noted in the individual	documentation sections,	all
       methods return the object reference on success, or a (non-reference)
       text string containing the error	message	upon failure.

CAVEATS
       Moving the method management to a separate class	adds a good deal of
       overhead	to the general system. The trade-off in	reduced	complexity and
       added maintainability should offset this.

BUGS
       Please report any bugs or feature requests to "bug-rpc-xml at
       rt.cpan.org", or	through	the web	interface at
       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=RPC-XML>. I will	be
       notified, and then you'll automatically be notified of progress on your
       bug as I	make changes.

SUPPORT
       o   RT: CPAN's request tracker

	   <http://rt.cpan.org/NoAuth/Bugs.html?Dist=RPC-XML>

       o   AnnoCPAN: Annotated CPAN documentation

	   <http://annocpan.org/dist/RPC-XML>

       o   CPAN	Ratings

	   <http://cpanratings.perl.org/d/RPC-XML>

       o   Search CPAN

	   <http://search.cpan.org/dist/RPC-XML>

       o   MetaCPAN

	   <https://metacpan.org/release/RPC-XML>

       o   Source code on GitHub

	   <http://github.com/rjray/rpc-xml>

LICENSE	AND COPYRIGHT
       This file and the code within are copyright (c) 2011 by Randy J.	Ray.

       Copying and distribution	are permitted under the	terms of the Artistic
       License 2.0
       (<http://www.opensource.org/licenses/artistic-license-2.0.php>) or the
       GNU LGPL	2.1 (<http://www.opensource.org/licenses/lgpl-2.1.php>).

CREDITS
       The XML-RPC standard is Copyright (c) 1998-2001,	UserLand Software,
       Inc.  See <http://www.xmlrpc.com> for more information about the	XML-
       RPC specification.

SEE ALSO
       RPC::XML::Server, make_method

AUTHOR
       Randy J.	Ray "<rjray@blackperl.com>"

perl v5.32.0			  2013-04-27		RPC::XML::Procedure(3)

NAME | SYNOPSIS | DESCRIPTION | CLASSES | SUBROUTINES/METHODS | NAMESPACES | DIAGNOSTICS | CAVEATS | BUGS | SUPPORT | LICENSE AND COPYRIGHT | CREDITS | SEE ALSO | AUTHOR

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

home | help