RPC::XML::Procedure - Object encapsulation of server-side RPC
procedures
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 { ... });
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.
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.
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 described 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.
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 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.
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.
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.
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.
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.
- RT: CPAN's request tracker
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=RPC-XML>
- AnnoCPAN: Annotated CPAN documentation
<http://annocpan.org/dist/RPC-XML>
- CPAN Ratings
<http://cpanratings.perl.org/d/RPC-XML>
- Search CPAN
<http://search.cpan.org/dist/RPC-XML>
- MetaCPAN
<https://metacpan.org/release/RPC-XML>
- Source code on GitHub
<http://github.com/rjray/rpc-xml>
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>).
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.
RPC::XML::Server, make_method
Randy J. Ray
"<rjray@blackperl.com>"