RPC::XML::Server - A server base-class for XML-RPC
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 both a base-class for developing XML-RPC servers, and a working server
class in its own right. It is built upon the RPC::XML data classes, and
defaults to using HTTP::Daemon 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).
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.
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::ParserFactory-generated
object, and a dispatch table with the set of default procedures 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 procedures
provided with the RPC::XML distribution. These may be later loaded using
the add_default_methods interface described later. The procedures themselves
are described below (see The Default Procedures 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 procedures/methods/functions to the server object by passing
filenames to the add_method/add_procedure/add_function calls, 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 the add_* and xpl_path methods,
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/procedure/function 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/procedure/function 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, its value is expected to be an array
reference. The contents of that array are passed to the new method of the
RPC::XML::ParserFactory class, which creates the parser object that the
server object caches for its use. See the RPC::XML::ParserFactory 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 threshold, it will be
spooled anyway. The file itself is created via File::Temp with
UNLINK set,
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.
- fault_code_base
-
Specify a base integer value that is added to the numerical codes for all
faults the server can return. See Server Faults for the list of faults
that are built-in to the server class. This allows an application to ``move''
the RPC::XML::Server pre-defined fault codes out of the way of codes that
the application itself may generate.
Note that this value is not applied to any faults specified via the next
option, fault_table. It is assumed that the developer has already applied
any offset to those codes.
- fault_table
-
Specify one or more fault types to either add to or override the built-in set
of faults for the server object. The value of this parameter is a hash
reference whose keys are the fault type and whose values are either a scalar
(which is taken to be the numerical code) or a list reference with two elements
(the code followed by the string). See Server Faults for the list of
faults that are built-in to the server class, and for more information on
defining your own.
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)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.
- server_fault(STRING, STRING)
-
Create a RPC::XML::fault object of the specified type, optionally including
the second (string) parameter. See Server Faults for the list of faults
defined by RPC::XML::Server (as well as documentation on creating your
own).
- add_method(FILE | HASHREF | OBJECT)
-
- add_procedure(FILE | HASHREF | OBJECT)
-
- add_function(FILE | HASHREF | OBJECT)
-
This adds a new published method/procedure/function 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, RPC::XML::Method or RPC::XML::Function classes).
If passed as a hash reference, the following keys are expected:
- name
-
The published (externally-visible) name for the method.
- versionversion
-
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 Procedures 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 page (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, add_function and add_procedure 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
functionality 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_procedure(NAME)
-
- delete_function(NAME)
-
Delete the named method/procedure/function 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_procedure and delete_function calls are identical, supplied
for the sake of symmetry. All calls return the matched object regardless of its
underlying type.
- list_methods
-
- list_procedures
-
- list_functions
-
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_procedures and list_functions calls are provided for
symmetry. All calls list all published routines on the calling server object,
regardless of underlying type.
xpl_path([LISTREF])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_procedure(NAME)
-
- get_function(NAME)
-
Returns a reference to an object of the class RPC::XML::Method,
RPC::XML::Function 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. 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_procedure and get_function calls are provided for symmetry. All
will return the same object for NAME, regardless of the underlying type.
- 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 are no symmetric calls in this case. The provided API is
implemented as methods, and thus only this interface is provided.
- add_methods_in_dir(DIR [, DETAILS])
-
- add_procedures_in_dir(DIR [, DETAILS])
-
- add_functions_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_procedures_in_dir and add_functions_in_dir are provided for symmetry.
- share_methods(SERVER, NAMES)
-
- share_procedures(SERVER, NAMES)
-
- share_functions(SERVER, NAMES)
-
The calling server object shares the methods/procedures/functions 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
reference). Both objects will reference the same exact RPC::XML::Procedure
(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_procedures and share_functions calls are provided for symmetry.
- copy_methods(SERVER, NAMES)
-
- copy_procedures(SERVER, NAMES)
-
- copy_functions(SERVER, NAMES)
-
These behave like the methods share_* 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_procedures and copy_functions are 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 remote procedures be explicitly published in one
of the several ways provided. Procedures may be added directly within code by
using add_procedure/add_method/add_function as described above, with
full data provided for the code reference, signature list, etc. The
add_* 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.
There are three types of procedures that RPC::XML::Server marshalls calls
to. All are provided by the RPC::XML::Procedure module. You should not
need to load or reference this module directly, as loading RPC::XML::Server
(or a derivative) makes it available. The three types are:
- Methods (RPC::XML::Method)
-
Code that is considered a ``method'' by the server is called as though it were,
in fact, a method in that class. The first argument in the list is the server
object itself, with the arguments to the call making up the rest of the list.
The server checks the signature of the method against the arguments list
before the call is made. See below (How Procedures Are Called) for more
on the invocation of code as methods.
- Procedures (RPC::XML::Procedure)
-
Code that is considered a ``procedure'' by the server is called like a normal
(non-method) subroutine call. The server object is not injected into the
arguments list. The signature of the procedure is checked again the list of
arguments before the call is made, as with methods.
- Functions (RPC::XML::Function)
-
Lastly, code that is considered a ``function'' is the simplest of the three:
it does not have the server object injected into the arguments list, and no
check of signatures is done before the call is made. It is the responsibility
of the function to properly understand the arguments list, and to return a
value that the caller will understand.
There is (currently) no version that is called like a method but ignores
signatures like a function.
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 ``function'', 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.
- signaturesignature
-
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.
- peerfamily
-
This is the address family,
AF_INET or AF_INET6, of a network address of
the client that has connected and made the current request. It is required
for unpacking peeraddr properly.
- peeraddr
-
This is the address part of a packed SOCKADDR_IN or SOCKADDR_IN6
structure, as returned by Socket/pack_sockaddr_in or
Socket/pack_sockaddr_in6, 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. Apply Socket/inet_ntop to
peerfamily and this value to obtain textual representation of the address.
- 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
-
This is the port of the remote (client) end of the socket, taken from the
SOCKADDR_IN structure.
- request
-
The HTTP::Request object for this request. Can be used to read
HTTP headers sent by the client (
X-Forwarded-For for your access checks, for
example).
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 (unless the
XPL specifies a namespace, see RPC::XML::Procedure). 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,
independent 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:
- 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.
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 threshold in
size (the default threshold 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 threshold 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.
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 threshold 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 threshold, if the uncompressed size exceeds the threshold.
- message_file_threshmessage_file_thresh
-
- message_temp_dirmessage_temp_dir
-
These methods may be used to retrieve or alter the values of the given keys
as defined earlier for the
new method.
Previous versions of this library had a very loosely-organized set of fault
codes that a server might return in certain (non-fatal) error circumstances.
This has been replaced by a more configurable, adjustable system to allow
users to better integrate the server-defined faults with any that their
application may produce. It also allows for the definition of additional
fault types so that the same mechanism for formatting the pre-defined faults
can be used within sub-classes and user applications.
The server method server_fault is used to generate RPC::XML::fault
objects for these situations. It takes one or two arguments, the first being
the name of the type of fault to create and the second being the specific
message. If a fault is defined with a static message, the second argument may
be skipped (and will be ignored if passed).
In addition to defining their own faults, a user may override the definition
of any of the server's pre-defined faults.
The user may define their own faults using the fault_table argument to the
constructor of the server class being instantiated. They may also override
any of the pre-defined faults (detailed in the next section) by providing a
new definition for the name.
The value of the fault_table argument is a hash reference whose keys are
the names of the faults and whose values are one of two types:
- An integer
-
If the value for the key is a scalar, it is assumed to be an integer and will
be used as the fault code. When the fault is created, the message argument
(the second parameter) will be used verbatim as the fault message.
- A 2-element list reference
-
If the value is a list reference, it is assumed to have two elements: the first
is the integer fault code to use, and the second is a message ``template''
string to use as the fault message. If the string contains the sequence
%s,
this will be replaced with the message argument (the second parameter) passed
to server_fault. If that sequence is not in the string, then the fault
message is considered static and the message argument is ignored.
An example of defining faults:
my $server = RPC::XML::Server->new(
...
fault_table => {
limitexceeded => [ 500 => 'Call limit exceeded' ],
accessdenied => [ 600 => 'Access denied: %s' ],
serviceclosed => 700
},
...
);
In this example, the fault-type ``limitexceeded'' is defined as having a fault
code of 500 and a static message of Call limit exceeded. The next fault
defined is ``accessdenied'', which has a code of 600 and message that starts
with Access denied: and incorporates whatever message was passed in to the
fault creation. The last example defines a fault called serviceclosed that
has a code of 700 and uses any passed-in message unaltered.
The RPC::XML::Server class defines the following faults and uses them
internally. You can override the codes and messages for these by including them
in the table passed as a fault_table argument. The faults fall into three
groups:
- Request Initialization
-
Faults in this group stem from the initialization of the request and the
parsing of the XML. The codes for this group fall in the range 100-199.
- Method Resolution
-
This group covers problems with mapping the request to a known method or
function on the server. These codes will be in the range 200-299.
- Execution
-
Lastly, these faults are for problems in actually executing the requested
code. Their codes are in the range 300-399.
The faults, and the phases they apply to, are:
- badxml (Request Initialization)
-
This fault is sent back to the client when the XML of the request did not
parse as a valid XML-RPC request.
The code is 100, and the message is of the form, XML parse error: %s.
The specific error from the XML parser is included in the message.
- badmethod (Method Resolution)
-
This fault is sent when the requested method is unknown to the server. No
method has been configured on the server by that name.
The code is 200, and the message is of the form, Method lookup error: %s.
The name of the method and other information is included in the message.
- badsignature (Method Resolution)
-
If a method is known on the server, but there is no signature that matches the
sequence of arguments passed, this fault is returned. This fault cannot be
triggered by server-side code configured via RPC::XML::Function, as no
signature-checking is done for those.
The code is 201, and the message is of the form, Method signature error:
%s. The name of the method and the signature of the arguments is included in
the message.
- execerror (Execution)
-
This fault relates back to the client any exception thrown by the remote code
during execution. If the invoked code returned their error in the form of a
RPC::XML::fault object, that fault is returned instead. Otherwise, the
value of
$@ is used in the message of the fault that gets generated.
The code is 300, and the message is of the form, Code execution error:
%s. The actual text of the exception thrown is included in the message.
There is one special server-fault whose code and message cannot be overridden.
If a call is made to server_fault for an unknown type of fault, the
returned object will have a code of -1 and a message stating that the
fault-type is unknown. The message will include both the requested type-name
and any message (if any) that was passed in.
If you just want to ``move'' the range of codes that the server uses out of the
way of your application's own faults, this can be done with the
fault_code_base parameter when constructing the server object. The value
of the parameter must be an integer, and it is added to the value of all
existing fault codes. For example, a value of 10000 would make the code
for the badxml fault be 10100, the code for badmethod be 10200,
etc.
This is applied before any user-defined faults are merged in, so their code
values will not be affected by this value.
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.
Please report any bugs or feature requests to
bug-rpc-xml at rt.cpan.org, or through the web interface at
http://rt.cpan.org/NoAuth/ReportBug.html. I will be
notified, and then you'll automatically be notified of progress on
your bug as I make changes.
This file and the code within are copyright (c) 2011 by Randy J. Ray.
Copying and distribution are permitted under the terms of the Artistic
License 2.0 (http://www.opensource.org/licenses/artistic-license-2.0.php) or
the GNU LGPL 2.1 (http://www.opensource.org/licenses/lgpl-2.1.php).
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.
RPC::XML, RPC::XML::Client,
RPC::XML::ParserFactory
Randy J. Ray <rjray@blackperl.com>
|