RPC::XML::Server - A sample server implementation based on RPC::XML
use RPC::XML::Server; ... $srv = new RPC::XML::Server (port => 9000); # Several of these, most likely: $srv->add_method(...); ... $srv->accept_loop; # Never returns
This is a sample XML-RPC server built upon the RPC::XML data classes, and using HTTP::Daemon and HTTP::Response for the communication layer.
Use of the RPC::XML::Server is based on an object model. A server is instantiated from the class, methods (subroutines) are made public by adding them through the object interface, and then the server object is responsible for dispatching requests (and possibly for the HTTP listening, as well).
The following methods are provided by the RPC::XML::Server class:
Creates a new object of the class and returns the blessed reference. Depending on the options, the object will contain some combination of an HTTP listener, a pre-populated HTTP::Response object, a RPC::XML::Parser object, and a dispatch table with the set of default methods pre-loaded. The options that new accepts are passed as a hash of key/value pairs (not a hash reference). The accepted options are:
If passed with a true value, prevents the creation and storage of the HTTP::Daemon and the pre-configured HTTP::Response objects. This allows for deployment of a server object in other environments. Note that if this is set, the accept_loop method described below will silently return immediately.
true
If passed with a true value, prevents the loading of the default methods provided with the RPC::XML distribution. These may be later loaded using the add_default_methods interface described later. The methods themselves are described below (see "The Default Methods Provided").
These four are mainly relevant only to HTTP-based implementations. The last three are not used at all if no_http is set. The path argument sets the additional URI path information that clients would use to contact the server. Internally, it is not used except in outgoing status and introspection reports. The host, port and queue arguments are passed to the HTTP::Daemon constructor if they are passed. They set the hostname, TCP/IP port, and socket listening queue, respectively. Again, they are not used if the no_http argument was set.
no_http
If you plan to add methods to the server object by passing filenames to the add_method call, this argument may be used to specify one or more additional directories to be searched when the passed-in filename is a relative path. The value for this must be an array reference. See also add_method and xpl_path, below.
add_method
If specified and set to a true value, enables the automatic searching for a requested remote method that is unknown to the server object handling the request. If set to "no" (or not set at all), then a request for an unknown function causes the object instance to report an error. If the routine is still not found, the error is reported. Enabling this is a security risk, and should only be permitted by a server administrator with fully informed acknowledgement and consent.
If specified and set to a "true" value, enables the checking of the modification time of the file from which a method was originally loaded. If the file has changed, the method is re-loaded before execution is handed off. As with the auto-loading of methods, this represents a security risk, and should only be permitted by a server administrator with fully informed acknowledgement and consent.
The value passed with this option is treated as a boolean toggle to decide whether debugging statements should be sent to the logging facility.
Any other keys in the options hash not explicitly used by the constructor are copied over verbatim onto the object, for the benefit of sub-classing this class. All internal keys are prefixed with "__" to avoid confusion. Feel free to use this prefix only if you wish to re-introduce confusion.
__
Returns the version string associated with this package.
This returns the identifying string for the server, in the format "NAME/VERSION" consistent with other applications such as Apache and LWP. It is provided here as part of the compatibility with HTTP::Daemon that is required for effective integration with Net::Server.
NAME/VERSION
This returns the HTTP URL that the server will be responding to, when it is in the connection-accept loop. If the server object was created without a built-in HTTP listener, then this method returns undef.
undef
Returns the number of requests this server object has marshalled. Note that in multi-process environments (such as Apache or Net::Server::PreFork) the value returned will only reflect the messages dispatched by the specific process itself.
Each instance of this class (and any subclasses that do not completely override the new method) creates and stores an instance of HTTP::Response, which is then used by the HTTP::Daemon or Net::Server processing loops in constructing the response to clients. The response object has all common headers pre-set for efficiency.
new
Gets and possibly sets the clock-time when the server starts accepting connections. If a value is passed that evaluates to true, then the current clock time is marked as the starting time. In either case, the current value is returned. The clock-time is based on the internal time command of Perl, and thus is represented as an integer number of seconds since the system epoch. Generally, it is suitable for passing to either localtime or to the time2iso8601 routine exported by the RPC::XML package.
time2iso8601
If called with no arguments, it returns the current debugging value as a decimal value. The debugging level cannot be changed at run-time.
If there are any arguments, the first one is treated as a numerical value that gets logically-anded with the internal debugging level. If the result is a true value, then the remainder is treated as an sprintf format string and arguments. This is evaluated and written to the error log (generally the STDERR file descriptor).
sprintf
This adds a new published method to the server object that invokes it. The new method may be specified in one of two ways: as a filename or as a hash reference.
If passed as a hash reference, the following keys are expected:
The published (externally-visible) name for the method
An optional version stamp. Not used internally, kept mainly for informative purposes.
If passed and evaluates to a true value, then the method should be hidden from any introspection API implementations.
A code reference to the actual Perl subroutine that handles this method. A symbolic reference is not accepted. The value can be passed either as a reference to an existing routine, or possibly as a closure. See "How Methods are Called" for the semantics the referenced subroutine must follow.
A list reference of the signatures by which this routine may be invoked. Every method has at least one signature. Though less efficient for cases of exactly one signature, a list reference is always used for sake of consistency.
Optional documentation text for the method. This is the text that would be returned, for example, by a system.methodHelp call (providing the server has such an externally-visible method).
If a file is passed, then it is expected to be in the XML-based format, described later (see "Specifying Server-Side Remote Methods"). If the name passed is not an absolute pathname, then the file will be searched for in any directories specified when the object was instantiated, then in the directory into which this module was installed, and finally in the current working directory.
Get and/or set the object-specific search path for *.xpl files (files that specify methods) that are specified in calls to add_method, above. If a list reference is passed, it is installed as the new path (each element of the list being one directory name to search). Regardless of argument, the current path is returned as a list reference. When a file is passed to add_method, the elements of this path are searched first, in order, before the installation directory or the current working directory are searched.
*.xpl
Returns a hash reference containing the current binding for the published method NAME. If there is no such method known to the server, then undef is returned. The hash has the same key and value pairs as for add_method, above. Thus, hash reference returned is suitable for passing back to add_method. This facilitates temporary changes in what a published name maps to.
This is a shorter implementation of the above, that only returns the code reference associated with the named method. It returns undef if no such method exists. Since the methods are stored internally as closures, this is the only reliable way of calling one method from within another.
Enters the connection-accept loop, which generally does not return. This is the accept()-based loop of HTTP::Daemon if the object was created with an instance of that class as a part. Otherwise, this enters the run-loop of the Net::Server class. It listens for requests, and marshalls them out via the dispatch method described below. It answers HTTP-HEAD requests immediately (without counting them on the server statistics) and efficiently by using a cached HTTP::Response object.
accept()
dispatch
Because infinite loops requiring a HUP or KILL signal to terminate are generally in poor taste, the HTTP::Daemon side of this sets up a localized signal handler which causes an exit when triggered. By default, this is attached to the INT signal. If the Net::Server module is being used instead, it provides its own signal management.
HUP
KILL
INT
The arguments, if passed, are interpreted as a hash of key/value options (not a hash reference, please note). For HTTP::Daemon, only one is recognized:
If passed, should be the traditional name for the signal that should be bound to the exit function. The user is responsible for not passing the name of a non-existent signal, or one that cannot be caught. If the value of this argument is 0 (a false value) or the string NONE, then the signal handler will not be installed, and the loop may only be broken out of by killing the running process (unless other arrangements are made within the application).
false
NONE
The options that Net::Server responds to are detailed in the manual pages for that package. All options passed to server_loop in this situation are passed unaltered to the run() method in Net::Server.
server_loop
run()
This is the server method that actually manages the marshalling of an incoming request into an invocation of a Perl subroutine. The parameter passed in may be one of: a scalar containing the full XML text of the request, a scalar reference to such a string, or a pre-constructed RPC::XML::request object. Unless an object is passed, the text is parsed with any errors triggering an early exit. Once the object representation of the request is on hand, the parameter data is extracted, as is the method name itself. The call is sent along to the appropriate subroutine, and the results are collated into an object of the RPC::XML::response class, which is returned. Any non-reference return value should be presumed to be an error string. If the dispatched method encountered some sort of error, it will not be propagated upward here, but rather encoded as an object of the RPC::XML::fault class, and returned as the result of the dispatch. This distinguishes between server-centric errors, and general run-time errors.
This method adds all the default methods (those that are shipped with this extension) to the calling server object. The files are denoted by their *.xpl extension, and are installed into the same directory as this Server.pm file. The set of default methods are described below (see "The Default Methods Provided").
If any names are passed as a list of arguments to this call, then only those methods specified are actually loaded. If the *.xpl extension is absent on any of these names, then it is silently added for testing purposes. Note that the methods shipped with this package have file names without the leading "status." part of the method name. If the very first element of the list of arguments is "except" (or "-except"), then the rest of the list is treated as a set of names to not load, while all others do get read. The Apache::RPC::Server module uses this to prevent the loading of the default system.status method while still loading all the rest of the defaults. (It then provides a more Apache-centric status method.)
status.
except
-except
system.status
This is exactly like add_default_methods above, save that the caller specifies which directory to scan for *.xpl files. In fact, the defaults routine simply calls this routine with the installation directory as the first argument. The definition of the additional arguments is the same as above.
Specifying the methods themselves can be a tricky undertaking. Some packages (in other languages) delegate a specific class to handling incoming requests. This works well, but it can lead to routines not intended for public availability to in fact be available. There are also issues around the access that the methods would then have to other resources within the same running system.
The approach taken by RPC::XML::Server (and the Apache::RPC::Server subclass of it) require that methods be explicitly published in one of the several ways provided. Methods may be added directly within code by using add_method as described above, with full data provided for the code reference, signature list, etc. The add_method technique can also be used with a file that conforms to a specific XML-based format. Entire directories of files may be added using add_methods_in_dir, which merely reads the given directory for files that appear to be method definitions.
add_methods_in_dir
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 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 <methoddef>. 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.
<methoddef>
The default methods that this package provides are turned into XPL files by the make_method tool, described later. 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.
<hidden />
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.
<name>
<signature>
<code>
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 those 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?
eval
The utility script make_method is provided as a part of this package. 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.
make_method
When a routine is called via the server dispatcher, it is called with the arguments that the client request passed, plus one. The extra argument is the first one passed, a reference to a RPC::XML::Server object (or a subclass thereof). This is derived from a hash reference, and will include two special keys:
This is the name by which the method was called in the client. Most of the time, this will probably be consistent for all calls to the server-side method. But it does not have to be, hence the passing of the value.
This is the signature that was used, when dispatching. Perl has a liberal view of lists and scalars, so it is not always clear what arguments the client specifically has in mind when calling the method. The signature is an array reference containing one or more datatypes, each a simple string. The first of the datatypes specifies the expected return type. The remainder (if any) refer to the arguments themselves.
The methods should not make (excessive) use of global variables. Likewise, methods should not change their package space within the definition. Bad Things Could Happen.
The following methods are provided with this package, and are the ones installed on newly-created server objects unless told not to. These are identified by their published names, as they are compiled internally as anonymous subroutines and thus cannot be called directly:
Returns a string value identifying the server name, version, and possibly a capability level. Takes no arguments.
Returns a series of struct objects that give overview documentation of one or more of the published methods. It may be called with a string identifying a single routine, in which case the return value is a struct. It may be called with an array of string values, in which case an array of struct values, one per element in, is returned. Lastly, it may be called with no input parameters, in which case all published routines are documented. Note that routines may be configured to be hidden from such introspection queries.
Returns a list of the published methods or a subset of them as an array of string values. If called with no parameters, returns all (non-hidden) method names. If called with a single string pattern, returns only those names that contain the string as a substring of their name (case-sensitive, and this is not a regular expression evaluation).
Takes either a single method name as a string, or a series of them as an array of string. The return value is the help text for the method, as either a string or array of string value. If the method(s) have no help text, the string will be null.
As above, but returns the signatures that the method accepts, as array of string representations. If only one method is requests via a string parameter, then the return value is the corresponding array. If the parameter in is an array, then the returned value will be an array of array of string.
This is a simple implementation of composite function calls in a single request. It takes an array of struct values. Each struct has at least a methodName member, which provides the name of the method to call. If there is also a params member, it refers to an array of the parameters that should be passed to the call.
methodName
params
Takes no arguments and returns a struct containing a number of system status values including (but not limited to) the current time on the server, the time the server was started (both of these are returned in both ISO 8601 and UNIX-style integer formats), number of requests dispatched, and some identifying information (hostname, port, etc.).
In addition, each of these has an accompanying help file in the methods sub-directory of the distribution.
methods
These methods are installed as *.xpl files, which are generated from files in the methods directory of the distribution using the make_method tool (see make_method). The files there provide the Perl code that implements these, their help files and other information.
All methods return some type of reference on success, or an error string on failure. Non-reference return values should always be interpreted as errors unless otherwise noted.
This is a reference implementation in which clarity of process and readability of the code took precedence over general efficiency. Much, if not all, of this can be written more compactly and/or efficiently.
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.
This module is licensed under the terms of the Artistic License that covers Perl itself. See <http://language.perl.com/misc/Artistic.html> for the license itself.
RPC::XML, RPC::XML::Client, RPC::XML::Parser
Randy J. Ray <rjray@blackperl.com>
To install RPC::XML, copy and paste the appropriate command in to your terminal.
cpanm
cpanm RPC::XML
CPAN shell
perl -MCPAN -e shell install RPC::XML
For more information on module installation, please visit the detailed CPAN module installation guide.