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) doesnotincludethereturntype. 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.
AdditionalHashData
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.
XPLFileStructure
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 XPLProcedureLayout 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.
Install Now
PNG Icons
