Provided by: librpc-xml-perl_0.79-1_all bug

NAME

       RPC::XML::Server - A server base-class for XML-RPC

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 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.

SUBROUTINES/METHODS

       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::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 threshhold, 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)
           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.

           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 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 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_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])
           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 refernce). 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 Server-Side Remote Procedures
       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.

   The Three Types of Procedures
       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.

   How Procedures 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 "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.

       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
           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 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.

   Server Faults
       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.

       Defining 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.

       Server-defined faults

       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.

       Adjusting the server-defined codes

       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.

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.

BUGS

       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?Queue=RPC-XML>. I will be
       notified, and then you'll automatically be notified of progress on your bug as I make
       changes.

SUPPORT

       ·   RT: CPAN's request tracker

           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=RPC-XML>

       ·   AnnoCPAN: Annotated CPAN documentation

           <http://annocpan.org/dist/RPC-XML>

       ·   CPAN Ratings

           <http://cpanratings.perl.org/d/RPC-XML>

       ·   Search CPAN

           <http://search.cpan.org/dist/RPC-XML>

       ·   MetaCPAN

           <https://metacpan.org/release/RPC-XML>

       ·   Source code on GitHub

           <http://github.com/rjray/rpc-xml>

LICENSE AND COPYRIGHT

       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>).

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.

SEE ALSO

       RPC::XML, RPC::XML::Client, RPC::XML::ParserFactory

AUTHOR

       Randy J. Ray "<rjray@blackperl.com>"