RPC::XML::Procedure(3)User Contributed Perl DocumentatioRPC::XML::Procedure(3)NAMERPC::XML::Procedure - Object encapsulation of server-side RPC proce-
dures
SYNOPSIS
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');
IMPORTANT NOTE
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.
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. Pre-
viously, 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.
USAGE
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 meth-
ods 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 occur mul-
tiple times. Otherwise, each of the following is allowed,
but may only occur once:
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 (May appear more than once) Provides one call-
ing-signature for the method, as either a
space-separated string of types or a list-ref-
erence
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 intro-
spection 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 managment 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.
code([NEW])
Returns or sets the code-reference that will receive calls as mar-
shalled 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).
is_valid
Returns a true/false value as to whether the object currently has
enough content to be a valid method for a server to publish. This
entails having at the very least a name, one or more signatures,
and a code-reference to route the calls to. A server created from
the classes in this software suite will not accept a method that is
not valid.
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 signa-
tures are ignored. If the new signature would cause a conflict (a
case in which the same set of input types are specified for differ-
ent 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 argu-
ments 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 ear-
lier, 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.
mtime
When the method was loaded from a file, this key contains the modi-
fication-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, 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 "<procedure-
def>". The tags that specify name, signatures and the code itself
must always be present. Some optional information may also be sup-
plied. 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.
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 spe-
cific 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.
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.
LICENSE
This module is licensed under the terms of the Artistic License that
covers Perl. See <http://www.opensource.org/licenses/artis-
tic-license.php> for the license.
SEE ALSO
RPC::XML::Server, make_method
AUTHOR
Randy J. Ray <rjray@blackperl.com>
perl v5.8.8 2006-02-18 RPC::XML::Procedure(3)
