On Apache
Under GNU General Public License
2012-05-25 05:00 @38.107.179.237 Crawled by CCBot/1.0 (+http://www.commoncrawl.org/bot.html)
RPC::XML::Server(3pm) User Contributed Perl Documentation RPC::XML::Server(3pm)
NAME
RPC::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 listening, as well).
Static Methods
These methods are static to the package, and are used to provide external 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 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)
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:
no_http
If passed with a "true" value, prevents the creation and storage 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 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.
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
constructor.
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 stringified 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 themselves 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 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.
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 messages dispatched by the specific process itself.
response
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. 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 seconds.
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 (generally 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 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
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 maintains. 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 symmetry. Both calls
return the matched object regardless of its underlying 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 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:
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 unmodified.
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 provided.
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
definition 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 operation 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-statistics 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
expressions.
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 exception 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 derivative) 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 these 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 specifies the
expected return type. The remainder (if any) refer to the arguments themselves.
peeraddr
This is the address part of a packed SOCKADDR_IN structure, as returned by
"pack_sockaddr_in" in Socket, which contains the address of the client that has
connected and made the current request. This is provided "raw" in case you need it.
While you could re-create it from "peerhost", it is readily available in both this
server environment and the Apache::RPC::Server environment and thus included for
convenience.
peerhost
This is the address of the remote (client) end of the socket, in "x.x.x.x" (dotted-
quad) format. If you wish to look up the clients host-name, you can use this to do so
or utilize the encoded structure above directly.
peerport
Lastly, this is the port of the remote (client) end of the socket, taken from the
SOCKADDR_IN structure.
Those keys should only be referenced within method code itself, as they are not set on the
server object outside of that context.
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 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 routines 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 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.
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 compression 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 example, if the hosted
code returns large Base64 values pre-encoded from file handles), the "message_file_thresh"
and "message_temp_dir" settings may be used in a manner similar to RPC::XML::Client.
Specifically, 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 and the code within are released under the terms of the Artistic License 2.0
(http://www.opensource.org/licenses/artistic-license-2.0.php). This code may be
redistributed under either the Artistic License or the GNU Lesser General Public License
(LGPL) version 2.1 (http://www.opensource.org/licenses/lgpl-license.php).
SEE ALSO
RPC::XML, RPC::XML::Client, RPC::XML::Parser
AUTHOR
Randy J. Ray <rjray AT blackperl.com>
perl v5.10.0 2008-04-09 RPC::XML::Server(3pm)
Generated by $Id: phpMan.php,v 4.49 2006/02/26 13:18:18 chedong Exp $ Author: Che Dong
On Apache
Under GNU General Public License
2012-05-25 05:00 @38.107.179.237 Crawled by CCBot/1.0 (+http://www.commoncrawl.org/bot.html)