RPC::XML::Server(3) User Contributed Perl Documentation RPC::XML::Server(3)NAMERPC::XML::Server - A sample server implementation based on RPC::XML
SYNOPSIS
use RPC::XML::Server;
...
$srv = RPC::XML::Server->new(port => 9000);
# Several of these, most likely:
$srv->add_method(...);
...
$srv->server_loop; # Never returns
DESCRIPTION
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.
USAGE
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 listen-
ing, as well).
Static Methods
These methods are static to the package, and are used to provide exter-
nal access to internal settings:
INSTALL_DIR
Returns the directory that this module is installed into. This is
used by methods such as "add_default_methods" to locate the XPL
files that are shipped with the distribution.
version
Returns the version string associated with this package.
product_tokens
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.
Methods
The following are object (non-static) methods. Unless otherwise explic-
itly noted, all methods return the invoking object reference upon suc-
cess, 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)
Creates a new object of the class and returns the blessed refer-
ence. Depending on the options, the object will contain some combi-
nation 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:
no_http
If passed with a "true" value, prevents the creation and stor-
age of the HTTP::Daemon object. This allows for deployment of a
server object in other environments. Note that if this is set,
the server_loop method described below will silently attempt to
use the Net::Server module.
no_default
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").
path
host
port
queue
These four are specific to the HTTP-based nature of the server.
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. They may also
be used if the server object tries to use Net::Server as an
alternative server core.
xpl_path
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.
timeout
Specify a value (in seconds) for the HTTP::Daemon server to use
as a timeout value when reading request data from an inbound
connection. The default value is 10 seconds. This value is not
used except by HTTP::Daemon.
auto_methods
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.
auto_updates
If specified and set to a "true" value, enables the checking of
the modification time of the file from which a method was orig-
inally 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.
parser
If this parameter is passed, the value following it is expected
to be an array reference. The contents of that array are passed
to the new method of the RPC::XML::Parser object that the
server object caches for its use. See the RPC::XML::Parser
manual page for a list of recognized parameters to the con-
structor.
message_file_thresh
If this key is passed, the value associated with it is assumed
to be a numerical limit to the size of in-memory messages. Any
out-bound request that would be larger than this when stringi-
fied is instead written to an anonynous temporary file, and
spooled from there instead. This is useful for cases in which
the request includes RPC::XML::base64 objects that are them-
selves spooled from file-handles. This test is independent of
compression, so even if compression of a request would drop it
below this threshhold, it will be spooled anyway. The file
itself is unlinked after the file-handle is created, so once it
is freed the disk space is immediately freed.
message_temp_dir
If a message is to be spooled to a temporary file, this key can
define a specific directory in which to open those files. If
this is not given, then the "tmpdir" method from the File::Spec
package is used, instead.
Any other keys in the options hash not explicitly used by the con-
structor 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.
url 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".
requests
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 mes-
sages dispatched by the specific process itself.
response
Each instance of this class (and any subclasses that do not com-
pletely 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. This method returns a reference to that object.
started([BOOL])
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.
timeout(INT)
You can call this method to set the timeout of new connections
after they are received. This function returns the old timeout
value. If you pass in no value then it will return the old value
without modifying the current value. The default value is 10 sec-
onds.
add_method(FILE | HASHREF | OBJECT)
add_proc(FILE | HASHREF | OBJECT)
This adds a new published method or procedure to the server object
that invokes it. The new method may be specified in one of three
ways: as a filename, a hash reference or an existing object (gener-
ally of either RPC::XML::Procedure or RPC::XML::Method classes).
If passed as a hash reference, the following keys are expected:
name
The published (externally-visible) name for the method.
version
An optional version stamp. Not used internally, kept mainly for
informative purposes.
hidden
If passed and evaluates to a "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.
code
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.
signature
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.
help
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 in the RPC::XML::Procedure manual (see
RPC::XML::Procedure). If the name passed is not an absolute path-
name, then the file will be searched for in any directories speci-
fied 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 RPC::XML::Procedure.
delete_method(NAME)delete_proc(NAME)
Delete the named method or procedure from the calling object.
Removes the entry from the internal table that the object main-
tains. If the method is shared across more than one server object
(see "share_methods"), then the underlying object for it will only
be destroyed when the last server object releases it. On error
(such as no method by that name known), an error string is
returned.
The delete_proc call is identical, supplied for the sake of symme-
try. Both calls return the matched object regardless of its under-
lying type.
list_methods
list_procs
This returns a list of the names of methods and procedures the
server current has published. Note that the returned values are
not the method objects, but rather the names by which they are
externally known. The "hidden" status of a method is not consulted
when this list is created; all methods and procedures known are
listed. The list is not sorted in any specific order.
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])
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.
get_method(NAME)get_proc(NAME)
Returns a reference to an object of the class RPC::XML::Method or
RPC::XML::Procedure, which is the current binding for the published
method NAME. If there is no such method known to the server, then
"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)
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.
Because infinite loops requiring a "HUP" or "KILL" signal to termi-
nate are generally in poor taste, the HTTP::Daemon side of this
sets up a localized signal handler which causes an exit when trig-
gered. By default, this is attached to the "INT" signal. If the
Net::Server module is being used instead, it provides its own sig-
nal 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:
signal
If passed, should be the traditional name for the signal that
should be bound to the exit function. If desired, a reference
to an array of signal names may be passed, in which case all
signals will be given the same handler. 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).
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)
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.
The dispatched method may communicate error in several ways.
First, any non-reference return value is presumed to be an error
string, and is encoded and returned as an RPC::XML::fault response.
The method is run under an "eval()", so errors conveyed by $@ are
similarly encoded and returned. As a special case, a method may
explicitly "die()" with a fault response, which is passed on unmod-
ified.
add_default_methods([DETAILS])
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.)
Note that there is no symmetric call in this case. The provided API
is implemented as methods, and thus only this interface is pro-
vided.
add_methods_in_dir(DIR [, DETAILS])
add_procs_in_dir(DIR [, DETAILS])
This is exactly like add_default_methods above, save that the
caller specifies which directory to scan for "*.xpl" files. In
fact, the add_default_methods routine simply calls this routine
with the installation directory as the first argument. The defini-
tion of the additional arguments is the same as above.
add_procs_in_dir is provided for symmetry.
share_methods(SERVER, NAMES)
share_procs(SERVER, NAMES)
The calling server object shares the methods and/or procedures
listed in NAMES with the source-server passed as the first object.
The source must derive from this package in order for this opera-
tion to be permitted. At least one method must be specified, and
all are specified by name (not by object refernce). Both objects
will reference the same exact RPC::XML::Procedure (or Method, or
derivative thereof) object in this case, meaning that call-statis-
tics and the like will reflect the combined data. If one or more of
the passed names are not present on the source server, an error
message is returned and none are copied to the calling object.
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 expres-
sions.
The share_procs interface is provided for symmetry.
copy_methods(SERVER, NAMES)
copy_procs(SERVER, NAMES)
This behaves like the method share_methods above, with the excep-
tion that the calling object is given a clone of each method,
rather than referencing the same exact method as the source server.
The code reference part of the method is shared between the two,
but all other data are copied (including a fresh copy of any list
references used) into a completely new RPC::XML::Procedure (or de-
rivative) object, using the "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 Server-Side Remote Methods
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
RPC::XML::Procedure). 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.
How Methods Are Called
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:
method_name
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.
signature
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 speci-
fies the expected return type. The remainder (if any) refer to the
arguments themselves.
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::Proce-
dure 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 names-
paces. 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 Default Methods Provided
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:
system.identity
Returns a string value identifying the server name, version, and
possibly a capability level. Takes no arguments.
system.introspection
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 rou-
tines may be configured to be hidden from such introspection
queries.
system.listMethods
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).
system.methodHelp
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.
system.methodSignature
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.
system.multicall
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.
system.status
Takes no arguments and returns a struct containing a number of sys-
tem 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 "meth-
ods" 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.
Content Compression
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
Returns a false value if compression is not available to the server
object. This is based on the availability of the Compress::Zlib
module at start-up time, and cannot be changed.
compress_thresh([MIN_LIMIT])
Return or set the compression threshhold value. Messages smaller
than this size in bytes will not be compressed, even when compres-
sion is available, to save on CPU resources. If a value is passed,
it becomes the new limit and the old value is returned.
Spooling Large Messages
If the server anticipates handling large out-bound messages (for exam-
ple, if the hosted code returns large Base64 values pre-encoded from
file handles), the "message_file_thresh" and "message_temp_dir" set-
tings may be used in a manner similar to RPC::XML::Client. Specifi-
cally, the threshhold is used to determine when a message should be
spooled to a filehandle rather than made into an in-memory string (the
RPC::XML::base64 type can use a filehandle, thus eliminating the need
for the data to ever be completely in memory). An anonymous temporary
file is used for these operations.
Note that the message size is checked before compression is applied,
since the size of the compressed output cannot be known until the full
message is examined. It is possible that a message will be spooled even
if its compressed size is below the threshhold, if the uncompressed
size exceeds the threshhold.
message_file_thresh
message_temp_dir
These methods may be used to retrieve or alter the values of the
given keys as defined earlier for the "new" method.
DIAGNOSTICS
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.
CAVEATS
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.
CREDITS
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().
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, RPC::XML::Client, RPC::XML::Parser
AUTHOR
Randy J. Ray <rjray@blackperl.com>
perl v5.8.8 2006-02-18 RPC::XML::Server(3)
