RPC::XML::Procedure - Object encapsulation of server-side RPC procedures
require RPC::XML::Procedure;
...
$method_1 = RPC::XML::Procedure->new({ name => 'system.identity',
code => sub { ... },
signature => [ 'string' ] });
$method_2 = RPC::XML::Procedure->new('/path/to/status.xpl');
This package is comprised of the code that was formerly RPC::XML::Method. The package was renamed when the decision was made to support procedures and methods as functionally different entities. It is not necessary to include both this module and RPC::XML::Method -- this module provides the latter as an empty subclass. In time, RPC::XML::Method will be removed from the distribution entirely.
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 the RPC::XML::Server manpage).
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.
The following methods are provided by this class:
new(FILE|HASHREF|LIST)signature) is
allowed to occur multiple times. Otherwise, each of the following is allowed,
but may only occur once:
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.
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.
code([NEW])signature([NEW])help([NEW])hidden([NEW])version([NEW])add_signature(LIST)delete_signature(LIST)match_signature(SIGNATURE)'int int' would be tested for by calling
$M->match_signature('int') and expecting the return value to be int.
dispatch and call methods of the server
class, where the return value is subsequently wrapped within a
RPC::XML::response object.
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:
filemtimetime value. This is used to
check for changes to the file the code was originally read from.
called
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 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, version?, hidden?, signature+,
help?, code)>
<!ELEMENT methoddef (name, version?, hidden?, signature+,
help?, code)>
<!ELEMENT name (#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> or
<proceduredef>. 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 direct examples of what the file should look like.
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 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.
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.
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.
This module is licensed under the terms of the Artistic License that covers Perl. See <http://language.perl.com/misc/Artistic.html> for the license.
the RPC::XML::Server manpage, make_method
Randy J. Ray <rjray@blackperl.com>