RPC::XML::Server - A sample server implementation based on RPC::XML
use RPC::XML::Server;
...
$srv = RPC::XML::Server->new(port => 9000);
# Several of these, most likely:
$srv->add_method(...);
...
$srv->server_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. Unless otherwise explicitly noted, all methods return the invoking object reference upon success, and a non-reference error string upon failure.
See Content Compression below for details of how the server class manages gzip-based compression and expansion of messages.
new(OPTIONS)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 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).
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.
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.
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.
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.
undef.
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. This method returns a reference
to that object.
started([BOOL])time2iso8601 routine exported by the RPC::XML package.
If passed as a hash reference, the following keys are expected:
true value, then the method should be hidden
from any introspection API implementations. This parameter is optional, the
default behavior being to make the method publically-visible.
If a file is passed, then it is expected to be in the XML-based format, described in the RPC::XML::Procedure manual (see the RPC::XML::Procedure manpage). 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. If the operation fails, the return value will be a non-reference, an error message. Otherwise, the return value is the object reference.
The add_method and add_proc calls are essentialy identical unless called with hash references. Both files and objects contain the information that defines the type (method vs. procedure) of the funtionality to be added to the server. If add_method is called with a file that describes a procedure, the resulting addition to the server object will be a RPC::XML::Procedure object, not a method object.
For more on the creation and manipulation of procedures and methods as objects, see the RPC::XML::Procedure manpage.
delete_method(NAME)delete_proc(NAME)The delete_proc call is identical, supplied for the sake of symmetry. Both calls return the matched object regardless of its underlying type.
The list_procs call is provided for symmetry. Both calls list all published routines on the calling server object, regardless of underlying type.
xpl_path([LISTREF])*.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.
get_method(NAME)get_proc(NAME)undef is
returned. The object is implemented as a hash, and has the same key and value
pairs as for add_method, above. Thus, the reference returned is suitable
for passing back to add_method. This facilitates temporary changes in what
a published name maps to. Note that this is a referent to the object as stored
on the server object itself, and thus changes to it could affect the behavior
of the server.
The get_proc interface is provided for symmetry.
server_loop(HASH)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.
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.
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:
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).
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.
dispatch(REQUEST)add_default_methods([DETAILS])*.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.)
Note that there is no symmetric call in this case. The provided API is implemented as methods, and thus only this interface is provided.
*.xpl files. In fact, the
add_default_methods routine simply calls this routine with the installation
directory as the first argument. The definition of the additional arguments is
the same as above.
add_procs_in_dir is provided for symmetry.
Alternately, one or more of the name parameters passed to this call may be
regular-expression objects (the result of the qr operator). Any of these
detected are applied against the list of all available methods known to the
source server. All matching ones are inserted into the list (the list is pared
for redundancies in any case). This allows for easier addition of whole
classes such as those in the system.* name space (via qr/^system\./),
for example. There is no substring matching provided. Names listed in the
parameters to this routine must be either complete strings or regular
expressions.
The share_procs interface is provided for symmetry.
clone() method
from that class. Thus, while the calling object has the same methods
available, and is re-using existing code in the Perl runtime, the method
objects (and hence the statistics and such) are kept separate. As with the
above, an error is flagged if one or more are not found.
This routine also accepts regular-expression objects with the same behavior and limitations. Again, copy_procs is simply provided for symmetry.
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 (detailed in the
manual page for the RPC::XML::Procedure class, see the RPC::XML::Procedure manpage).
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.
When a routine is called via the server dispatcher, it is called with the arguments that the client request passed. Depending on whether the routine is considered a ``procedure'' or a ``method'', there may be an extra argument at the head of the list. The extra argument is present when the routine being dispatched is part of a RPC::XML::Method object. The extra argument is 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:
Note that by passing the server object reference first, method-classed routines are essentially expected to behave as actual methods of the server class, as opposed to ordinary functions. Of course, they can also discard the initial argument completely.
The routines should not make (excessive) use of global variables, for obvious
reasons. When the routines are loaded from XPL files, the code is created as a
closure that forces execution in the RPC::XML::Procedure package. If the
code element of a procedure/method is passed in as a direct code reference by
one of the other syntaxes allowed by the constructor, the package may well be
different. Thus, routines should strive to be as localized as possible,
independant of specific namespaces. If a group of routines are expected to
work in close concert, each should explicitly set the namespace with a
package declaration as the first statement within the routines themselves.
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:
method(s) have no
help text, the string will be null.
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.
In addition, each of these has an accompanying help file in the methods
sub-directory of the distribution.
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.
The RPC::XML::Server class now supports compressed messages, both incoming and outgoing. If a client indicates that it can understand compressed content, the server will use the Compress::Zlib (available from CPAN) module, if available, to compress any outgoing messages above a certain threshhold in size (the default threshhold is set to 4096 bytes). The following methods are all related to the compression support within the server class:
compress_thresh([MIN_LIMIT])
Unless explicitly stated otherwise, 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 began as a reference implementation in which clarity of process and readability of the code took precedence over general efficiency. It is now being maintained as production code, but may still have parts that could be written more 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. A helpful patch was sent in by Tino Wuensche to fix problems in the signal-setting and signal-catching code in server_loop().
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 manpage, the RPC::XML::Client manpage, the RPC::XML::Parser manpage
Randy J. Ray <rjray@blackperl.com>